Workflows
Open an incident, schedule maintenance, set a component status and create a monitor, step by step with curl.
Last updated:
Incident: open, update, close
An incident goes through three calls. All of them need the incidents scope with write access.
incident:openopens the incident with a title, a first text and a severity (minor,majororcritical,minorif omitted). UsecomponentIdsto link affected components. The response contains the new ID indata.id.incident:post-updateadds an update. WithnewStatusyou set the state:investigating,identifiedormonitoring.incident:resolvecloses the incident with a final text.
curl -X POST https://status.example.com/api/write \
-H "Authorization: Bearer kpat_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"type": "publicstatus:write:incident:open",
"payload": {
"title": "Elevated API latency",
"body": "We are investigating elevated response times.",
"severity": "major",
"componentIds": [
"<component-id>"
]
}
}'
curl -X POST https://status.example.com/api/write \
-H "Authorization: Bearer kpat_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"type": "publicstatus:write:incident:post-update",
"payload": {
"incidentId": "<incident-id>",
"body": "A slow database query is the cause. A fix is rolling out.",
"newStatus": "identified"
}
}'
curl -X POST https://status.example.com/api/write \
-H "Authorization: Bearer kpat_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"type": "publicstatus:write:incident:resolve",
"payload": {
"incidentId": "<incident-id>",
"body": "Response times are back to normal."
}
}'
Maintenance: schedule, start, complete or cancel
Maintenance needs the maintenance scope with write access. maintenance:schedule creates the window, with start and end as ISO 8601 timestamps. The response contains the ID in data.id.
curl -X POST https://status.example.com/api/write \
-H "Authorization: Bearer kpat_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"type": "publicstatus:write:maintenance:schedule",
"payload": {
"title": "Database upgrade",
"body": "The API is read-only during the upgrade.",
"scheduledStart": "2026-11-10T02:00:00Z",
"scheduledEnd": "2026-11-10T03:00:00Z",
"componentIds": [
"<component-id>"
]
}
}'
After that you control the maintenance with maintenance:start, maintenance:complete or maintenance:cancel. All three expect the id. The version is optional: if you send it, read it from maintenance:detail with the id. If the version is outdated, the API rejects the call with 409 and the code version_conflict.
curl -X POST https://status.example.com/api/write \
-H "Authorization: Bearer kpat_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"type": "publicstatus:write:maintenance:start",
"payload": {
"id": "<maintenance-id>",
"version": 1
}
}'
curl -X POST https://status.example.com/api/write \
-H "Authorization: Bearer kpat_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"type": "publicstatus:write:maintenance:complete",
"payload": {
"id": "<maintenance-id>",
"version": 1
}
}'
curl -X POST https://status.example.com/api/write \
-H "Authorization: Bearer kpat_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"type": "publicstatus:write:maintenance:cancel",
"payload": {
"id": "<maintenance-id>",
"version": 1
}
}'
The API rejects invalid transitions, such as starting a maintenance that is already complete.
Component: create and set the status
Components need the components scope with write access. component:create creates a component and returns its ID in data.id. A new component starts as operational.
curl -X POST https://status.example.com/api/write \
-H "Authorization: Bearer kpat_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"type": "publicstatus:write:component:create",
"payload": {
"name": "API",
"description": "Public HTTP API"
}
}'
You change the status with component:update. Besides id and the changes in changes, the call needs the component’s current version. You get it from component:detail with the id. After creation it is 1 and goes up by one with every change. With an outdated version, the API rejects the change.
curl -X POST https://status.example.com/api/write \
-H "Authorization: Bearer kpat_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"type": "publicstatus:write:component:update",
"payload": {
"id": "<component-id>",
"version": 1,
"changes": {
"status": "major-outage"
}
}
}'
operational- Running normally.
degraded-performance- Limited, for example slow.
partial-outage- Partial outage.
major-outage- Major outage.
under-maintenance- Under maintenance.
A deploy pipeline can use this to set a component to under-maintenance before the rollout and back to operational afterwards.
Monitor: create and check right away
Monitors need the monitors scope with write access. monitor:create creates an uptime monitor. kind selects the type of check: http, keyword, ssl-expiry, tcp-port or heartbeat. The interval in intervalSeconds is a string with one of these values: "60", "300", "600" or "1800". With componentId you link a component that switches to major outage automatically when the monitor fails.
curl -X POST https://status.example.com/api/write \
-H "Authorization: Bearer kpat_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"type": "publicstatus:write:monitor:create",
"payload": {
"name": "API health",
"kind": "http",
"url": "https://api.example.com/health",
"intervalSeconds": "300",
"componentId": "<component-id>",
"enabled": true
}
}'
monitor:check-now checks a monitor right away and returns the result in data.up. The call only stores a data point. Components, incidents and notifications are changed only by the regular check.
curl -X POST https://status.example.com/api/write \
-H "Authorization: Bearer kpat_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"type": "publicstatus:write:monitor:check-now",
"payload": {
"monitorId": "<monitor-id>"
}
}'
Reading one record: detail
Besides lists, every scope with read access offers a :detail call that returns one record by its id. It also returns the current version that changes need.
curl -X POST https://status.example.com/api/query \
-H "Authorization: Bearer kpat_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"type": "publicstatus:query:incident:detail",
"payload": {
"id": "<incident-id>"
}
}'