### Alarm
Alarm is a very diverse data type, as there are many different types of alarms. [Alarm Type](#alarm-type) can be used to determine which properties you should expect belong to one alarm.

| Name         | Type                    | Description                                                    |
| ------------ | ----------------------- | -------------------------------------------------------------- |
| `ts`         | Number                  | A Unix timestamp that shows the time this alarm was generated |
| `gid`        | String                  | Unique identifier of the Firewalla box that raised this alarm |
| `aid`        | Number                  | Unique identifier of the alarm |
| `type`       | [Alarm Type](#alarm-type) | Alarm Type |
| `status`     | [Alarm Status](#alarm-status) | Alarm Status |
| `message`    | String                  | A readable description of what this alarm is about |
| `device`     | [Device](#device)       | Detailed information about the monitoring device involved in this alarm. <br /> Available when `type != 4` |
| `remote`     | [Remote](#remote)       | Detailed information about the remote host involved in this alarm <br /> Available when `type in [1,2,8,9,10,16]` |
| `direction`  | String                  | Direction of the alarm, `inbound` for inbound, `outbound` for outbound, or `local` for local traffic |
| `transfer`   | [Transfer](#transfer)   | Detailed information about data being transferred over the related period of time <br /> Available when `type in [2,3,4,16]` |
| `dataPlan`   | [Data Plan](#data-plan)   | Detailed information about the data plan being exceeded <br /> Available when `type == 4` |
| `vpn`        | [VPN](#vpn)             | Detailed information about the VPN client profile which has experienced a connection status change <br /> Available when `type in [11,12,13]` |
| `port`       | [Port](#port)           | Detailed information about the port being opened <br /> Available when `type == 14` |
| `wan`        | [WAN](#wan)             | Detailed information about Internet connectivity <br /> Available when `type == 15` |
| `protocol`   | String                  | Transport protocol of this alarm, either `tcp` or `udp` |

### Alarm Type

| Number | Alarm Type                    |
| ----   | ------------------------------ |
| 1      | Security Activity              |
| 2      | Abnormal Upload                |
| 3      | Large Bandwidth Usage          |
| 4      | Monthly Data Plan              |
| 5      | New Device                      |
| 6      | Device Back Online             |
| 7      | Device Offline                 |
| 8      | Video Activity                 |
| 9      | Gaming Activity                |
| 10     | Porn Activity                  |
| 11     | VPN Activity                   |
| 12     | VPN Connection Restored        |
| 13     | VPN Connection Error           |
| 14     | Open Port                      |
| 15     | Internet Connectivity Update   |
| 16     | Large Upload                   |

### Alarm Status

| Number | Alarm Status                    |
| ----   | ------------------------------ |
| 1      | `active`                        |
| 2      | `archived`                      |

### Device

| Name      | Type                      | Description        |
| --------- | ------------------------- | ------------------ |
| `id`      | [Device ID](./device.md/#device-id) | This device's unique identifier |
| `ip`      | String                    | Device IP address |
| `name`    | String                    | Device display name |
| `port`    | Number[] <span style="color:gray">*optional*</span> | Ports being used on the device. |
| `lastActive` | Number <span style="color:gray">*optional*</span> | A Unix timestamp that states the last time the specific device was active <br /> Available when `type == device_offline` |
| `network` | [Network](./device.md/#network) | Network that this device was connected to when alarm was raised |
| `group`   | [Group](./device.md/#group) <span style="color:gray">*optional*</span> | Group that this device belonged to when alarm was raised |

### Remote

| Name        | Type                      | Description |
| ----------- | ------------------------- | ----------- |
| `ip`        | String                    | Remote host IP address |
| `domain`    | String <span style="color:gray">*optional*</span> | Remote host domain name |
| `rootDomain`| String <span style="color:gray">*optional*</span> | Remote host domain name that does not include any subdomains |
| `region`    | String <span style="color:gray">*optional*</span> | Region of the remote IP, a 2-letter [ISO 3166 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) |
| `category`  | [Category](#category) <span style="color:gray">*optional*</span> | Remote host category, based on Firewalla cloud intel |
| `port`      | Number[] <span style="color:gray">*optional*</span> | Ports being used on the remote host |

### Category

| Possible Values                                                                                 |
| ----------------------------------------------------------------------------------------------- |
| `ad` `edu` `games` `gamble` `intel` `p2p` `porn` `private` `social` `shopping` `video` `vpn` |

### Transfer

| Name        | Type                                | Description |
| ----------- | ----------------------------------- | ----------- |
| `total`     | Number                              | Total amount of data transferred in bytes |
| `percentage`| Number <span style="color:gray">*optional*</span> | Percentage of all bandwidth or data plan |
| `upload`    | Number <span style="color:gray">*optional*</span> | Total amount of data uploaded in bytes |
| `download`  | Number <span style="color:gray">*optional*</span> | Total amount of data downloaded in bytes |
| `duration`  | Number <span style="color:gray">*optional*</span> | Total time span of the transfer in seconds |
| `stats`     | A JSON array of [Stat](#stat) <span style="color:gray">*optional*</span> | A series of time-value pairs that show a chart of data transferred over time |

### Data Plan

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `quota` | Number | Quota of this data plan in bytes |
| `begin` | Number | A Unix timestamp that shows the beginning time of this data plan |
| `end`   | Number | A Unix timestamp that shows the ending time of this data plan |

### VPN

| Name          | Type      | Description                           |
| ------------- | --------- | ------------------------------------- |
| `id`          | String    | VPN profile unique ID |
| `name`        | String    | VPN profile display name |
| `type`        | String    | VPN type, `ovpn` for OpenVPN or `wg` for WireGuard |
| `subType`     | String    | VPN connection type, `cs` for Remote Access VPN or `s2s` for Site to Site VPN |
| `deviceCount` | Number    | Number of devices that's currently set for using this VPN |
| `strict`      | Boolean   | Whether a kill switch has been enabled on this VPN |

### Port
| Name          | Type   | Description   |
| ------------- | ------ | ------------- |
| `devicePort`  | Number | Port on the device that was opened |
| `protocol`    | String | Protocol associated with device port |
| `publicPort`  | Number | Port on the WAN that was opened |
| `description` | String | Description of this open port, only available if it was opened by [UPnP](https://en.wikipedia.org/wiki/Universal_Plug_and_Play) |

### WAN
| Name          | Type                    | Description   |
| ------------- | ----------------------- | ------------- |
| `name`        | String   | Name of the WAN interface that triggers the alarm |
| `status`      | Number   | WAN connectivity status, possible values: `1` for `connected`,`2` for `standby`, `3` for `disconnected` |
| `active`      | String[] | WAN network names that were active when the alarm was raised |
| `switched`    | Boolean  | Whether WAN switch-over happened when the alarm was raised. If alarm is triggered by backup WAN in failover mode, switch-over won’t happen |
| `type`        | String   | The dual WAN type, i.e., `primary_standby` or `load_balance` |
| `ready`       | Boolean  | WAN connectivity status of the WAN interface that triggers the alarm |

### Stat

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| `ts`       | Number | A Unix timestamp |
| `download` | Number | Data downloaded in bytes |
| `upload`   | Number | Data uploaded in bytes |

### Mute Scope

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `type`  | String | Scope type, possible values: `device` `group` `user` `network` `all` |
| `value` | String <span style="color:gray">*optional*</span> | Scope descriptor, see [Mute Scope Type And Value Mapping](#mute-scope-type-and-value-mapping). Not used when `type` is `all` |

### Mute Scope Type And Value Mapping

| `type` | `value` | Description |
| ------- | ------- | ----------- |
| `device` | device ID | Applies to a specific device |
| `group` | group ID | Applies to all devices in a group |
| `network` | network ID | Applies to all devices in a network |
| `user` | user ID | Applies to all devices belonging to a user |
| `all` | — | Applies to all devices on the box |

### Mute Target

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `type`  | String | Type of target to silence, possible values: `alarmType` `domain` `ip` |
| `value` | String <span style="color:gray">*optional*</span> | Target descriptor, see [Mute Target Type And Value Mapping](#mute-target-type-and-value-mapping). Required when `type` is `domain` or `ip` |

### Mute Target Type And Value Mapping

| `type` | `value` | Description |
| -------- | ------- | ----------- |
| `alarmType` | — | Explicitly silences all future alarms of the same type, regardless of destination. Use this to mute by alarm category rather than a specific host |
| `domain` | domain name | Silences all future alarms matching this domain. Wildcard matching is applied automatically, e.g. `example.com` also matches `sub.example.com` |
| `ip` | IP address | Silences all future alarms matching this IP address, e.g. `1.2.3.4` |