Incidents

An incident is an operator-authored, customer-facing record of a service disruption, distinct from an alert (the internal paging event driven by monitor state). Incidents render on status pages; alerts don’t.

The split lets the on-call team triage and decide what to communicate publicly, when, and how, independent of every flap in the underlying monitor stream.

Endpoints

Method	Path	Description	Scope
GET	/api/v1/incidents	List incidents in the org, filterable by status.	incidents
POST	/api/v1/incidents	Create.	incidents
GET	/api/v1/incidents/{id}	Read one (full timeline).	incidents
PATCH	/api/v1/incidents/{id}	Update metadata (title, severity, status).	incidents
DELETE	/api/v1/incidents/{id}	Delete (admin-only; prefer marking resolved).	incidents
POST	/api/v1/incidents/{id}/updates	Append a public or private timeline update.	incidents
PATCH	/api/v1/incidents/{id}/updates/{updateId}	Edit an existing update.	incidents
DELETE	/api/v1/incidents/{id}/updates/{updateId}	Delete an update (admin-only).	incidents
POST	/api/v1/alerts/{id}/create-incident	Promote an alert into a new incident, pre-populated.	incidents

Status lifecycle

Status	Meaning
investigating	Initial state. Operators acknowledge the issue but haven’t pinned the cause.
identified	Root cause known; communicating it.
monitoring	Mitigation applied; watching for recovery.
resolved	Incident closed. Page banners stop reflecting it.
maintenance	Reserved for incidents that represent planned work rather than disruption. Public banner uses the maintenance label.

Status changes are tracked on the timeline via update entries: every status transition is also an update with the new status set.

Severity

Severity	Public banner text	Notes
critical	”Major System Outage”	Worst case. The page banner goes red.
major	”Partial System Disruption”	Amber.
minor	”Minor Service Degradation”	Amber.

When a status page has multiple active incidents linked, the page banner reflects the worst severity. When an incident is resolved, it stops contributing to the banner.

List incidents

GET /api/v1/incidents?status=active

Query parameters:

Parameter	Description
status	active (default; anything not yet resolved), resolved, or all.
limit, cursor	Pagination.

The list response wraps the incidents and enriches each with linked monitor IDs + linked status-page IDs.

Create

POST /api/v1/incidents

{
  "title": "Checkout latency degradation",
  "severity": "major",
  "status": "investigating",
  "started_at": "2026-04-24T17:42:00Z",
  "monitor_ids": ["01HXMON..."],
  "status_page_ids": ["01HXSP..."],
  "initial_update": {
    "body": "We are investigating elevated latency on the checkout path.",
    "public": true
  }
}

Field	Required	Notes
title	yes	Customer-facing; keep it short and plain.
severity	yes	minor, major, critical, or maintenance.
status	no	Defaults to investigating.
started_at	no	Defaults to the create timestamp. Set explicitly if backfilling.
monitor_ids	no	Monitors flagged as affected. They render as part of the incident card on the public status page.
status_page_ids	no	Pages this incident appears on. An incident can publish to multiple pages (e.g., public + partner-only). Empty = internal-only incident.
initial_update.body	no	Plain text, plus \n line breaks. Renders on the public timeline if public: true.
initial_update.public	no	Defaults to true.

Response 201 Created with the incident document.

Incident document

{
  "id": "01HXINC...",
  "org_id": "01HXORG...",
  "title": "Checkout latency degradation",
  "status": "investigating",
  "severity": "major",
  "started_at": "2026-04-24T17:42:00Z",
  "resolved_at": null,
  "created_by": "usr_alice",
  "monitor_ids": ["01HXMON..."],
  "status_page_ids": ["01HXSP..."],
  "updates": [
    {
      "id": "01HXUPD...",
      "user_id": "usr_alice",
      "user_email": "[email protected]",
      "status": "investigating",
      "body": "We are investigating elevated latency on the checkout path.",
      "public": true,
      "created_at": "2026-04-24T17:43:00Z"
    }
  ],
  "created_at": "2026-04-24T17:42:30Z",
  "updated_at": "2026-04-24T17:43:00Z"
}

Post an update

POST /api/v1/incidents/{id}/updates

{
  "status": "identified",
  "body": "We've identified a bad deploy and are rolling back now. ETA 5 min.",
  "public": true
}

Field	Notes
status	New status. Setting resolved here resolves the incident.
body	Plain text + \n.
public	When true, the update appears on every linked status page. When false, it stays in the console (internal coordination only).

Use private updates for internal back-channel (“trying runbook X, not working, escalating to backend team”) and public updates for customer-facing communication (“we’ve rolled back the deploy and are watching for recovery”).

Resolve

Set status: "resolved" via PATCH or via POST /updates. Resolution stamps resolved_at and freezes the incident’s banner contribution: the page recomputes overall status without it.

A resolved incident continues to render on its linked status pages for 7 days in a “Recent incidents” section, then ages out automatically.

Promote from alert

POST /api/v1/alerts/{id}/create-incident

{
  "title": "Override the alert title (optional)",
  "severity": "major",
  "status_page_ids": ["01HXSP..."]
}

The server pre-populates from the alert: title (alert summary), severity (alert severity → incident severity mapping: critical → major, etc., overridable in the request), and the affected monitor (linked). The originating alert’s timeline is annotated with a cross-link to the new incident.

Edit / delete updates

PATCH /api/v1/incidents/{id}/updates/{updateId} lets you edit an update’s body or public flag. Visitors who already saw the original see an “(edited)” marker; the edit history is auditable in the console.

DELETE is admin-only and rare; prefer editing with a clarifying note.

What this API doesn’t do

• No subscribers. YipYap doesn’t currently push incident updates to status-page visitors via email/RSS/SMS. To notify external systems on incident transitions, route a copy via notification channels (e.g., Slack, webhook).
• No automatic incident creation from alerts. Alerts don’t auto-promote; operators decide when something is worth telling the public. The “create from alert” flow is a deliberate one-click promotion, not an automation.

Related resources

• Features → Status Pages: where incidents render publicly.
• Status Pages API: page CRUD and layout.
• Alerts API: internal alert state, the typical source for promotions.