v1/alerts
Use the v1/alerts API to create, update, list, and manage alerts for your account. For each alert, specify the alert, the scope for the alert, as well as rules for the alert to fire and reset. The alert scope and fire/reset rules vary depending on the alert type.
In the classic Remote Manager interface and pre-v1 APIs, alerts are called alarms, and the two terms are synonymous. Going forward, Digi recommends you use the /v1/alerts API rather than the pre-v1 Alarm APIs to manage alerts.
URI
https://<hostname>/ws/v1/alerts
Formats
| HTTP method | Format | Description | Parameters |
|---|---|---|---|
| GET | /ws/v1/alerts | Get a summary of the alerts API. | |
| GET | /ws/v1/alerts/summary | Get a summary of alerts. | query |
| GET | /ws/v1/alerts/bulk | List alerts in bulk CSV format. | orderby query fields |
| GET | /ws/v1/alerts/bulk/summary/ws/v1/alerts/bulk/status | Export up to 20,000 rows of CSV data representing the summary or status of any alarm that has been fired and/or reset. | orderby query fields |
| GET | /ws/v1/alerts/inventory | List alerts | cursor orderby size query |
| POST | /ws/v1/alerts/inventory | Create one or more alerts | None |
| GET, PUT, DELETE | /ws/v1/alerts/inventory/{id} | Get a specific alert, modify an existing alert, and delete an alert. | |
| GET | /ws/v1/alerts/history/{alert_id_source} | Get history of fired alerts. | cursor size start_time end_time order |
| GET | /ws/v1/alerts/status | Get current status for alerts. | cursor orderby size query |
| GET | /ws/v1/alerts/summary | Get a summary of all alerts. | cursor orderby size query |
Fields
id
System generated identifier for the alert.
name
String name of the alert.
description
String that describes the alert.
enabled
Boolean indicating if the alert is enabled. Default is true.
fire
The definition of the rule describing conditions for when the alert fires. Not all alerts require a fire rule.
fire.parameters
A map of parameter names and values indicating the conditions required for the alert to fire.
priority
String describing the priority assigned to the alert.
- high
- medium
- low
reset
The definition of the rule describing conditions for when the alert is reset. Not all alerts require a reset rule.
reset.enabled
Boolean indicating if the rule should automatically reset.
reset.parameters
A map of parameter names and values indicating the conditions required for the alert to reset.
scope
The definition of the scope defining how the alert is applied.
scope.type
What type of scope defines how the alert is applied.
- Device: The target of the alert is a specific device.
- Global: The target of the alert is global to the account.
- Group: The target of the alert is a group or all devices in a group.
- Resource: The target of the alert is a resource in the system.
- XBeeNode: The target of the alert is a specific XBee node.
scope.value
The value indicating the scope target depends on the scope.type setting.
| Scope Type | Scope Value |
|---|---|
| Device | The scope.value field is a device id. For example: 00000000-00000000-00000000-00000000 |
| Global | The scope.value field is the empty string. |
| Group | The scope.value field is a group name: For example: Regions/Northwest indicates any devices in the Northwest subgroup of the Regions group. |
| Resource | The scope.value field is the resource identifier. For example a stream name: 00000000-00000000-00000000-00000000/metrics/sys/cpu/used. Can use the wildcard character (*) to include all path components of a stream name, for example */metrics/sys/cpu/used. |
| XBeeNode | The scope.value field is an XBee node extended address. For example: 00:08:A2:A5:6E:4D:52:85 |
type
String that indicates the alert type.
- DataPoint On Change: Fires when a data point is uploaded containing a different value from the previous data point. The scope type of a DataPoint on Change alert is always Resource.
- DataPoint condition: Fires when a data point is uploaded containing a value that matches the specified criteria. The scope type of a DataPoint condition alert is always Resource.
- Device Excessive Disconnects: Fires when devices disconnect with a specified frequency. The scope type of a Device Excessive Disconnects alert is Group or Device.
- Device Name On Change: Fires when a devices name changes. The scope type of a Device Name On Change alert is Group or Device.
- Device Offline: Fires when devices disconnects for a specified time. The scope type of a Device Offline alert is Group or Device.
- Dia channel data point condition match: Fires when a DIA channel data point is uploaded containing a value that matches the specified criteria. The scope type of a Dia channel data point condition match is Group or Device.
- Missing DataPoint: Fires when a new data point is not uploaded for a specified time. The scope type of a Missing DataPoint alert is always Resource.
- Missing DiaChannel DataPoint: Fires when a new DIA channel data point is not uploaded for a specified time. The scope type of a Missing DiaChannel DataPoint alert is Group or Device.
- Missing Smart Energy DataPoint: Fires when a new Smart Energy data point is not uploaded for a specified time. The scope type of a Missing Smart Engergy DataPoint alert is Group, Device, or XBeeNode.
- Smart energy data point condition match: Fires when a Smart Energy data point is uploaded containing a value that matches the specified criteria. The scope type of a Smart energy data point condition match ialert s Group, Device, or XBeeNode.
- Subscription Usage: Fires when the account subscription usage matches the specified criteria. The scope type of a Subscription Usage alert is always Global.
- XBeeNode Excessive Deactivations: Fires when XBee nodes deactivate with a specified frequency. The scope type of an XBeeNode Excessive Deactivations alert is Group, Device ,or XBeeNode.
- XBeeNode Offline: Fires when an XBee node is offline for a specified time. The scope type of an XBeeNode Offline alert is Group, Device, or XBeeNode.