Incidents

Incidents are addressed by their number in the workspace: /incidents/42 is INC-42. Two scopes: incidents:read reads, incidents:write declares and changes.

Scopes only narrow what the token's owner may do. The owner must be a non-guest member of a workspace that has Incidents switched on, otherwise every call answers 403.

Important A private incident is a 404 for a token whose owner is not one of its members, whatever its scopes. It is also missing from the list. Administrators get no special treatment through the API.

The same things exist in the MCP server as polder_* incident tools. See Scopes.

An incident#

The list returns the compact form, a single incident returns it plus the detail.

A single incident also has accepted_at, closed_at, merged_into, channel (the chat channel), roles (every role with its holder), members, following, timestamps, metrics (seconds), timeline, updates (the latest 50), links (only what you may see yourself), tasks, postmortem and more.

List incidents#

Incidents you may see, most recently declared first, paged.

curl "https://backlog.polder.work/api/v1/workspaces/7/incidents?phase=open" \
  -H "Authorization: Bearer $POLDER_TOKEN"

{
  "data": [{
    "id": 90, "identifier": "INC-42", "number": 42, "title": "Checkout is down", "private": false,
    "status": { "id": 2, "name": "Investigating", "phase": "active" },
    "severity": { "id": 1, "name": "SEV1", "rank": 1, "…": "…" },
    "lead": { "id": 3, "name": "Sanne", "avatar": null }, "…": "…"
  }],
  "meta": { "page": 1, "per_page": 50, "total": 1, "last_page": 1 }
}

Get the options#

The workspace's configuration you pick ids from: severities, types (with private_by_default), statuses (with their phase) and roles (id, key, name, description). Fetch it before declaring or changing an incident.

{ "data": { "severities": [{ "id": 1, "name": "SEV1", "…": "…" }], "types": [], "statuses": [], "roles": [] } }

Declare an incident#

Declares an incident with the next number of the workspace and the source api. It starts straight in the active phase, or in triage when you ask for it. Answers 201 with the full incident.

Body

curl https://backlog.polder.work/api/v1/workspaces/7/incidents \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Checkout is down", "severity_id": 1}'

Get an incident#

The full incident. 404 when the number does not exist in this workspace or the incident is private and you are not a member.

{ "data": { "identifier": "INC-42", "title": "Checkout is down", "roles": [], "timeline": [], "updates": [], "…": "…" } }

Change an incident#

Changes the fields you send. A status change goes through the lifecycle (it can set timestamps, notify people and write to the timeline). Answers 200 with the full incident.

To tell people what is going on, use Post a status update instead.

Post a status update#

Posts an update for the people following the incident, optionally changing status and severity in the same step and scheduling the next update. Answers 201 with the update's id and the incident row.

{ "data": { "id": 311, "incident": { "identifier": "INC-42", "next_update_at": "2026-10-28T10:30:00+00:00", "…": "…" } } }

Get the timeline#

Everything that happened, oldest first. Each event has id, kind (note, message, role, …), actor, occurred_at, data, edited, hidden and editable. The timeline is not paged.

{ "data": [{ "id": 1, "kind": "note", "actor": { "id": 3, "name": "Sanne", "avatar": null }, "occurred_at": "2026-10-28T09:12:00+00:00", "data": { "text": "Rolled back the release" }, "edited": false, "hidden": false, "editable": true }] }

Add a timeline note#

Writes a note on the timeline. Answers 201 with the new event's id.

curl https://backlog.polder.work/api/v1/workspaces/7/incidents/42/timeline \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Rolled back the release", "occurred_at": "2026-10-28T09:12:00+00:00"}'

Assign a role#

Gives a role (the ids come from the options) to a person, or clears it. role is the role's id, not its number. The new holder becomes a member of the incident and the change is written on the timeline. Setting the same holder again changes nothing. Answers 200 with the incident row.

The lead role cannot be cleared while the incident is open (422 on user_id).

curl -X PUT https://backlog.polder.work/api/v1/workspaces/7/incidents/42/roles/1 \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": 3}'