Alarms API

These routes let a ticket system, an operations centre or a script work with alarms. How alarms behave is explained in Alarms and Working with alarms. Paths are under https://<your host>/tenant/<tenantId>.

Routes

Default roles: reading and acknowledging are User permissions; resolving, muting and changing rules are Admin permissions.

List alarms

GET /api/iot/alarms (pages from 1). Unknown parameters are refused.

A RESOLVED or any list always reads a time range, at most 92 days: “An alarm history range may span at most 92 days.”

{
  "items": [
    {
      "alarmId": "9a7e…",
      "type": "high_temperature",
      "severity": "CRITICAL",
      "status": "OPEN",
      "originator": { "type": "DEVICE", "id": "6f1c…", "name": "cold-room-2" },
      "deviceId": "6f1c…",
      "deviceName": "cold-room-2",
      "profileId": "a1b2…",
      "ruleId": "3c4d…",
      "title": "Temperature too high",
      "details": { "temperature": 9.4 },
      "topic": null,
      "startTs": 1762678800000,
      "openedAt": 1762678800000,
      "acknowledgedAt": null,
      "acknowledgedBy": null,
      "resolvedAt": null,
      "resolvedBy": null,
      "resolveReason": null,
      "occurrences": 3,
      "flapping": false,
      "isAuto": true
    }
  ],
  "total": 1
}

Alarm times are milliseconds since the epoch. resolveReason is clear (its rule or flow cleared it), manual (a person) or originator_deleted (its device was deleted).

GET /api/iot/alarms/{alarmId} answers { "alarm": {...} } with the same fields plus the rule’s runbook. An alarm of another organisation is a 404.

Counts

GET /api/iot/alarms/counts?deviceId={deviceId}

{ "open": 4, "acknowledged": 1, "bySeverity": { "CRITICAL": 1, "MAJOR": 2, "MINOR": 0, "WARNING": 2, "INFO": 0 } }

Only alarms that are not resolved are counted. Leave out deviceId for the whole organisation.

Acknowledge and resolve

{
    "alarmIds": [
        "9a7e…",
        "b81f…"
    ],
    "note": "Technician on the way, ticket INC-4411"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/alarms/acknowledge' \
  -H 'Content-Type: application/json' \
  -d '{"alarmIds":["9a7e…","b81f…"],"note":"Technician on the way, ticket INC-4411"}'

{
    "results": [
        {
            "alarmId": "9a7e…",
            "ok": true
        },
        {
            "alarmId": "b81f…",
            "ok": false,
            "reason": "not_active"
        }
    ]
}

POST /api/iot/alarms/resolve takes the same body and answers the same way. A resolved alarm is final; if the condition is still true, the rule opens a new alarm. Resolving a CRITICAL alarm by hand is written to the audit log.

Add a note without changing the state:

POST /api/iot/alarms/{alarmId}/comments
{ "text": "Spare part ordered" }

The answer is 201 { "ok": true }. Notes appear in the timeline (GET .../events).

Alarm rules

GET /api/iot/alarm-rules/{profileId} answers { "rules": [...] }. PUT replaces the profile’s whole rule set: rules you leave out are deleted, and their open alarms are resolved.

{
  "rules": [
    {
      "type": "high_temperature",
      "title": "Temperature too high",
      "severities": [
        { "severity": "CRITICAL", "condition": { "key": "temperature", "op": ">", "value": { "attribute": "maxTempThreshold" } } },
        { "severity": "WARNING", "condition": { "key": "temperature", "op": ">", "value": 6 } }
      ],
      "debounce": { "mode": "duration", "raise": 300, "clear": 120 },
      "hysteresis": 0.5,
      "notify": { "recipients": [{ "kind": "role", "role": "ADMIN" }], "minSeverity": "WARNING", "repeatEverySec": 3600 },
      "runbook": "Check the door seal, then the compressor."
    },
    {
      "type": "device_offline",
      "title": "Sensor offline",
      "inactivity": { "afterSec": 900, "severity": "WARNING" }
    }
  ]
}

Rules of the schema:

Condition keys are checked against the profile’s keys. The full meaning of each field is in Alarm rules on device profiles and Alarm conditions reference.

Mutes

A mute must end in the future and last at most 90 days. Alarms are still recorded while muted; nobody is notified. See Muting a device for maintenance.

Errors

Events instead of polling

Subscribe a webhook to alarm.created, alarm.acknowledged and alarm.cleared to learn of changes as they happen. Payloads are in the Webhook event reference.