Alarms

Alarms are conditions defined on a tag. These routes manage definitions and act on outstanding alarms. Live alarm frames (alarm.active, alarm.acknowledged, ...) arrive over the socket; see Live data over /sync. Background in Alarms.

Routes

Method and path	Role	Purpose
GET /api/v1/tags/{tagId}/alarms	viewer	The tag's alarm definitions with their live state
POST /api/v1/tags/{tagId}/alarms	engineer	Add an alarm to a tag
GET /api/v1/alarms	viewer	Every alarm definition on the gateway
GET /api/v1/alarms/active	viewer	Everything outstanding, most severe first
GET /api/v1/alarms/history	viewer	Lifecycle events, newest first, paged
GET /api/v1/alarms/{id}	viewer	One alarm
PUT /api/v1/alarms/{id}	engineer	Replace a definition
DELETE /api/v1/alarms/{id}	engineer	Delete a definition
POST /api/v1/alarms/{id}/acknowledge	operator	Acknowledge, recording who
POST /api/v1/alarms/{id}/shelve	operator	Silence for a duration
POST /api/v1/alarms/{id}/unshelve	operator	End a shelf early

{tagId} accepts a tag id or path.

Definition fields

POST /api/v1/tags/{tagId}/alarms and PUT /api/v1/alarms/{id} take AlarmInput. Every field is optional in the record; the service rejects a definition it cannot evaluate with 400.

Field	Type	Meaning
name	string	Display name
severity	integer	Higher is more severe; the active list sorts by it
condition	string	greater, less, equal or notEqual
setpoint	number	The value compared against
deadband	number	Hysteresis around the setpoint
onDelayMs	integer	Milliseconds the condition must hold before the alarm goes active
enabled	boolean	A disabled alarm is not evaluated

condition	Active when	Clears when
greater	value > setpoint	value <= setpoint − deadband
less	value < setpoint	value >= setpoint + deadband
equal	value = setpoint, exactly	value is further than deadband from setpoint
notEqual	value is further than deadband from setpoint	value is within deadband of setpoint

Alarms defined on a tag type member are inherited by every instance: they show up here with inherited: true and are edited on the type or through the member's overrides, not through PUT/DELETE here. See Tag types.

The alarm object

Every read route and every alarm.* socket frame carries AlarmDto:

{
  "id": "…", "tagId": "…", "tagPath": "Plant.Line1.Temperature",
  "name": "High temperature", "severity": 3, "condition": "greater", "setpoint": 80, "deadband": 2, "onDelayMs": 5000, "enabled": true,
  "state": "active", "occurrenceId": "…",
  "pendingSince": null, "activatedAt": 1762603200000, "acknowledgedAt": null, "acknowledgedBy": null, "acknowledgedByName": null, "clearedAt": null,
  "value": 83.5, "quality": "good", "valueTimestamp": 1762603200000, "stale": false,
  "inherited": false, "shelvedUntil": null
}

All times here are Unix milliseconds. state is one of:

state	Condition	Acknowledged	Outstanding
normal	false		no
active	true	no	yes
acknowledged	true	yes	yes
cleared	false	no	yes

occurrenceId identifies one activation; it changes each time the alarm goes active again. pendingSince is set while an on-delay is running. stale is set when the value's quality stopped the alarm from being evaluated. shelvedUntil is set while the alarm is shelved: it is silenced in presentation but still evaluated.

Acknowledging

POST /api/v1/alarms/{id}/acknowledge with an optional body {"occurrenceId": "…"}. The body may be empty. With an occurrenceId, the acknowledgement applies only if that occurrence is still the current one, so an operator does not acknowledge a newer activation by mistake. The principal's id and name (or email) are recorded as acknowledgedBy / acknowledgedByName. Response 200: the alarm.

Shelving

POST /api/v1/alarms/{id}/shelve body {"durationMs": 3600000} (required, Unix milliseconds of duration). POST /api/v1/alarms/{id}/unshelve has no body. Both return the alarm; both record who did it in history as a shelved or unshelved event.

History

GET /api/v1/alarms/history?alarmId=&tagId=&from=&to=&before=&limit=100

Parameter	Type	Meaning
alarmId	string	Only this alarm
tagId	string	Only alarms on this tag
from, to	Unix ms	Time range
before	Unix ms	Only events older than this; pass the previous page's nextBefore
limit	integer	Page size, default 100

Response:

{
  "events": [
    { "id": 9120, "alarmId": "…", "tagId": "…", "tagPath": "…", "alarmName": "…", "severity": 3, "condition": "greater", "setpoint": 80,
      "occurrenceId": "…", "kind": "active", "value": 83.5, "quality": "good", "valueTimestamp": 1762603200000,
      "principalId": null, "principalName": null, "reason": null, "timestamp": 1762603200000, "shelvedUntil": null }
  ],
  "nextBefore": 1762599600000
}

kind is the lifecycle event: active, acknowledged, cleared, shelved, unshelved and the events the service writes for definition changes. principalId and principalName are set on events a person caused. A shelved event carries shelvedUntil. nextBefore is null on the last page. History is kept for Alarms__EventRetention (default 365 days).

Notable status codes

• 400 for a definition the service refuses, and for acknowledge or shelve on an alarm that has no current occurrence.
• 404 for an unknown alarm or tag.