API

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.

  1. incident:open opens the incident with a title, a first text and a severity (minor, major or critical, minor if omitted). Use componentIds to link affected components. The response contains the new ID in data.id.
  2. incident:post-update adds an update. With newStatus you set the state: investigating, identified or monitoring.
  3. incident:resolve closes the incident with a final text.
shellOpen an incident
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>"
    ]
  }
}'
shellPost an update with a new state
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"
  }
}'
shellClose an incident
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.

shellSchedule maintenance
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.

shellStart maintenance
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
  }
}'
shellComplete maintenance
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
  }
}'
shellCancel scheduled maintenance
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.

shellCreate a component
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.

shellSet a component to major outage
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.

shellCreate an HTTP monitor with a linked component
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.

shellCheck a monitor right away
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.

shellRead one incident
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>"
  }
}'