Alerts API

Alerts have two halves: rules (the things you configure) and events (the things that happen). The two are joined by channel_id.

Rules

A rule is a configuration object attached to a channel. The most basic rule is "stay between ok_min and ok_max". The richer rules add time-of-day windows and severity escalation.

List rules on a channel

GET /v1/channels/chn_a1b2/rules

{
  "data": [
    {
      "id":         "rul_z9y8",
      "channel_id": "chn_a1b2",
      "kind":       "range",
      "ok_min":     -2,
      "ok_max":      8,
      "grace_min":   15,
      "severity":   "alarm",
      "enabled":     true
    }
  ]
}

Create a rule

POST /v1/channels/chn_a1b2/rules
{
  "kind":      "range",
  "ok_min":    -2,
  "ok_max":     8,
  "grace_min": 15,
  "severity":  "alarm"
}

Supported kind values:

• range — value ∈ [ok_min, ok_max]. The default.
• delta — abs(value − previous) ≤ max_delta in interval_s. Useful for "the freezer door must not let temperature rise faster than 0.5 °C per minute".
• derivative — running 1-h rate of change inside [min_rate, max_rate].
• absence — no measurement received for min_interval_s.
• comparison — value compared to another_channel ± offset. Useful for the Legionella supply/return delta.

A channel can have multiple rules; they are evaluated independently. The channel's state is the most severe of all active rule states.

Update a rule

PATCH /v1/rules/rul_z9y8
{ "ok_max": 6 }

Audit-logged. To replay history under the new rule, see POST /v1/sensors/.../recompute.

Time-of-day windows

{
  "kind": "range",
  "ok_min": -2,
  "ok_max":  8,
  "windows": [
    { "rrule": "FREQ=DAILY;BYHOUR=22;BYMINUTE=0", "duration_min": 30, "ok_max": 12 }
  ]
}

rrule is RFC 5545 (the iCalendar recurrence rule format). During each instance, the override values are used in place of the base ones. Use for nightly defrost or planned production windows.

Events

An event is one transition in the channel's state machine: ok → grace → alarm → acknowledged → cleared. Events are persisted; the chart's red bars derive from the event log.

List events

GET /v1/channels/chn_a1b2/events?from=…&to=…

{
  "data": [
    {
      "id":          "evt_4f3c",
      "channel_id":  "chn_a1b2",
      "rule_id":     "rul_z9y8",
      "kind":        "alarm_opened",
      "severity":    "alarm",
      "opened_at":   "2026-05-17T08:10:00Z",
      "value_at":     11.2,
      "thresholds":  { "ok_min": -2, "ok_max": 8 }
    },
    {
      "id":          "evt_4f3d",
      "channel_id":  "chn_a1b2",
      "rule_id":     "rul_z9y8",
      "kind":        "alarm_ack",
      "ack_at":      "2026-05-17T08:14:30Z",
      "ack_by":      "ops@cafe-bratislava.sk",
      "ack_note":    "Door propped open during delivery; closed."
    },
    {
      "id":          "evt_4f3e",
      "channel_id":  "chn_a1b2",
      "rule_id":     "rul_z9y8",
      "kind":        "alarm_cleared",
      "cleared_at":  "2026-05-17T08:25:00Z",
      "value_at":     6.1
    }
  ]
}

kind values:

• alarm_opened — channel entered alarm (after grace expired).
• alarm_ack — an operator acknowledged with a note.
• alarm_cleared — value returned to in-range.
• silence_opened / silence_closed — operator-scheduled silence windows.
• device_offline / device_online — connection state transitions.

Acknowledge an alarm

POST /v1/events/evt_4f3c/ack
{ "note": "Door propped open during delivery; closed." }

Issues an alarm_ack event. The acknowledger identity comes from the session or the ua_live_ token used.

Replay / recompute

If you change a rule and want to recompute past events under the new rule, call the channel-level recompute (see Sensors API). Events emitted by the previous rule are preserved; new events from the recompute are tagged origin = "recompute" so an auditor can distinguish them.