Alarms

Base URL: $BUSINESS_API

The object

idstring · optional
rule_idstring · optional
sensor_idstring · optional
sample_idstring · optional
titlestring · optional
severitystring · optional
event_typestring · optional
statusstring · optional

one of open, acknowledged, resolved

valuenumber · optional
peak_valuenumber · optional
unitstring · optional
opened_atstring (date-time) · optional
last_observed_atstring (date-time) · optional
acknowledged_atstring (date-time) · optional
acknowledged_bystring · optional
resolved_atstring (date-time) · optional
resolution_notesstring · optional
resolution_codestring · optional

Stable code of a resolution the server wrote (alarm.auto_cleared); clients word it and fall back to resolution_notes. Absent for notes people typed.

The object
{
  "id": "ala_2NbIUPJ8YXJkm1LiQVXgqjxIYd7",
  "rule_id": "rul_2aARlSaHxSk1Z6Yp9aKdnemXRyk",
  "sensor_id": "sen_28o3p46TDQsRdq8pzycV5cIxbMg",
  "sample_id": "sam_2U07jOAhTYQNV60Pd6W5x8IZHUU",
  "title": "Fuga na Rua 3",
  "severity": "severity",
  "event_type": "event type",
  "status": "open",
  "value": 13.42,
  "peak_value": 13.42,
  "unit": "unit",
  "opened_at": "2026-11-19T09:30:00Z",
  "last_observed_at": "2026-11-19T09:30:00Z",
  "acknowledged_at": "2026-11-19T09:30:00Z",
  "acknowledged_by": "acknowledged by",
  "resolved_at": "2026-11-19T09:30:00Z",
  "resolution_notes": "resolution notes",
  "resolution_code": "RES-2026-000142"
}

List alarms

Logs

GET /alarms

Returns the tenant's alarms, newest first, with cursor pagination (limit defaults to 20, at most 100; pass next_cursor as after). Filters combine, so you can ask for the open alarms of one rule at one sensor.

Parameters

statusstring · query · optional

Return only alarms in this state: open, acknowledged or resolved; omit for all states.

rule_idstring · query · optional

Return only alarms raised by this alarm rule (prefix mrl_).

sensor_idstring · query · optional

Return only alarms raised at this location: the sensor ID for telemetry rules, or the asset or DMA ID of the sample for quality rules.

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 OK

Show attributes
dataarray of Alarm · optional
Show child attributes
idstring · optional
rule_idstring · optional
sensor_idstring · optional
sample_idstring · optional
titlestring · optional
severitystring · optional
event_typestring · optional
statusstring · optional

one of open, acknowledged, resolved

valuenumber · optional
peak_valuenumber · optional
unitstring · optional
opened_atstring (date-time) · optional
last_observed_atstring (date-time) · optional
acknowledged_atstring (date-time) · optional
acknowledged_bystring · optional
resolved_atstring (date-time) · optional
resolution_notesstring · optional
resolution_codestring · optional

Stable code of a resolution the server wrote (alarm.auto_cleared); clients word it and fall back to resolution_notes. Absent for notes people typed.

has_moreboolean · optional
next_cursorstring · optional

Errors 400 · 403

Permissions business:monitoring:read · Roles: admin, analyst, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/alarms" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "ala_2NbIUPJ8YXJkm1LiQVXgqjxIYd7",
      "rule_id": "rul_2aARlSaHxSk1Z6Yp9aKdnemXRyk",
      "sensor_id": "sen_28o3p46TDQsRdq8pzycV5cIxbMg",
      "sample_id": "sam_2U07jOAhTYQNV60Pd6W5x8IZHUU",
      "title": "Fuga na Rua 3",
      "severity": "severity",
      "event_type": "event type",
      "status": "open",
      "value": 13.42,
      "peak_value": 13.42,
      "unit": "unit",
      "opened_at": "2026-11-19T09:30:00Z",
      "last_observed_at": "2026-11-19T09:30:00Z",
      "acknowledged_at": "2026-11-19T09:30:00Z",
      "acknowledged_by": "acknowledged by",
      "resolved_at": "2026-11-19T09:30:00Z",
      "resolution_notes": "resolution notes",
      "resolution_code": "RES-2026-000142"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Get an alarm

Logs

GET /alarms/{id}

Returns one alarm with its current, peak and unit values, timestamps for opening, last observation, acknowledgement and resolution, and the resolution notes or code (auto-cleared alarms carry a resolution code). Answers 404 when the alarm is not in the caller's tenant.

Parameters

idstring · path · required

Identifier of the alarm (prefix alm_).

Returns

200 OK

Show attributes
idstring · optional
rule_idstring · optional
sensor_idstring · optional
sample_idstring · optional
titlestring · optional
severitystring · optional
event_typestring · optional
statusstring · optional

one of open, acknowledged, resolved

valuenumber · optional
peak_valuenumber · optional
unitstring · optional
opened_atstring (date-time) · optional
last_observed_atstring (date-time) · optional
acknowledged_atstring (date-time) · optional
acknowledged_bystring · optional
resolved_atstring (date-time) · optional
resolution_notesstring · optional
resolution_codestring · optional

Stable code of a resolution the server wrote (alarm.auto_cleared); clients word it and fall back to resolution_notes. Absent for notes people typed.

Errors 400 · 403

Permissions business:monitoring:read · Roles: admin, analyst, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/alarms/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "ala_2NbIUPJ8YXJkm1LiQVXgqjxIYd7",
  "rule_id": "rul_2aARlSaHxSk1Z6Yp9aKdnemXRyk",
  "sensor_id": "sen_28o3p46TDQsRdq8pzycV5cIxbMg",
  "sample_id": "sam_2U07jOAhTYQNV60Pd6W5x8IZHUU",
  "title": "Fuga na Rua 3",
  "severity": "severity",
  "event_type": "event type",
  "status": "open",
  "value": 13.42,
  "peak_value": 13.42,
  "unit": "unit",
  "opened_at": "2026-11-19T09:30:00Z",
  "last_observed_at": "2026-11-19T09:30:00Z",
  "acknowledged_at": "2026-11-19T09:30:00Z",
  "acknowledged_by": "acknowledged by",
  "resolved_at": "2026-11-19T09:30:00Z",
  "resolution_notes": "resolution notes",
  "resolution_code": "RES-2026-000142"
}

Acknowledge an open alarm

Logs

POST /alarms/{id}/acknowledge

Moves an open alarm to acknowledged and records who acknowledged it and when. Acknowledging an alarm that is already acknowledged returns it unchanged; acknowledging a resolved alarm answers 409. The alarm can still auto-clear or be resolved afterwards.

Parameters

idstring · path · required

Identifier of the alarm to acknowledge (prefix alm_).

Returns

200 OK

Show attributes
idstring · optional
rule_idstring · optional
sensor_idstring · optional
sample_idstring · optional
titlestring · optional
severitystring · optional
event_typestring · optional
statusstring · optional

one of open, acknowledged, resolved

valuenumber · optional
peak_valuenumber · optional
unitstring · optional
opened_atstring (date-time) · optional
last_observed_atstring (date-time) · optional
acknowledged_atstring (date-time) · optional
acknowledged_bystring · optional
resolved_atstring (date-time) · optional
resolution_notesstring · optional
resolution_codestring · optional

Stable code of a resolution the server wrote (alarm.auto_cleared); clients word it and fall back to resolution_notes. Absent for notes people typed.

Errors 400 · 403

Permissions business:alarms:manage · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/alarms/{id}/acknowledge" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "ala_2NbIUPJ8YXJkm1LiQVXgqjxIYd7",
  "rule_id": "rul_2aARlSaHxSk1Z6Yp9aKdnemXRyk",
  "sensor_id": "sen_28o3p46TDQsRdq8pzycV5cIxbMg",
  "sample_id": "sam_2U07jOAhTYQNV60Pd6W5x8IZHUU",
  "title": "Fuga na Rua 3",
  "severity": "severity",
  "event_type": "event type",
  "status": "open",
  "value": 13.42,
  "peak_value": 13.42,
  "unit": "unit",
  "opened_at": "2026-11-19T09:30:00Z",
  "last_observed_at": "2026-11-19T09:30:00Z",
  "acknowledged_at": "2026-11-19T09:30:00Z",
  "acknowledged_by": "acknowledged by",
  "resolved_at": "2026-11-19T09:30:00Z",
  "resolution_notes": "resolution notes",
  "resolution_code": "RES-2026-000142"
}

Close an alarm with optional notes

Logs

POST /alarms/{id}/resolve

Closes an open or acknowledged alarm by hand, stamping the resolution time and storing the optional notes from the body (the body may be omitted). Resolving an alarm that is already resolved returns it unchanged. A later breach of the same rule at the same location opens a new alarm.

Parameters

idstring · path · required

Identifier of the alarm to resolve (prefix alm_).

Returns

200 OK

Show attributes
idstring · optional
rule_idstring · optional
sensor_idstring · optional
sample_idstring · optional
titlestring · optional
severitystring · optional
event_typestring · optional
statusstring · optional

one of open, acknowledged, resolved

valuenumber · optional
peak_valuenumber · optional
unitstring · optional
opened_atstring (date-time) · optional
last_observed_atstring (date-time) · optional
acknowledged_atstring (date-time) · optional
acknowledged_bystring · optional
resolved_atstring (date-time) · optional
resolution_notesstring · optional
resolution_codestring · optional

Stable code of a resolution the server wrote (alarm.auto_cleared); clients word it and fall back to resolution_notes. Absent for notes people typed.

Errors 400 · 403

Permissions business:alarms:manage · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/alarms/{id}/resolve" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "ala_2NbIUPJ8YXJkm1LiQVXgqjxIYd7",
  "rule_id": "rul_2aARlSaHxSk1Z6Yp9aKdnemXRyk",
  "sensor_id": "sen_28o3p46TDQsRdq8pzycV5cIxbMg",
  "sample_id": "sam_2U07jOAhTYQNV60Pd6W5x8IZHUU",
  "title": "Fuga na Rua 3",
  "severity": "severity",
  "event_type": "event type",
  "status": "open",
  "value": 13.42,
  "peak_value": 13.42,
  "unit": "unit",
  "opened_at": "2026-11-19T09:30:00Z",
  "last_observed_at": "2026-11-19T09:30:00Z",
  "acknowledged_at": "2026-11-19T09:30:00Z",
  "acknowledged_by": "acknowledged by",
  "resolved_at": "2026-11-19T09:30:00Z",
  "resolution_notes": "resolution notes",
  "resolution_code": "RES-2026-000142"
}