API

API tokens

Create an API token for PublicStatus, choose its scopes and send it with your requests.

Last updated:

An API token lets a script or another service call the PublicStatus API in your name. Its scopes decide which data it may read or change.

Create a token

  1. Open Developer › API tokens.
  2. Choose Create a new token.
  3. Enter a name, pick the scopes and the expiry, and confirm with your password.
  4. Copy the token. It starts with kpat_ and is shown only once.

A token expires after 90 days unless you pick another expiry. The longest possible expiry is 3650 days.

Use the token

Send the token in the Authorization header. Requests with a token need no cookie and no CSRF token.

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

Scopes

Each scope comes in two levels. read allows the read handlers. write allows everything read allows plus the write handlers.

Scope Grant Handlers
components (Components) components:read publicstatus:query:component:detail, publicstatus:query:component:list
components (Components) components:write publicstatus:write:component:create, publicstatus:write:component:delete, publicstatus:write:component:update
incidents (Incidents) incidents:read publicstatus:query:incident:detail, publicstatus:query:incident:list, publicstatus:query:incident:updates
incidents (Incidents) incidents:write publicstatus:write:incident:open, publicstatus:write:incident:post-update, publicstatus:write:incident:resolve, publicstatus:write:incident:update
maintenance (Maintenance) maintenance:read publicstatus:query:maintenance:detail, publicstatus:query:maintenance:list
maintenance (Maintenance) maintenance:write publicstatus:write:maintenance:cancel, publicstatus:write:maintenance:complete, publicstatus:write:maintenance:schedule, publicstatus:write:maintenance:start
monitors (Monitors) monitors:read publicstatus:query:monitor:detail, publicstatus:query:monitor:list, publicstatus:query:monitor:uptime-public
monitors (Monitors) monitors:write publicstatus:write:monitor:check-now, publicstatus:write:monitor:create, publicstatus:write:monitor:delete, publicstatus:write:monitor:mint-heartbeat-token, publicstatus:write:monitor:update
webhooks (Webhooks) webhooks:read publicstatus:query:webhook-subscriber:detail, publicstatus:query:webhook-subscriber:list
webhooks (Webhooks) webhooks:write publicstatus:write:webhook-subscriber:create, publicstatus:write:webhook-subscriber:delete, publicstatus:write:webhook-subscriber:reactivate, publicstatus:write:webhook-subscriber:rotate-secret, publicstatus:write:webhook-subscriber:update

Rate limit

Each token may send 120 requests per 60 seconds. Above that the API answers 429 pat_rate_limited.

API tokens are available from the Team plan.

Errors

HTTP status Code Cause
401 missing_token No Authorization header.
401 invalid_token The token is unknown, revoked or expired.
403 access_denied The token lacks the scope for this handler.
403 access_denied The endpoint does not accept tokens. Tokens work only on the API endpoints.
429 pat_rate_limited Too many requests from this token.
403 feature_disabled API tokens are not part of your plan.

Revoke a token

Revoke a token in Developer › API tokens as soon as you stop using it. Changing your password revokes all your tokens. A token always acts with your current roles. If you leave the account or your user is deleted, it stops working.

Security

  • Treat a token like a password. Keep it in a secret store, never in code, a repository, an app or web page, or a log.
  • Give each script its own token with only the scopes it needs.
  • Revoke tokens you no longer use. Revoke a token at once if it may have leaked.