Skip to content

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

GET/alarm

Returns 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

POST/add/alarm

Creates 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

{
    "success": "success"
}

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

POST/edit/alarm

Updates 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

{
    "success": "success"
}

Delete alarm

POST/delete/alarm

Deletes 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

{
    "success": "success"
}

Failures: Missing argument: alarm_id, Alarm not found, Not allowed (alarm belongs to another user).

Enable alarm

POST/enable/alarm

Enables 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

{
    "success": "success"
}

Failures: Missing argument: alarm_id, No alarm with specified alarm ID.

Disable alarm

POST/disable/alarm

Disables 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:

{
    "alarm_id": 1716549872345
}

Response

{
    "success": "success"
}

Failures: Missing argument: alarm_id, No alarm with specified alarm ID.