REST API — Incidents

The Drumbeats Incidents API lists, acknowledges, and resolves incidents programmatically. Every endpoint requires an X-API-Key header carrying a project-scoped key. See the REST API overview for authentication and shared response shapes.

List incidents

GET /v1/incidents?project_id=<project-id>

GET /v1/incidents?project_id=<project-id>

Returns paginated incidents for the given project, optionally filtered.

curl "https://api.drumbeats.io/v1/incidents?project_id=<project-id>&status=OPEN" \
  -H "X-API-Key: dk_live_<key>"

curl "https://api.drumbeats.io/v1/incidents?project_id=<project-id>&status=OPEN" \
  -H "X-API-Key: dk_live_<key>"

Response shape:

{
  "data": [
    {
      "id": "<incident-uuid>",
      "monitor_id": "<monitor-uuid>",
      "project_id": "<project-uuid>",
      "monitor": {
        "id": "<monitor-uuid>",
        "name": "Daily Backup Job",
        "slug": "daily-backup",
        "project_id": "<project-uuid>"
      },
      "event": "MISSED",
      "cause": "Missed check-in",
      "status": "OPEN",
      "started_at": "2026-05-11T02:10:00.000Z",
      "acknowledged_at": null,
      "acknowledged_by": null,
      "resolved_at": null,
      "resolved_by": null
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1, "has_next": false, "has_prev": false }
}

{
  "data": [
    {
      "id": "<incident-uuid>",
      "monitor_id": "<monitor-uuid>",
      "project_id": "<project-uuid>",
      "monitor": {
        "id": "<monitor-uuid>",
        "name": "Daily Backup Job",
        "slug": "daily-backup",
        "project_id": "<project-uuid>"
      },
      "event": "MISSED",
      "cause": "Missed check-in",
      "status": "OPEN",
      "started_at": "2026-05-11T02:10:00.000Z",
      "acknowledged_at": null,
      "acknowledged_by": null,
      "resolved_at": null,
      "resolved_by": null
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1, "has_next": false, "has_prev": false }
}

The incident enum is OPEN | ACKNOWLEDGED | RESOLVED. There is no separate RECOVERED state — a success ping transitions an OPEN or ACKNOWLEDGED incident directly to RESOLVED and the monitor flips back UP.

Get one incident

GET /v1/incidents/<incident-id>

GET /v1/incidents/<incident-id>

Returns a single incident by UUID, including the embedded monitor summary and any acknowledge / resolve metadata.

curl https://api.drumbeats.io/v1/incidents/<incident-id> \
  -H "X-API-Key: dk_live_<key>"

curl https://api.drumbeats.io/v1/incidents/<incident-id> \
  -H "X-API-Key: dk_live_<key>"

Acknowledge an incident

POST /v1/incidents/<incident-id>/acknowledge

POST /v1/incidents/<incident-id>/acknowledge

Transitions an incident from OPEN to ACKNOWLEDGED and records who acknowledged it. Requires Member role or higher. Acknowledging silences the per-channel re-page so on-call rotations stop being nudged once someone is actively fixing the issue — see Alert logic for the cooldown rules.

curl -X POST https://api.drumbeats.io/v1/incidents/<incident-id>/acknowledge \
  -H "X-API-Key: dk_live_<key>"

curl -X POST https://api.drumbeats.io/v1/incidents/<incident-id>/acknowledge \
  -H "X-API-Key: dk_live_<key>"

Response:

Resolve an incident

Transitions an incident from OPEN or ACKNOWLEDGED to RESOLVED. Requires Member role or higher.

Incidents auto-resolve when the monitor receives a success ping after a failure or missed check-in — manual resolution is for the rare cases where the underlying issue is fixed but no ping has arrived yet. Manual resolution is recorded with resolved_by so the audit trail is clear.

Response:

Related guides

• Incidents — incident lifecycle, state machine, and acknowledgement semantics.
• REST API — Monitors — fetch monitor-scoped incidents via GET /v1/monitors/<id>/incidents.
• Notifications: alert logic — what acknowledgement does to re-page behaviour.