AUTHENTICATION
All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard under the API Keys section.
Header format
curl https://<your-api-base-url>/api/v1/status \
-H "Authorization: Bearer sk_live_..."Keep keys secret. API keys grant full read/write access to your status page. Rotate compromised keys immediately from the dashboard.
Each API key is scoped to a single status page. Use your deployment's API base URL:
https://<your-api-base-url>Append endpoint paths from this reference to your API base URL (for example, /api/v1/status).
RATE LIMITS
Rate limits are enforced per API key. Exceeding the limit returns 429 with a Retry-After header (seconds).
| TYPE | METHODS | LIMIT |
|---|---|---|
| Read | GET | 120 requests / minute |
| Write | POST, PATCH | 60 requests / minute |
ERRORS
All errors return a JSON object with an error field containing code and message.
Error format
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}Error codes
| CODE | STATUS | DESCRIPTION |
|---|---|---|
| UNAUTHORIZED | 401 | Missing or invalid API key |
| NOT_FOUND | 404 | Resource does not exist or does not belong to this API key's page |
| BAD_REQUEST | 400 | Missing required fields or invalid parameter values |
| RATE_LIMITED | 429 | Too many requests. Check the Retry-After header. |
READ ENDPOINTS
Retrieve status page data. Authenticated with Bearer token. 120 requests per minute.
/api/v1/statusReturns the status page summary including name, slug, and description.
Response 200
{
"name": "Acme Corp",
"slug": "acme-corp",
"description": "Status updates for Acme services"
}/api/v1/componentsReturns all components for the status page with their current status and display order.
Response 200
{
"components": [
{
"_id": "abc123",
"name": "API",
"status": "operational",
"displayOrder": 0,
"description": "Core API service"
}
]
}/api/v1/incidentsReturns incidents for the status page. Optionally filter to active incidents only.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| status | query | string | Pass "active" to return only unresolved incidents |
Response 200
{
"incidents": [
{
"_id": "inc_1",
"title": "API latency spike",
"status": "investigating",
"severity": "major",
"createdAt": 1700000000000
}
]
}/api/v1/incidents/detailReturns a single incident with all its updates.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| id* | query | string | The incident ID |
Response 200
{
"incident": {
"_id": "inc_1",
"title": "API latency spike",
"status": "resolved",
"severity": "major"
},
"updates": [
{
"status": "investigating",
"message": "Looking into elevated p99 latency",
"createdAt": 1700000000000
}
]
}WRITE ENDPOINTS
Create and modify incidents and components. Authenticated with Bearer token. 60 requests per minute.
/api/v1/incidentsCreates a new incident and notifies subscribers.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| title* | body | string | Incident title (max 120 chars) |
| severity* | body | string | "minor", "major", or "critical" |
| message* | body | string | Initial update message |
| affectedComponentIds | body | string[] | Array of component IDs to mark as affected |
Request
curl -X POST https://<your-api-base-url>/api/v1/incidents \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"title": "Database connectivity issues",
"severity": "major",
"message": "Investigating connection timeouts to primary DB"
}'Response 201
{
"incident": {
"_id": "inc_2",
"title": "Database connectivity issues",
"status": "investigating",
"severity": "major"
}
}/api/v1/incidents/updatesAdds an update to an existing incident and notifies subscribers.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| incidentId* | query | string | The incident ID |
| status* | body | string | "investigating", "identified", "monitoring", "update", or "resolved" |
| message* | body | string | Update message |
Request
curl -X POST "https://<your-api-base-url>/api/v1/incidents/updates?incidentId=inc_2" \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"status": "identified",
"message": "Root cause identified: connection pool exhaustion"
}'Response 200
{ "success": true }/api/v1/incidents/resolveMarks an incident as resolved and notifies subscribers.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| incidentId* | query | string | The incident ID |
| message | body | string | Optional resolution message |
Request
curl -X POST "https://<your-api-base-url>/api/v1/incidents/resolve?incidentId=inc_2" \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "message": "Connection pool resized, latency nominal" }'Response 200
{ "success": true }/api/v1/components/statusChanges the status of a single component.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| componentId* | query | string | The component ID |
| status* | body | string | "operational", "degraded", "partial_outage", "major_outage", or "maintenance" |
Request
curl -X PATCH "https://<your-api-base-url>/api/v1/components/status?componentId=abc123" \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "status": "degraded" }'Response 200
{ "success": true }