Alert rules

6 operations at https://api.zaitrack.app. Request and response bodies are JSON with camelCase keys; ids are UUIDs; times are RFC 3339 in UTC.

Every operation needs an API key, a personal access token or an OAuth access token unless it says otherwise. An Idempotency-Key is replayed for 24 hours; see Idempotency. Errors are application/problem+json; see Errors.

List alert rules

GET /v1/alert-rules

Scope: alerts:read or alerts:*
Rate class: read (100 per second and 360,000 per hour)
Idempotency-Key: not used
Audited: no
Step-up MFA: no

Request

No body.

Response

200: fields the handler writes, taken from its source.

Field	Type	Notes
`items`	array of object
`items[].id`	string	omitted when empty
`items[].name`	string
`items[].kind`	string
`items[].severity`	string
`items[].enabled`	boolean	omitted when empty
`items[].params`	object
`items[].params.thresholdKph`	number	omitted when empty
`items[].params.minDurationSec`	integer	omitted when empty
`items[].params.minMinutes`	integer	omitted when empty
`items[].params.minVolts`	number	omitted when empty
`items[].params.geofenceId`	string (UUID)	omitted when empty
`items[].params.geofenceCategory`	string	omitted when empty
`items[].params.on`	string	omitted when empty
`items[].params.minDefect`	string	omitted when empty
`items[].params.minSeverity`	string	omitted when empty
`items[].params.events`	array of string	omitted when empty
`items[].params.vehicleLimit`	boolean	omitted when empty
`items[].vehicleIds`	array of string
`items[].ackBeforeResolve`	boolean
`items[].window`	object
`items[].window.mode`	string	omitted when empty
`items[].window.spans`	array of object	omitted when empty
`items[].window.spans[].day`	integer
`items[].window.spans[].start`	string
`items[].window.spans[].end`	string
`items[].throttle`	object
`items[].throttle.max`	integer	omitted when empty
`items[].throttle.perMinutes`	integer	omitted when empty
`items[].driverIds`	array of string
`items[].geofenceIds`	array of string
`items[].titleTemplate`	string
`items[].createdAt`	string	omitted when empty
`items[].updatedAt`	string	omitted when empty
`items[].version`	integer	omitted when empty

Example

curl "https://api.zaitrack.app/v1/alert-rules" \
  -H "Authorization: Bearer zk_test_…"

Create an alert rule

POST /v1/alert-rules

Scope: rules:write or rules:*
Rate class: write (50 per second and 36,000 per hour)
Idempotency-Key: optional
Audited: low risk
Step-up MFA: no

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
`id`	string	optional
`name`	string
`kind`	string
`severity`	string
`enabled`	boolean	optional
`params`	object
`params.thresholdKph`	number	optional
`params.minDurationSec`	integer	optional
`params.minMinutes`	integer	optional
`params.minVolts`	number	optional
`params.geofenceId`	string (UUID)	optional
`params.geofenceCategory`	string	optional
`params.on`	string	optional
`params.minDefect`	string	optional
`params.minSeverity`	string	optional
`params.events`	array of string	optional
`params.vehicleLimit`	boolean	optional
`vehicleIds`	array of string
`ackBeforeResolve`	boolean
`window`	object
`window.mode`	string	optional
`window.spans`	array of object	optional
`window.spans[].day`	integer
`window.spans[].start`	string
`window.spans[].end`	string
`throttle`	object
`throttle.max`	integer	optional
`throttle.perMinutes`	integer	optional
`driverIds`	array of string
`geofenceIds`	array of string
`titleTemplate`	string
`createdAt`	string	optional
`updatedAt`	string	optional
`version`	integer	optional

Response

201: fields the handler writes, taken from its source.

Field	Type	Notes
`id`	string	omitted when empty
`name`	string
`kind`	string
`severity`	string
`enabled`	boolean	omitted when empty
`params`	object
`params.thresholdKph`	number	omitted when empty
`params.minDurationSec`	integer	omitted when empty
`params.minMinutes`	integer	omitted when empty
`params.minVolts`	number	omitted when empty
`params.geofenceId`	string (UUID)	omitted when empty
`params.geofenceCategory`	string	omitted when empty
`params.on`	string	omitted when empty
`params.minDefect`	string	omitted when empty
`params.minSeverity`	string	omitted when empty
`params.events`	array of string	omitted when empty
`params.vehicleLimit`	boolean	omitted when empty
`vehicleIds`	array of string
`ackBeforeResolve`	boolean
`window`	object
`window.mode`	string	omitted when empty
`window.spans`	array of object	omitted when empty
`window.spans[].day`	integer
`window.spans[].start`	string
`window.spans[].end`	string
`throttle`	object
`throttle.max`	integer	omitted when empty
`throttle.perMinutes`	integer	omitted when empty
`driverIds`	array of string
`geofenceIds`	array of string
`titleTemplate`	string
`createdAt`	string	omitted when empty
`updatedAt`	string	omitted when empty
`version`	integer	omitted when empty

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/alert-rules" \
  -H "Authorization: Bearer zk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"id": "…", "name": "…", "kind": "…", "severity": "…", "enabled": false, "params": {"thresholdKph": 0, "minDurationSec": 0, "minMinutes": 0, "minVolts": 0, "geofenceId": "00000000-0000-0000-0000-000000000000", "geofenceCategory": "…", "on": "…", "minDefect": "…", "minSeverity": "…", "events": [], "vehicleLimit": false}, "vehicleIds": [], "ackBeforeResolve": false, "window": {"mode": "…", "spans": []}, "throttle": {"max": 0, "perMinutes": 0}, "driverIds": [], "geofenceIds": [], "titleTemplate": "…", "createdAt": "…", "updatedAt": "…", "version": 0}'

Get an alert rule

GET /v1/alert-rules/{id}

Scope: alerts:read or alerts:*
Rate class: read (100 per second and 360,000 per hour)
Idempotency-Key: not used
Audited: no
Step-up MFA: no

Path parameters: id.

Request

No body.

Response

200: fields the handler writes, taken from its source.

The same fields as the response of Create an alert rule.

Example

curl "https://api.zaitrack.app/v1/alert-rules/$ID" \
  -H "Authorization: Bearer zk_test_…"

Update an alert rule

PATCH /v1/alert-rules/{id}

Scope: rules:write or rules:*
Rate class: write (50 per second and 36,000 per hour)
Idempotency-Key: not used
Audited: low risk
Step-up MFA: no
If-Match: the version you read; a stale one is refused (412 or 409)

Path parameters: id.

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
`name`	string	optional
`severity`	string	optional
`enabled`	boolean	optional
`params`	object	optional
`params.thresholdKph`	number	optional
`params.minDurationSec`	integer	optional
`params.minMinutes`	integer	optional
`params.minVolts`	number	optional
`params.geofenceId`	string (UUID)	optional
`params.geofenceCategory`	string	optional
`params.on`	string	optional
`params.minDefect`	string	optional
`params.minSeverity`	string	optional
`params.events`	array of string	optional
`params.vehicleLimit`	boolean	optional
`vehicleIds`	array of string	optional
`ackBeforeResolve`	boolean	optional
`window`	object	optional
`window.mode`	string	optional
`window.spans`	array of object	optional
`window.spans[].day`	integer
`window.spans[].start`	string
`window.spans[].end`	string
`throttle`	object	optional
`throttle.max`	integer	optional
`throttle.perMinutes`	integer	optional
`driverIds`	array of string	optional
`geofenceIds`	array of string	optional
`titleTemplate`	string	optional

Response

200: fields the handler writes, taken from its source.

The same fields as the response of Create an alert rule.

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X PATCH "https://api.zaitrack.app/v1/alert-rules/$ID" \
  -H "Authorization: Bearer zk_test_…" \
  -H 'If-Match: "3"' \
  -H "Content-Type: application/json" \
  -d '{"name": "…", "severity": "…"}'

Delete an alert rule

DELETE /v1/alert-rules/{id}

Scope: rules:write or rules:*
Rate class: write (50 per second and 36,000 per hour)
Idempotency-Key: not used
Audited: low risk
Step-up MFA: no

Path parameters: id.

Request

No body.

Response

204: no body.

Example

curl -X DELETE "https://api.zaitrack.app/v1/alert-rules/$ID" \
  -H "Authorization: Bearer zk_test_…"

Dry-run an alert rule

POST /v1/alert-rules:test

Scope: rules:read or rules:*
Rate class: read (100 per second and 360,000 per hour)
Idempotency-Key: not used
Audited: no
Step-up MFA: no

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
`ruleId`	string
`rule`	object	optional
`rule.id`	string	optional
`rule.name`	string
`rule.kind`	string
`rule.severity`	string
`rule.enabled`	boolean	optional
`rule.params`	object
`rule.params.thresholdKph`	number	optional
`rule.params.minDurationSec`	integer	optional
`rule.params.minMinutes`	integer	optional
`rule.params.minVolts`	number	optional
`rule.params.geofenceId`	string (UUID)	optional
`rule.params.geofenceCategory`	string	optional
`rule.params.on`	string	optional
`rule.params.minDefect`	string	optional
`rule.params.minSeverity`	string	optional
`rule.params.events`	array of string	optional
`rule.params.vehicleLimit`	boolean	optional
`rule.vehicleIds`	array of string
`rule.ackBeforeResolve`	boolean
`rule.window`	object
`rule.window.mode`	string	optional
`rule.window.spans`	array of object	optional
`rule.window.spans[].day`	integer
`rule.window.spans[].start`	string
`rule.window.spans[].end`	string
`rule.throttle`	object
`rule.throttle.max`	integer	optional
`rule.throttle.perMinutes`	integer	optional
`rule.driverIds`	array of string
`rule.geofenceIds`	array of string
`rule.titleTemplate`	string
`rule.createdAt`	string	optional
`rule.updatedAt`	string	optional
`rule.version`	integer	optional
`deviceId`	string
`from`	string
`to`	string

Response

200: fields the handler writes, taken from its source.

Field	Type	Notes
`kind`	—
`params`	—
`points`	integer
`truncated`	boolean
`wouldAlert`	—
`episodes`	array of object
`episodes[].startedAt`	—
`episodes[].raisedAt`	—
`episodes[].clearedAt`	—
`episodes[].worst`	—
`episodes[].heldBy`	—
`episodes[].title`	—

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/alert-rules:test" \
  -H "Authorization: Bearer zk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"ruleId": "…", "rule": {"id": "…", "name": "…", "kind": "…", "severity": "…", "enabled": false, "params": {"thresholdKph": 0, "minDurationSec": 0, "minMinutes": 0, "minVolts": 0, "geofenceId": "00000000-0000-0000-0000-000000000000", "geofenceCategory": "…", "on": "…", "minDefect": "…", "minSeverity": "…", "events": [], "vehicleLimit": false}, "vehicleIds": [], "ackBeforeResolve": false, "window": {"mode": "…", "spans": []}, "throttle": {"max": 0, "perMinutes": 0}, "driverIds": [], "geofenceIds": [], "titleTemplate": "…", "createdAt": "…", "updatedAt": "…", "version": 0}, "deviceId": "…", "from": "…", "to": "…"}'

List alert rules​

Request​

Response​

Example​

Create an alert rule​

Request​

Response​

Example​

Get an alert rule​

Request​

Response​

Example​

Update an alert rule​

Request​

Response​

Example​

Delete an alert rule​

Request​

Response​

Example​

Dry-run an alert rule​

Request​

Response​

Example​

List alert rules

Request

Response

Example

Create an alert rule

Request

Response

Example

Get an alert rule

Request

Response

Example

Update an alert rule

Request

Response

Example

Delete an alert rule

Request

Response

Example

Dry-run an alert rule

Request

Response

Example