# Alarms

An alarm is a set of data that signifies an event. It's Firewalla's core features that summarizes stuff that needs attention so users can better understand and protect their network.

## Get Alarms

This API gets all alarms within current MSP.

[!badge variant="primary" text="GET"] <span style="color:grey">https://msp_domain</span>**/v2/alarms**

<p class="header">Header</p>

| Name                                                       | Value                 |
| ---------------------------------------------------------- | --------------------- |
| Authorization <span style="color:orange">*required*</span> | Personal access token |

<p class="header">Query String</p>

Name        | Value
---         | ---
query       | The search query. See [Query basics](./search.md#alarm-qualifiers)
groupBy     | Grouping the alarms based on the  given values. A comma-separated list. e.g., `type,box`
sortBy      | Sorting the alarms based on the given values. A comma-separated list. e.g., `ts:desc,total:asc`. Defaults to `ts:desc`
limit <span style="color:grey"><=500</span> | Max number of results being returned. Defaults to `200`
cursor | See [Pagination](./search.md#pagination)

<p class="response">Response</p>

<p class="statusCode"><svg class="green" viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>200 Success</span>

</p>

Name      | Type    | Description
---       | ---     | ---
`count`   | Number  | Number of results in the response
`results` | [Alarm](../data-models/alarm.md/#alarm)[] | List of alarms being returned, its length is always no more than the `limit` specified in the request
`next_cursor` | String | See [Pagination](./search.md#pagination)

```json
{
    "count": 1,
    "results": [
        {
            "aid": 1,
            "type": 5,
            "message": "Found a new device iPhone connected to your network.",
            "ts": 1664522841.895,
            "gid": "00000000-0000-0000-0000-000000000000"
        }
    ],
    "next_cursor": null
}
```

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>401 Permission Denied</span>
</p>

<p class="examples">Examples</p>

- [Get-Active-Alarms-By-Specific-Box](https://github.com/firewalla/msp-api-examples/tree/main/get-active-alarms-by-specific-box), `Query String` `Pagination`

## Get An Alarm

This API gets a specific alarm.

[!badge variant="primary" text="GET"] <span style="color:grey">https://msp_domain</span>**/v2/alarms/:gid/:aid**

<p class="header">Header</p>

| Name                                                       | Value                 |
| ---------------------------------------------------------- | --------------------- |
| Authorization <span style="color:orange">*required*</span> | Personal access token |

<p class="header">Path</p>

| Name                                             | Value    |
| ------------------------------------------------ | -------- |
| gid <span style="color:orange">*required*</span> | Box ID   |
| aid <span style="color:orange">*required*</span> | Alarm ID |

<p class="response">Response</p>

<p class="statusCode"><svg class="green" viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>200 Success</span>

</p>

A JSON representation of [Alarms](../data-models/alarm.md/#alarm)

```json
{
    "aid": 1,
    "type": 5,
    "message": "Found a new device iPhone connected to your network.",
    "ts": 1664522841.895,
    "gid": "00000000-0000-0000-0000-000000000000",
    "device": {
        "name": "iPhone",
        "id": "AA:BB:CC:DD:EE:FF",
        "ip": "192.168.1.2",
        "network": {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Lan 1"
        },
        "group": {
            "id": "1",
            "name": "Guest"
        }
    }
}
```

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>401 Permission Denied</span>
</p>

<p class="examples">Examples</p>

+++ Node.js
```js
// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";
const gid = "00000000-0000-0000-0000-000000000000";
const aid = 1;

axios({
    method: "get",
    url: `https://${msp_domain}/v2/alarms/${gid}/${aid}`,
    headers: {
        "Authorization": `Token ${token}`
    }
}).then(res => {
    console.log(res.data);
})
```
+++ cURL
```bash
curl --request GET  \
--url "https://${msp_domain}/v2/alarms/${gid}/${aid}" \
--header "Authorization: Token ${your_personal_access_token}"
```
+++

## Delete An Alarm
This API deletes an existing alarm.

[!badge variant="primary" text="DELETE"] <span style="color:grey">https://msp_domain</span>**/v2/alarms/:gid/:aid**

<p class="header">Header</p>

| Name                                                       | Value                 |
| ---------------------------------------------------------- | --------------------- |
| Authorization <span style="color:orange">*required*</span> | Personal access token |

<p class="header">Path</p>

| Name                                             | Value    |
| ------------------------------------------------ | -------- |
| gid <span style="color:orange">*required*</span> | Box ID   |
| aid <span style="color:orange">*required*</span> | Alarm ID |

<p class="response">Response</p>

<p class="statusCode"><svg class="green" viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>200 Success</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>401 Permission Denied</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>404 Not Found</span>
</p>

<p class="examples">Examples</p>

+++ Node.js
```js
// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";
const gid = "00000000-0000-0000-0000-000000000000";
const aid = 1;

axios({
    method: "delete",
    url: `https://${msp_domain}/v2/alarms/${gid}/${aid}`,
    headers: {
        "Authorization": `Token ${token}`
    }
}).then(res => {
    console.log(res.data);
})
```
+++ cURL
```bash
curl --request DELETE  \
--url "https://${msp_domain}/v2/alarms/${gid}/${aid}" \
--header "Authorization: Token ${your_personal_access_token}"
```
+++

## Archive An Alarm [!badge variant="warning" text="MSP 2.11.0 or later"]
This API archives an existing alarm. The alarm is moved to the archived state and no longer appears among active alarms. Unlike muting, archiving does not create a silence exception, so future traffic matching this alarm can still trigger new alarms.

[!badge variant="primary" text="POST"] <span style="color:grey">https://msp_domain</span>**/v2/alarms/:gid/:aid/archive**

<p class="header">Header</p>

| Name                                                       | Value                 |
| ---------------------------------------------------------- | --------------------- |
| Authorization <span style="color:orange">*required*</span> | Personal access token |

<p class="header">Path</p>

| Name                                             | Value    |
| ------------------------------------------------ | -------- |
| gid <span style="color:orange">*required*</span> | Box ID   |
| aid <span style="color:orange">*required*</span> | Alarm ID |

<p class="response">Response</p>

<p class="statusCode"><svg class="green" viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>200 Success</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>401 Permission Denied</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>404 Not Found</span>
</p>

<p class="examples">Examples</p>

+++ Node.js
```js
// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";
const gid = "00000000-0000-0000-0000-000000000000";
const aid = 1;

axios({
    method: "post",
    url: `https://${msp_domain}/v2/alarms/${gid}/${aid}/archive`,
    headers: {
        "Authorization": `Token ${token}`
    }
}).then(res => {
    console.log(res.data);
})
```
+++ cURL
```bash
curl --request POST  \
--url "https://${msp_domain}/v2/alarms/${gid}/${aid}/archive" \
--header "Authorization: Token ${your_personal_access_token}"
```
+++

## Mute An Alarm [!badge variant="warning" text="MSP 2.11.0 or later"]
This API mutes an alarm. It archives the alarm and instructs the box to create a silence exception so that future traffic matching this alarm will no longer trigger new alarms.

[!badge variant="primary" text="POST"] <span style="color:grey">https://msp_domain</span>**/v2/alarms/:gid/:aid/mute**

<p class="header">Header</p>

| Name                                                       | Value                 |
| ---------------------------------------------------------- | --------------------- |
| Authorization <span style="color:orange">*required*</span> | Personal access token |

<p class="header">Path</p>

| Name                                             | Value    |
| ------------------------------------------------ | -------- |
| gid <span style="color:orange">*required*</span> | Box ID   |
| aid <span style="color:orange">*required*</span> | Alarm ID |

<p class="header">Body</p>

| Name | Type | Description |
| ---- | ---- | ----------- |
| `target` | [Mute Target](../data-models/alarm.md/#mute-target) <span style="color:orange">*required*</span> | What to silence |
| `scope` | [Mute Scope](../data-models/alarm.md/#mute-scope) <span style="color:orange">*required*</span> | Which devices this silence applies to |

<p class="response">Response</p>

<p class="statusCode"><svg class="green" viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>200 Success</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>400 Bad Request</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>401 Permission Denied</span>
</p>

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>404 Not Found</span>
</p>

<p class="examples">Examples</p>

+++ Node.js
```js
// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";
const gid = "00000000-0000-0000-0000-000000000000";
const aid = 1;

// Mute by alarm type on all devices
axios({
    method: "post",
    url: `https://${msp_domain}/v2/alarms/${gid}/${aid}/mute`,
    headers: {
        "Authorization": `Token ${token}`,
        "Content-Type": "application/json"
    },
    data: {
        target: { type: "alarmType" },
        scope: { type: "all" }
    }
}).then(res => {
    console.log(res.data);
})

// Mute a specific destination on all devices
axios({
    method: "post",
    url: `https://${msp_domain}/v2/alarms/${gid}/${aid}/mute`,
    headers: {
        "Authorization": `Token ${token}`,
        "Content-Type": "application/json"
    },
    data: {
        target: { type: "domain", value: "example.com" },
        scope: { type: "all" }
    }
}).then(res => {
    console.log(res.data);
})

// Mute a specific destination for one device
axios({
    method: "post",
    url: `https://${msp_domain}/v2/alarms/${gid}/${aid}/mute`,
    headers: {
        "Authorization": `Token ${token}`,
        "Content-Type": "application/json"
    },
    data: {
        target: { type: "domain", value: "example.com" },
        scope: { type: "device", value: "AA:BB:CC:DD:EE:FF" }
    }
}).then(res => {
    console.log(res.data);
})
```
+++ cURL
```bash
# Mute by alarm type on all devices
curl --request POST  \
--url "https://${msp_domain}/v2/alarms/${gid}/${aid}/mute" \
--header "Authorization: Token ${your_personal_access_token}" \
--header "Content-Type: application/json" \
--data '{"target":{"type":"alarmType"},"scope":{"type":"all"}}'

# Mute a specific destination on all devices
curl --request POST  \
--url "https://${msp_domain}/v2/alarms/${gid}/${aid}/mute" \
--header "Authorization: Token ${your_personal_access_token}" \
--header "Content-Type: application/json" \
--data '{"target":{"type":"domain","value":"example.com"},"scope":{"type":"all"}}'

# Mute a specific destination for one device
curl --request POST  \
--url "https://${msp_domain}/v2/alarms/${gid}/${aid}/mute" \
--header "Authorization: Token ${your_personal_access_token}" \
--header "Content-Type: application/json" \
--data '{"target":{"type":"domain","value":"example.com"},"scope":{"type":"device","value":"AA:BB:CC:DD:EE:FF"}}'
```
+++