Alerts

7 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 alerts

GET /v1/alerts

• 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

Query parameter	Type	Notes
subjectType	string
status	string
minSeverity	string
pageSize	string
cursor	string
subjectId	—
ruleId	—
from	—
to	—

Request

No body.

Response

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

Field	Type	Notes
items	array of object
items[].id	—
items[].ruleId	—
items[].severity	—
items[].status	—
items[].title	—
items[].description	—
items[].code	—
items[].params	—
items[].subject	—
items[].labels	—
items[].occurredAt	—
items[].firstSeenAt	—
items[].lastSeenAt	—
items[].occurrenceCount	—
items[].acknowledgedAt	—
items[].acknowledgedBy	—
items[].resolvedAt	—
items[].resolvedBy	—
items[].resolutionNote	—
items[].suppressedUntil	—
items[].notes	array
items[].version	—
nextCursor	string

Example

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

Get an alert

GET /v1/alerts/{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.

Field	Type	Notes
id	—
ruleId	—
severity	—
status	—
title	—
description	—
code	—
params	—
subject	—
labels	—
occurredAt	—
firstSeenAt	—
lastSeenAt	—
occurrenceCount	—
acknowledgedAt	—
acknowledgedBy	—
resolvedAt	—
resolvedBy	—
resolutionNote	—
suppressedUntil	—
notes	array
version	—

Example

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

Acknowledge an alert

POST /v1/alerts/{id}:acknowledge

• Scope: alerts:write or alerts:*
• Rate class: write (50 per second and 36,000 per hour)
• Idempotency-Key: optional
• Audited: no
• 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. One handler serves several actions here, so a field may not apply to this one.

Field	Type	Notes
note	string
until	string

Response

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

The same fields as the response of Get an alert.

Example

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

curl -X POST "https://api.zaitrack.app/v1/alerts/$ID:acknowledge" \
  -H "Authorization: Bearer zk_test_…" \
  -H 'If-Match: "3"' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"note": "…", "until": "…"}'

Resolve an alert

POST /v1/alerts/{id}:resolve

• Scope: alerts:write or alerts:*
• Rate class: write (50 per second and 36,000 per hour)
• Idempotency-Key: optional
• Audited: no
• 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. One handler serves several actions here, so a field may not apply to this one.

The same fields as the request of Acknowledge an alert.

Response

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

The same fields as the response of Get an alert.

Example

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

curl -X POST "https://api.zaitrack.app/v1/alerts/$ID:resolve" \
  -H "Authorization: Bearer zk_test_…" \
  -H 'If-Match: "3"' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"note": "…", "until": "…"}'

Suppress an alert

POST /v1/alerts/{id}:suppress

• Scope: alerts:write or alerts:*
• Rate class: write (50 per second and 36,000 per hour)
• Idempotency-Key: optional
• 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. One handler serves several actions here, so a field may not apply to this one.

The same fields as the request of Acknowledge an alert.

Response

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

The same fields as the response of Get an alert.

Example

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

curl -X POST "https://api.zaitrack.app/v1/alerts/$ID:suppress" \
  -H "Authorization: Bearer zk_test_…" \
  -H 'If-Match: "3"' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"note": "…", "until": "…"}'

Add a note to an alert

POST /v1/alerts/{id}:note

• Scope: alerts:write or alerts:*
• Rate class: write (50 per second and 36,000 per hour)
• Idempotency-Key: optional
• Audited: no
• 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. One handler serves several actions here, so a field may not apply to this one.

The same fields as the request of Acknowledge an alert.

Response

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

The same fields as the response of Get an alert.

Example

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

curl -X POST "https://api.zaitrack.app/v1/alerts/$ID:note" \
  -H "Authorization: Bearer zk_test_…" \
  -H 'If-Match: "3"' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"note": "…", "until": "…"}'

Acknowledge or resolve alerts in bulk

POST /v1/alerts:bulk

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

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
action	string
ids	array of string
note	string

Response

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

Field	Type	Notes
results	array of object
results[].id	string
results[].ok	boolean
results[].status	string	omitted when empty
results[].error	string	omitted when empty

Example

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

curl -X POST "https://api.zaitrack.app/v1/alerts:bulk" \
  -H "Authorization: Bearer zk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"action": "…", "ids": [], "note": "…"}'