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.

GET https://msp_domain/v2/alarms

Name	Value
Authorization required	Personal access token

Name	Value
query	The search query. See Query basics
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 <=500	Max number of results being returned. Defaults to `200`
cursor	See Pagination

Response

200 Success

Name	Type	Description
`count`	Number	Number of results in the response
`results`	Alarm[]	List of alarms being returned, its length is always no more than the `limit` specified in the request
`next_cursor`	String	See Pagination

{
    "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
}

401 Permission Denied

Examples

Get-Active-Alarms-By-Specific-Box, Query String Pagination

Get An Alarm

This API gets a specific alarm.

GET https://msp_domain/v2/alarms/:gid/:aid

Name	Value
Authorization required	Personal access token

Name	Value
gid required	Box ID
aid required	Alarm ID

Response

200 Success

A JSON representation of Alarms

{
    "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"
        }
    }
}

401 Permission Denied

Examples

// 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 --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.

DELETE https://msp_domain/v2/alarms/:gid/:aid

Name	Value
Authorization required	Personal access token

Name	Value
gid required	Box ID
aid required	Alarm ID

Response

200 Success

401 Permission Denied

404 Not Found

Examples

// 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 --request DELETE  \
--url "https://${msp_domain}/v2/alarms/${gid}/${aid}" \
--header "Authorization: Token ${your_personal_access_token}"

Archive An Alarm 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.

POST https://msp_domain/v2/alarms/:gid/:aid/archive

Name	Value
Authorization required	Personal access token

Name	Value
gid required	Box ID
aid required	Alarm ID

Response

200 Success

401 Permission Denied

404 Not Found

Examples

// 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 --request POST  \
--url "https://${msp_domain}/v2/alarms/${gid}/${aid}/archive" \
--header "Authorization: Token ${your_personal_access_token}"

Mute An Alarm 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.

POST https://msp_domain/v2/alarms/:gid/:aid/mute

Name	Value
Authorization required	Personal access token

Name	Value
gid required	Box ID
aid required	Alarm ID

Name	Type	Description
`target`	Mute Target required	What to silence
`scope`	Mute Scope required	Which devices this silence applies to

Response

200 Success

400 Bad Request

401 Permission Denied

404 Not Found

Examples

// 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);
})

# 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"}}'