Alarm rules

Base URL: $BUSINESS_API

The object

idstring · optional
namestring · optional
sourcestring · optional

one of telemetry, quality

sensor_idstring · optional
parameterstring · optional
comparisonstring · optional

one of above, below

thresholdnumber · optional
clear_thresholdnumber · optional
severitystring · optional

one of critical, warning, info

event_typestring · optional
notify_phonesarray of string · optional
activeboolean · optional
The object
{
  "id": "ala_2Go3hsIph0iVZogl5Q41rKAV1E4",
  "name": "Ana Matsinhe",
  "source": "telemetry",
  "sensor_id": "sen_28o3p46TDQsRdq8pzycV5cIxbMg",
  "parameter": "parameter",
  "comparison": "above",
  "threshold": 1,
  "clear_threshold": 1,
  "severity": "critical",
  "event_type": "event type",
  "notify_phones": [
    "+258841234567"
  ],
  "active": true
}

List alarm rules

Logs

GET /alarm-rules

Returns the tenant's alarm rules, both active and inactive, newest first, with cursor pagination (limit defaults to 20, at most 100). Each rule carries its source, comparison, threshold, clear threshold, severity and whether it is currently evaluated.

Parameters

sourcestring · query · optional

Return only rules that watch this source: telemetry (sensor readings) or quality (water quality sample results); omit to return both.

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 AlarmRule · optional
Show child attributes
idstring · optional
namestring · optional
sourcestring · optional

one of telemetry, quality

sensor_idstring · optional
parameterstring · optional
comparisonstring · optional

one of above, below

thresholdnumber · optional
clear_thresholdnumber · optional
severitystring · optional

one of critical, warning, info

event_typestring · optional
notify_phonesarray of string · optional
activeboolean · optional
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/alarm-rules" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "ala_2Go3hsIph0iVZogl5Q41rKAV1E4",
      "name": "Ana Matsinhe",
      "source": "telemetry",
      "sensor_id": "sen_28o3p46TDQsRdq8pzycV5cIxbMg",
      "parameter": "parameter",
      "comparison": "above",
      "threshold": 1,
      "clear_threshold": 1,
      "severity": "critical",
      "event_type": "event type",
      "notify_phones": [
        "+258841234567"
      ],
      "active": true
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Create a threshold rule with hysteresis

Logs

POST /alarm-rules

A telemetry rule needs a sensor_id that exists in the tenant, and a quality rule needs a known water quality parameter. comparison must be above or below; an alarm opens when a value crosses threshold and closes automatically only when a value returns past clear_threshold, which defaults to threshold and must sit on the safe side of it. severity defaults to warning (critical, warning or info) and event_type to alarm.opened; the rule is created active and returns 201, with 400 for any failed check.

Body application/json

namestring · required
sourcestring · required

one of telemetry, quality

sensor_idstring · optional
parameterstring · optional
comparisonstring · required

one of above, below

thresholdnumber · required
clear_thresholdnumber · optional
severitystring · optional
event_typestring · optional
notify_phonesarray of string · optional

Returns

201 OK

Show attributes
idstring · optional
namestring · optional
sourcestring · optional

one of telemetry, quality

sensor_idstring · optional
parameterstring · optional
comparisonstring · optional

one of above, below

thresholdnumber · optional
clear_thresholdnumber · optional
severitystring · optional

one of critical, warning, info

event_typestring · optional
notify_phonesarray of string · optional
activeboolean · optional

Errors 400 · 403

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

curl -X POST "$BUSINESS_API/alarm-rules" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "source": "telemetry",
  "sensor_id": "sen_28o3p46TDQsRdq8pzycV5cIxbMg",
  "parameter": "parameter",
  "comparison": "above",
  "threshold": 1,
  "clear_threshold": 1,
  "severity": "severity",
  "event_type": "event type",
  "notify_phones": [
    "+258841234567"
  ]
}'
Response 201
{
  "id": "ala_2Go3hsIph0iVZogl5Q41rKAV1E4",
  "name": "Ana Matsinhe",
  "source": "telemetry",
  "sensor_id": "sen_28o3p46TDQsRdq8pzycV5cIxbMg",
  "parameter": "parameter",
  "comparison": "above",
  "threshold": 1,
  "clear_threshold": 1,
  "severity": "critical",
  "event_type": "event type",
  "notify_phones": [
    "+258841234567"
  ],
  "active": true
}

Get an alarm rule

Logs

GET /alarm-rules/{id}

Returns one alarm rule of the tenant with its thresholds, severity, notification phones and active flag. Answers 404 when the rule does not exist in the caller's tenant.

Parameters

idstring · path · required

Identifier of the alarm rule, as returned when it was created (prefix mrl_).

Returns

200 OK

Show attributes
idstring · optional
namestring · optional
sourcestring · optional

one of telemetry, quality

sensor_idstring · optional
parameterstring · optional
comparisonstring · optional

one of above, below

thresholdnumber · optional
clear_thresholdnumber · optional
severitystring · optional

one of critical, warning, info

event_typestring · optional
notify_phonesarray of string · optional
activeboolean · optional

Errors 400 · 403

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

curl -X GET "$BUSINESS_API/alarm-rules/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "ala_2Go3hsIph0iVZogl5Q41rKAV1E4",
  "name": "Ana Matsinhe",
  "source": "telemetry",
  "sensor_id": "sen_28o3p46TDQsRdq8pzycV5cIxbMg",
  "parameter": "parameter",
  "comparison": "above",
  "threshold": 1,
  "clear_threshold": 1,
  "severity": "critical",
  "event_type": "event type",
  "notify_phones": [
    "+258841234567"
  ],
  "active": true
}

Activate a rule

Logs

POST /alarm-rules/{id}/activate

Marks the rule active so new telemetry readings or quality results are evaluated against it again, and returns the updated rule. The call is idempotent: activating an active rule only refreshes its update time. Existing alarms are not changed.

Parameters

idstring · path · required

Identifier of the alarm rule to activate (prefix mrl_).

Returns

200 OK

Show attributes
idstring · optional
namestring · optional
sourcestring · optional

one of telemetry, quality

sensor_idstring · optional
parameterstring · optional
comparisonstring · optional

one of above, below

thresholdnumber · optional
clear_thresholdnumber · optional
severitystring · optional

one of critical, warning, info

event_typestring · optional
notify_phonesarray of string · optional
activeboolean · optional

Errors 400 · 403

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

curl -X POST "$BUSINESS_API/alarm-rules/{id}/activate" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "ala_2Go3hsIph0iVZogl5Q41rKAV1E4",
  "name": "Ana Matsinhe",
  "source": "telemetry",
  "sensor_id": "sen_28o3p46TDQsRdq8pzycV5cIxbMg",
  "parameter": "parameter",
  "comparison": "above",
  "threshold": 1,
  "clear_threshold": 1,
  "severity": "critical",
  "event_type": "event type",
  "notify_phones": [
    "+258841234567"
  ],
  "active": true
}

Deactivate a rule

Logs

POST /alarm-rules/{id}/deactivate

Marks the rule inactive so incoming readings and results no longer open, update or auto-clear alarms for it, and returns the updated rule. Alarms it already opened stay as they are and can still be acknowledged or resolved by hand. The call is idempotent.

Parameters

idstring · path · required

Identifier of the alarm rule to deactivate (prefix mrl_).

Returns

200 OK

Show attributes
idstring · optional
namestring · optional
sourcestring · optional

one of telemetry, quality

sensor_idstring · optional
parameterstring · optional
comparisonstring · optional

one of above, below

thresholdnumber · optional
clear_thresholdnumber · optional
severitystring · optional

one of critical, warning, info

event_typestring · optional
notify_phonesarray of string · optional
activeboolean · optional

Errors 400 · 403

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

curl -X POST "$BUSINESS_API/alarm-rules/{id}/deactivate" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "ala_2Go3hsIph0iVZogl5Q41rKAV1E4",
  "name": "Ana Matsinhe",
  "source": "telemetry",
  "sensor_id": "sen_28o3p46TDQsRdq8pzycV5cIxbMg",
  "parameter": "parameter",
  "comparison": "above",
  "threshold": 1,
  "clear_threshold": 1,
  "severity": "critical",
  "event_type": "event type",
  "notify_phones": [
    "+258841234567"
  ],
  "active": true
}