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": {}
}
}
}'