Incidents API

Read incidents and automate them over the Servor API — create incidents, post updates and resolve them with an incidents:read or incidents:write token.

Read incidents and drive incident automation programmatically. The Incidents API is the one place where the Servor API does more than read: you can create incidents, post updates as things develop, and resolve them when the issue is fixed. That makes it ideal for wiring your own alerting or runbooks into Servor.

Reading incidents requires the incidents:read scope. Creating incidents and posting updates requires incidents:write.

get/v1/incidentsScope: incidents:read

List incidents, newest first (paginated)

Parameters

limitintegerquery · optional
Page size, 1–100 (default 50).
cursorstringquery · optional
Opaque cursor from a previous response's nextCursor. Omit for the first page. An unrecognised cursor is ignored and the first page returned.

Example request

curl https://api.servor.app/v1/incidents \
  -H "Authorization: Bearer sv_live_..."

Example response

{
  "items": [
    {
      "id": "uuid",
      "title": "API degraded",
      "status": "investigating",
      "impact": "major",
      "statusPageId": "uuid",
      "isMaintenance": false,
      "startedAt": "2026-08-20T10:00:00.000Z",
      "resolvedAt": null,
      "createdAt": "2026-08-20T10:00:00.000Z"
    }
  ],
  "nextCursor": null
}

post/v1/incidentsScope: incidents:write

Create an incident

Request body

titlestringrequired
Short incident title.
statusinvestigating | identified | monitoring | resolvedrequired
impactnone | minor | major | criticalrequired
messagestringrequired
First update posted with the incident.
statusPageIduuidoptional
Attach the incident to a status page.
componentIdsuuid[]optional
Affected components.

Example request

curl -X POST https://api.servor.app/v1/incidents \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"<string>","status":"<investigating | identified | monitoring | resolved>","impact":"<none | minor | major | critical>","message":"<string>"}'

Example response

{
  "id": "uuid",
  "title": "API degraded",
  "status": "investigating"
}

get/v1/incidents/{id}Scope: incidents:read

Get an incident with its timeline

Parameters

iduuidpath · required
The incident id.

Example request

curl https://api.servor.app/v1/incidents/:id \
  -H "Authorization: Bearer sv_live_..."

Example response

{
  "id": "uuid",
  "title": "API degraded",
  "status": "identified",
  "impact": "major",
  "statusPageId": "uuid",
  "isMaintenance": false,
  "startedAt": "2026-08-20T10:00:00.000Z",
  "resolvedAt": null,
  "createdAt": "2026-08-20T10:00:00.000Z",
  "updates": [
    {
      "id": "uuid",
      "status": "investigating",
      "message": "Looking into it.",
      "createdAt": "2026-08-20T10:05:00.000Z"
    }
  ]
}

post/v1/incidents/{id}/updatesScope: incidents:write

Post an update (resolve with status=resolved)

Parameters

iduuidpath · required
The incident id.

Request body

statusinvestigating | identified | monitoring | resolvedrequired
Use "resolved" to close the incident.
messagestringrequired
notifySubscribersbooleanoptional
Email/webhook subscribers (default true).

Example request

curl -X POST https://api.servor.app/v1/incidents/:id/updates \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"<investigating | identified | monitoring | resolved>","message":"<string>"}'

Example response

{
  "id": "uuid",
  "status": "resolved"
}

Read vs. write

incidents:read — list incidents, read a single incident and its update timeline. Enough for dashboards, exports or a mirror in your own tooling.
incidents:write — create incidents and post updates (including the update that resolves them). Grant it only to tokens that actually need to write.

Least privilege

If a token only needs to display incidents, give it incidents:read alone. Keep write access on separate tokens you can revoke independently. See scopes.

Listing incidents

GET /v1/incidents returns an envelope — items and nextCursor — newest created first. While nextCursor is not null, pass it back as ?cursor= for the next page.

curl "https://api.servor.app/v1/incidents?limit=50" \
  -H "Authorization: Bearer sv_live_..."

Creation order, not start time

The list is ordered by when Servor recorded the incident, not by startedAt. That is deliberate: startedAt can be edited, and an incident backdated to last week would slot into the middle of a paginated walk — an automation following cursors would step straight past it and never see it.

It is also the question a poller is really asking: “what has appeared since I last looked” is about when Servor learned of the incident, not when the outage is said to have begun.

Creating an incident

An incident has a title, a status, an impact level and an opening message. You can optionally tie it to a status page and its components so it shows up publicly and notifies subscribers.

curl -X POST https://api.servor.app/v1/incidents \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Elevated API error rate",
    "status": "investigating",
    "impact": "major",
    "message": "We are investigating a spike in 5xx responses."
  }'

The response contains the new incident's id, which you use to post updates.

Posting updates and resolving

As the situation evolves, post updates to the same incident. Each update carries a status and a message; both are added to the public timeline and notify subscribers on the linked status page.

curl -X POST https://api.servor.app/v1/incidents/inc_123/updates \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "monitoring",
    "message": "A fix has been deployed. We are watching error rates."
  }'

To resolve an incident, post an update with status set to resolved:

curl -X POST https://api.servor.app/v1/incidents/inc_123/updates \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "message": "Error rates are back to normal. Incident resolved."
  }'

Resolving is an update

There is no separate "close" call. An incident is resolved by posting an update whose status is resolved — the timeline keeps the full history.

Automatic incidents

Incidents don't have to be created by hand. Servor can open one automatically when a monitor transitions to down. See automatic incidents for how detection works and report an incident for the manual flow in the dashboard — report an incident in Servor. Whichever way an incident is opened, you can post updates to it and resolve it over the API.

A typical automation

Detect the problem

Your own alerting (or a monitor) decides something is wrong.

Open an incident

POST /v1/incidents with a title, status: "investigating" and an impact level, tied to your status page.

Keep people posted

POST /v1/incidents/{id}/updates at each milestone — identified, monitoring, and so on.

Resolve it

Post a final update with status: "resolved" once the issue is fixed.

Notes

Incident updates are public on the linked status page and notify subscribers — write messages your users will read.
A 403 means your token is missing the scope for the action: incidents:read to read, incidents:write to create or update. See errors.
A 422 means the payload failed validation (for example a missing title or an unknown status); the response details say which field.