API

Incidents

API reference for Incidents: every handler with its fields and an example.

Last updated:

incident: detail

Get incident

Returns a single incident row by id, including its status, severity, start/resolution times, and custom fields, for the incident edit screen.

  • Required scope: incidents:read
  • Endpoint: POST /api/query
Field Type Required Description
id string (uuid) yes

Example request

curl -X POST https://status.example.com/api/query \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:query:incident:detail",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001"
  }
}'

incident: list

List incidents

Returns a filtered, paginated set of incident rows, including resolved ones, with their status, severity, and start time, for the admin incident list.

  • Required scope: incidents:read
  • Endpoint: POST /api/query
Field Type Required Description
cursor string no Position from nextCursor of the previous page.
limit integer no Rows per page, 50 by default, at most 200.
search string no Full-text search across the searchable fields.
sort string no Field to sort by.
sortDirection “asc” | “desc” no asc or desc.
offset integer no Number of rows to skip. Prefer cursor for paging.
totalCount boolean no Set true to also get total, the number of matching rows.
includeDeleted boolean no Set true to include deleted rows. Only for entities with soft delete.
onlyDeleted boolean no Set true to return only deleted rows. Only for entities with soft delete, not together with includeDeleted.
filter object no One field filter with field, op and value. op is one of eq, ne, lt, gt, lte, gte, in.
filter.field string yes
filter.op “eq” | “ne” | “lt” | “gt” | “lte” | “gte” | “in” yes
filter.value any yes
filters array of object no Several field filters, each with field, op and value. op is one of eq, ne, lt, gt, lte, gte, in.
namedFilter string no Name of a predefined filter of the entity, for example a work queue.
aggregate object no Returns aggregated values instead of rows.
aggregate.groupBy string no
aggregate.measures array of object no

Example request

curl -X POST https://status.example.com/api/query \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:query:incident:list",
  "payload": {}
}'

Example response

Status: 200

{
  "data": {
    "rows": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "tenantId": "00000000-0000-4000-8000-000000000002",
        "version": 3,
        "insertedAt": "2026-01-15T09:30:00.000Z",
        "modifiedAt": null,
        "insertedById": "00000000-0000-4000-8000-000000000003",
        "modifiedById": null,
        "title": "Elevated API errors",
        "status": "investigating",
        "severity": "major",
        "startedAt": "2026-01-15T09:30:00.000Z",
        "resolvedAt": null,
        "sourceMonitorId": null,
        "customFields": {}
      }
    ],
    "nextCursor": null
  }
}

incident: updates

List incident updates

Returns the chronological timeline of updates posted to one incident, including each poster’s display name.

  • Required scope: incidents:read
  • Endpoint: POST /api/query
Field Type Required Description
incidentId string (uuid) yes Incident

Example request

curl -X POST https://status.example.com/api/query \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:query:incident:updates",
  "payload": {
    "incidentId": "00000000-0000-4000-8000-000000000001"
  }
}'

incident: open

Open incident

Opens a new incident on the status page, links it to the affected components and records the initial update in its timeline.

  • Required scope: incidents:write
  • Endpoint: POST /api/write
Field Type Required Description
title string yes Title
body string yes Body
severity “minor” | “major” | “critical” no Severity
componentIds array of string (uuid) no Affected Components
startedAt string (date-time) no Started
sourceMonitorId string (uuid) no

Example request

curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:incident:open",
  "payload": {
    "title": "Elevated API errors",
    "body": "We are investigating elevated error rates.",
    "severity": "major",
    "componentIds": [
      "00000000-0000-4000-8000-000000000001"
    ]
  }
}'

Example response

Status: 200

{
  "isSuccess": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000002"
  }
}

incident: post-update

Post incident update

Appends a new timeline update to an open incident and optionally changes its status in the same call.

  • Required scope: incidents:write
  • Endpoint: POST /api/write
Field Type Required Description
incidentId string (uuid) yes Incident
body string yes Body
newStatus “investigating” | “identified” | “monitoring” | “resolved” no New Status

Example request

curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:incident:post-update",
  "payload": {
    "incidentId": "00000000-0000-4000-8000-000000000001",
    "body": "text",
    "newStatus": "investigating"
  }
}'

incident: resolve

Resolve incident

Marks an open incident as resolved, records the resolution time and appends a final update to its timeline.

  • Required scope: incidents:write
  • Endpoint: POST /api/write
Field Type Required Description
incidentId string (uuid) yes Incident
body string yes Body

Example request

curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:incident:resolve",
  "payload": {
    "incidentId": "00000000-0000-4000-8000-000000000001",
    "body": "text"
  }
}'

incident: update

Update incident

Updates a stored incident’s title, severity, startedAt, and custom fields without touching its status, which only the open/post-update/resolve handlers may change.

  • Required scope: incidents:write
  • Endpoint: POST /api/write
Field Type Required Description
id string (uuid) yes
version number yes
changes object yes
changes.title string no Title
changes.status “investigating” | “identified” | “monitoring” | “resolved” no Status
changes.severity “minor” | “major” | “critical” no Severity
changes.startedAt string (date-time) no Started
changes.resolvedAt string (date-time) | null no Resolved
changes.sourceMonitorId string | null no
changes.customFields object no

Example request

curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:incident:update",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001",
    "version": 1,
    "changes": {
      "title": "text",
      "status": "investigating",
      "severity": "minor",
      "startedAt": "2026-01-15T09:30:00.000Z",
      "resolvedAt": "2026-01-15T09:30:00.000Z",
      "sourceMonitorId": "text",
      "customFields": {}
    }
  }
}'