Incidents API
The Incidents API lets you create and read incidents, append timeline updates, and archive eligible resolved incidents. Published incident history is immutable: the API does not replace incident titles, initial messages, status-page or component assignments, or subscriber-notification choices, and it never hard-deletes incident history.
Requires an API key with the appropriate incidents:read or incidents:write scope.
List incidents
GET /user/api/v1/incidents
Required scope: incidents:read
Query parameters:
| Parameter | Description |
|---|---|
status_page_id | Filter by status page UUID |
limit | Max results (default 50, max 200) |
Example:
curl -H "Authorization: Bearer spk_..." \
"https://statuspage.me/user/api/v1/incidents?status_page_id=550e8400-e29b-41d4-a716-446655440000"
Get a single incident
GET /user/api/v1/incidents/:id
Required scope: incidents:read
Returns the incident and its full update timeline.
Create an incident
POST /user/api/v1/incidents
Required scope: incidents:write
Request body:
{
"title": "Database latency spike",
"message": "We are investigating elevated response times.",
"status_page_id": "550e8400-e29b-41d4-a716-446655440000",
"component_id": "",
"notify_subscribers": true
}
| Field | Required | Description |
|---|---|---|
title | Yes | Short incident title |
status_page_id | Yes* | UUID of status page (*or component_id) |
component_id | Yes* | Component ID (*or status_page_id) |
message | No | Initial message shown to subscribers |
notify_subscribers | No | Send email to subscribers (default: false) |
New incidents always start in Investigating. Published incident fields are immutable; choose a different state later by appending an incident update.
Response: 201 Created with the created incident object. To make a create safe to retry, send a unique Idempotency-Key header; see Authenticated REST API Overview.
Legacy PATCH endpoint
PATCH /user/api/v1/incidents/:id
Required scope: incidents:write
Published incident fields cannot be replaced. The legacy endpoint accepts only append mode for compatibility:
{
"message": "The issue has been resolved.",
"incident_state_id": "4",
"append_update": true
}
Requests without append_update: true return 409 Conflict. New integrations should use the dedicated timeline-update endpoint below.
Add an incident update (timeline entry)
POST /user/api/v1/incidents/:id/updates
Required scope: incidents:write
Request body:
{
"message": "We have identified the root cause and are applying a fix.",
"incident_state_id": "2"
}
At least one of message or incident_state_id is required.
Response: 201 Created with the immutable timeline-update object. To make the append safe to retry, send a unique Idempotency-Key header.
An update can keep the current state or move the incident forward, for example from Investigating to Identified. It cannot move an incident back to an earlier state or back to Investigating. Resolved and archived incidents do not accept further timeline updates.
Retrieve a specific update with:
GET /user/api/v1/incidents/:id/updates/:update_id
Archive a resolved incident
DELETE /user/api/v1/incidents/:id
Required scope: incidents:write
This operation never deletes incident history. It archives a resolved incident when the status-page owner’s plan includes incident archiving. It returns 403 Forbidden when the plan does not include archiving and 409 Conflict while the incident is unresolved.
The request must include X-HSP-Archive-Incident: true to confirm archive intent. Without that header, the API returns 409 Conflict.
Incident state IDs
The incident_state_id field typically maps to:
| ID | Stage |
|---|---|
1 | Investigating |
2 | Identified |
3 | Monitoring |
4 | Resolved |
Exact IDs may vary — use the public status page or support docs to confirm your values.