Incidents API

Manage incidents programmatically.

Overview

The Incidents API allows you to:

Create and update incidents
Add incident updates
Manage affected components
Create postmortems

Endpoints

Method	Endpoint	Description
GET	`/incidents`	List incidents
POST	`/incidents`	Create incident
GET	`/incidents/{id}`	Get incident
PATCH	`/incidents/{id}`	Update incident
DELETE	`/incidents/{id}`	Delete incident
POST	`/incidents/{id}/updates`	Add update

List Incidents

GET /api/v1/incidents

Query Parameters

Parameter	Type	Description
`status`	string	investigating, identified, monitoring, resolved
`impact`	string	minor, major, critical
`resolved`	boolean	Filter by resolved state
`componentId`	string	Filter by affected component
`from`	string	Start date (ISO 8601)
`to`	string	End date (ISO 8601)
`page`	number	Page number
`pageSize`	number	Items per page

Response

{
  "data": [
    {
      "id": "inc_123",
      "title": "API Response Delays",
      "status": "resolved",
      "impact": "major",
      "message": "We are investigating...",
      "components": [
        {
          "id": "comp_456",
          "name": "API Server",
          "status": "operational"
        }
      ],
      "updates": [...],
      "createdAt": "2026-01-22T10:00:00Z",
      "resolvedAt": "2026-01-22T11:30:00Z"
    }
  ],
  "meta": {
    "total": 50,
    "page": 1,
    "pageSize": 20
  }
}

Create Incident

POST /api/v1/incidents

Request Body

{
  "title": "API Response Delays",
  "status": "investigating",
  "impact": "major",
  "message": "We are investigating reports of slow API response times.",
  "componentIds": ["comp_456"],
  "componentStatuses": {
    "comp_456": "degraded_performance"
  }
}

Response

{
  "id": "inc_789",
  "title": "API Response Delays",
  "status": "investigating",
  "impact": "major",
  "message": "We are investigating...",
  "components": [...],
  "createdAt": "2026-01-22T10:00:00Z"
}

Get Incident

GET /api/v1/incidents/{id}

Query Parameters

Parameter	Type	Description
`include`	string	Comma-separated: updates, postmortem

Response

{
  "id": "inc_123",
  "title": "API Response Delays",
  "status": "resolved",
  "impact": "major",
  "message": "We are investigating...",
  "components": [...],
  "updates": [
    {
      "id": "upd_1",
      "status": "investigating",
      "message": "We are investigating...",
      "createdAt": "2026-01-22T10:00:00Z"
    },
    {
      "id": "upd_2",
      "status": "identified",
      "message": "Root cause identified...",
      "createdAt": "2026-01-22T10:30:00Z"
    }
  ],
  "postmortem": {
    "summary": "...",
    "rootCause": "...",
    "isPublished": true
  },
  "createdAt": "2026-01-22T10:00:00Z",
  "resolvedAt": "2026-01-22T11:30:00Z"
}

Update Incident

PATCH /api/v1/incidents/{id}

Request Body

{
  "title": "Updated Title",
  "impact": "critical"
}

Add Update

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

Request Body

{
  "status": "identified",
  "message": "We have identified the root cause as database connection pool exhaustion.",
  "componentStatuses": {
    "comp_456": "degraded_performance"
  }
}

Resolving

To resolve an incident:

{
  "status": "resolved",
  "message": "The issue has been resolved.",
  "componentStatuses": {
    "comp_456": "operational"
  }
}

Delete Incident

DELETE /api/v1/incidents/{id}

Response

{
  "success": true
}

Incident Object

Field	Type	Description
`id`	string	Unique identifier
`title`	string	Incident title
`status`	string	Current status
`impact`	string	Severity level
`message`	string	Initial/latest message
`components`	array	Affected components
`updates`	array	Status updates
`postmortem`	object	Postmortem content
`createdAt`	string	Creation timestamp
`resolvedAt`	string	Resolution timestamp

Status Values

Status	Description
`investigating`	Looking into the issue
`identified`	Root cause found
`monitoring`	Fix applied, watching
`resolved`	Issue fixed

Impact Values

Impact	Description
`minor`	Minimal user impact
`major`	Significant impact
`critical`	Service unavailable

Component Status Mapping

When creating/updating incidents, you can set affected component status:

Component Status	Description
`operational`	Normal operation
`degraded_performance`	Slow but working
`partial_outage`	Partial functionality
`major_outage`	Service down

Examples

Create Incident

curl -X POST https://your-domain.com/api/v1/incidents \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Database Connectivity Issues",
    "status": "investigating",
    "impact": "major",
    "message": "We are investigating reports of database connectivity issues.",
    "componentIds": ["comp_db"],
    "componentStatuses": {
      "comp_db": "major_outage"
    }
  }'

Add Update

curl -X POST https://your-domain.com/api/v1/incidents/inc_123/updates \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "identified",
    "message": "The database primary node has failed. Failover to replica in progress."
  }'

Resolve Incident

curl -X POST https://your-domain.com/api/v1/incidents/inc_123/updates \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "message": "Failover complete. All services restored.",
    "componentStatuses": {
      "comp_db": "operational"
    }
  }'

List Active Incidents

curl "https://your-domain.com/api/v1/incidents?resolved=false" \
  -H "Authorization: Bearer sk_live_xxx"

List Last 7 Days

curl "https://your-domain.com/api/v1/incidents?from=2026-01-15T00:00:00Z&to=2026-01-22T23:59:59Z" \
  -H "Authorization: Bearer sk_live_xxx"

Components Maintenances