Alarms¶
An alarm watches one value of a device and sends a threshold alert (email, plus SMS/WhatsApp where enabled) when its condition is met. Alarms are evaluated periodically by the server.
All alarm endpoints accept their fields either as query parameters or as a JSON body; when both are given, the query parameter wins. Responses use the standard {"success": ...} / {"failed": ...} envelope.
Device types (device_type):
| Value | Device | Notes |
|---|---|---|
| sensor | Sensor | Numeric threshold |
| switch | Switch | Boolean condition |
| met | Meteorological | Numeric threshold |
| batmon | Battery monitor | Numeric threshold |
| workstation | Workstation | Numeric threshold. ws is not accepted here |
| gps | GPS | Numeric threshold |
| ping / device | Device (ping) | Boolean condition |
| interface / dynamic | Dynamic interface | Numeric threshold |
Conditions (alarm_condition):
| Device type | Allowed values | Meaning |
|---|---|---|
| switch, ping, device | True, False |
Triggers when the device state equals the value |
| all others | =, <, >, <=, >= |
Triggers when current value condition alarm_threshold_value is true, e.g. > with threshold 30 triggers when the value is above 30 |
For boolean conditions alarm_threshold_value is ignored and stored as null.
Condition parameter (condition_parameter): selects which value of the device is compared.
| Device type | Values |
|---|---|
| gps | latitude, longitude, height |
| batmon | voltage, current, power, soc |
| met | temperature, pressure, humidity, precipitation |
| workstation | processor, ram, disk |
| interface / dynamic | Name of one of the interface's fields |
| sensor, switch, ping/device | Not used for the comparison, but still required when adding (e.g. value) |
Repeat delay (alarm_repeat_delay): number of seconds to wait before notifying again while the alarm condition stays true. Use -1 to notify only once (never repeat).
Get alarms¶
/alarmReturns all alarms of the user, or a single alarm
Request¶
Auth: api_key (query param or cookie)
Request body:
| Field name | Description | Type |
|---|---|---|
| alarm_id | [Optional] Return only this alarm. All of the user's alarms are returned if not specified | int |
Request example:
https://spoilerinterface.com/interface/alarm?api_key=8f14e45fceea167a5a36dedd4bea2543&alarm_id=1716549872345
Response¶
{
"success": [
{
"alarm_id": 1716549872345,
"device_id": 301659085216623,
"alarm_name": "High temperature",
"alarm_enabled": true,
"alarm_threshold_value": 30.0,
"alarm_condition": ">",
"alarm_trigger_time": null,
"alarm_repeat_delay": 300,
"alarm_akn": "",
"alarm_triggered": false,
"device_type": "sensor",
"condition_parameter": "value",
"update_time": 1716549872
}
]
}
When the user has no alarms the response is {"success": "No alarms found"}.
Field description¶
| Field name | Description | Type |
|---|---|---|
| alarm_id | Alarm ID | int |
| device_id | ID of the monitored device | int |
| alarm_name | Name of the alarm | str |
| alarm_enabled | Whether the alarm is evaluated | bool |
| alarm_threshold_value | Threshold value (null for boolean conditions) |
float |
| alarm_condition | Condition (see table above) | str |
| alarm_repeat_delay | Seconds between repeated notifications (-1 = never repeat) |
int |
| alarm_triggered | Whether the condition was met at the last evaluation | bool |
| device_type | Device type | str |
| condition_parameter | Compared value (see table above) | str |
| update_time | Last time the alarm was changed (epoch seconds) | int |
Add alarm¶
/add/alarmCreates a new alarm for a device
Request¶
Auth: api_key (query param or cookie) · Content-type: application/json
Request body:
| Field name | Description | Type |
|---|---|---|
| alarm_name | Name of the alarm | str |
| device_id | ID of the device to monitor | int |
| device_type | Device type (see table above) | str |
| alarm_enabled | Whether the alarm is active | bool |
| alarm_condition | Condition (see table above) | str |
| alarm_threshold_value | Threshold value. Not required for switch / ping / device | float |
| condition_parameter | Compared value (see table above) | str |
| alarm_repeat_delay | Seconds between repeated notifications, -1 to notify once |
int |
Request example:
{
"alarm_name": "High temperature",
"device_id": 301659085216623,
"device_type": "met",
"alarm_enabled": true,
"alarm_condition": ">",
"alarm_threshold_value": 30,
"condition_parameter": "temperature",
"alarm_repeat_delay": 300
}
Response¶
Common failures: Missing argument: <name>, Invalid device_type. ..., Incorrect value: Value should be a boolean, Incorrect value: alarm_condition value should be = or < or > or >= or <= .
Note: The new alarm_id is not returned; use Get alarms to find it.
Edit alarm¶
/edit/alarmUpdates an existing alarm
Request¶
Auth: api_key (query param or cookie) · Content-type: application/json
Request body:
Only alarm_id is required; other fields keep their current value when omitted. The monitored device_id cannot be changed. The condition is re-validated against the (new or existing) device_type.
| Field name | Description | Type |
|---|---|---|
| alarm_id | ID of the alarm to edit | int |
| alarm_name | [Optional] New name | str |
| device_type | [Optional] New device type | str |
| alarm_enabled | [Optional] Enable/disable the alarm. When sending a JSON body, always include it: an omitted value is stored as null |
bool |
| alarm_condition | [Optional] New condition | str |
| alarm_threshold_value | [Optional] New threshold value | float |
| condition_parameter | [Optional] New condition parameter | str |
| alarm_repeat_delay | [Optional] New repeat delay in seconds | int |
Request example:
{
"alarm_id": 1716549872345,
"alarm_enabled": true,
"alarm_condition": ">=",
"alarm_threshold_value": 35
}
Response¶
Delete alarm¶
/delete/alarmDeletes an alarm owned by the user
Request¶
Auth: api_key (query param or cookie) · Content-type: application/json
Request body:
| Field name | Description | Type |
|---|---|---|
| alarm_id | ID of the alarm to delete | int |
Request example:
https://spoilerinterface.com/interface/delete/alarm?api_key=8f14e45fceea167a5a36dedd4bea2543&alarm_id=1716549872345
Response¶
Failures: Missing argument: alarm_id, Alarm not found, Not allowed (alarm belongs to another user).
Enable alarm¶
/enable/alarmEnables an alarm
Request¶
Auth: None (identified by alarm_id) · Content-type: application/json
Request body:
| Field name | Description | Type |
|---|---|---|
| alarm_id | ID of the alarm | int |
Request example:
https://spoilerinterface.com/interface/enable/alarm?alarm_id=1716549872345
Response¶
Failures: Missing argument: alarm_id, No alarm with specified alarm ID.
Disable alarm¶
/disable/alarmDisables an alarm
Request¶
Auth: None (identified by alarm_id) · Content-type: application/json
Request body:
| Field name | Description | Type |
|---|---|---|
| alarm_id | ID of the alarm | int |
Request example:
Response¶
Failures: Missing argument: alarm_id, No alarm with specified alarm ID.