Incidents API

Incidents track service disruptions and outages detected by your monitors. They can be created automatically when monitors go down or manually for planned announcements.

All incident endpoints require authentication. Include the Authorization: Bearer {token} header with all requests.

Incident Status Flow

INVESTIGATING → IDENTIFIED → MONITORING → RESOLVED

Status	Description
`INVESTIGATING`	Initial state, team is investigating the issue
`IDENTIFIED`	Root cause has been identified
`MONITORING`	Fix deployed, monitoring for stability
`RESOLVED`	Incident is resolved

Severity Levels

Severity	Description
`CRITICAL`	Complete service outage
`HIGH`	Major functionality impacted
`MEDIUM`	Partial degradation
`LOW`	Minor issue, minimal impact

List Incidents

GET/api/incidents

Retrieve all incidents for monitors owned by the authenticated user

Headers:

Header	Value
Authorization	`Bearer {access_token}`

Query Parameters:

Parameter	Type	Required	Description
`severity`	string	No	Filter by severity: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`

Success Response (200 OK):

{
  "incidents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "monitor_id": "monitor-uuid",
      "monitor_name": "Production API",
      "title": "API Degraded Performance",
      "status": "INVESTIGATING",
      "severity": "HIGH",
      "acknowledged": false,
      "started_at": "2024-01-15T10:30:00Z",
      "resolved_at": null,
      "escalation_policy_id": "policy-uuid",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "monitor_id": "monitor-uuid-2",
      "monitor_name": "Database Server",
      "title": "Database Connection Issues",
      "status": "RESOLVED",
      "severity": "CRITICAL",
      "acknowledged": true,
      "started_at": "2024-01-14T08:00:00Z",
      "resolved_at": "2024-01-14T09:30:00Z",
      "escalation_policy_id": null,
      "created_at": "2024-01-14T08:00:00Z"
    }
  ]
}

Get Incident

GET/api/incidents/:id

Retrieve a single incident with detailed information

Path Parameters:

Parameter	Type	Description
`id`	UUID	Incident ID

Headers:

Header	Value
Authorization	`Bearer {access_token}`

Success Response (200 OK):

{
  "incident": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "monitor_id": "monitor-uuid",
    "monitor_name": "Production API",
    "title": "API Degraded Performance",
    "status": "INVESTIGATING",
    "severity": "HIGH",
    "acknowledged": true,
    "started_at": "2024-01-15T10:30:00Z",
    "resolved_at": null,
    "escalation_policy_id": "policy-uuid",
    "created_at": "2024-01-15T10:30:00Z",
    "acknowledgement": {
      "id": "ack-uuid",
      "incident_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "user-uuid",
      "user_name": "John Doe",
      "user_email": "john@example.com",
      "method": "web",
      "acknowledged_at": "2024-01-15T10:35:00Z"
    },
    "escalation_steps": [
      {
        "step_order": 1,
        "delay_minutes": 0
      },
      {
        "step_order": 2,
        "delay_minutes": 15
      },
      {
        "step_order": 3,
        "delay_minutes": 30
      }
    ]
  }
}

The acknowledgement field is only present if the incident has been acknowledged. The escalation_steps field is only present if the incident has an associated escalation policy.

Create Incident

POST/api/incidents

Manually create a new incident

Headers:

Header	Value
Authorization	`Bearer {access_token}`
Content-Type	application/json

Request Body:

Field	Type	Required	Default	Validation
`monitorId`	UUID	Yes	-	Must be a monitor owned by user
`title`	string	Yes	-	1-200 characters
`message`	string	No	-	Additional context
`severity`	string	No	`MEDIUM`	`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`

Request Example:

{
  "monitorId": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Scheduled Database Maintenance",
  "message": "Performing database upgrade, expect brief interruptions",
  "severity": "LOW"
}

Success Response (201 Created):

{
  "incident": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "monitor_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Scheduled Database Maintenance",
    "status": "INVESTIGATING",
    "severity": "LOW",
    "acknowledged": false,
    "started_at": "2024-01-15T12:00:00Z",
    "resolved_at": null,
    "created_at": "2024-01-15T12:00:00Z"
  }
}

When an incident is created, status page subscribers are automatically notified.

Error Responses:

Status	Error	Description
400	Validation errors	Invalid request body
404	`Monitor not found`	Monitor doesn't exist or not owned by user

Update Incident

PUT/api/incidents/:id

Update an incident's status, severity, or title

Path Parameters:

Parameter	Type	Description
`id`	UUID	Incident ID

Headers:

Header	Value
Authorization	`Bearer {access_token}`
Content-Type	application/json

Request Body:

Field	Type	Required	Validation
`status`	string	No	`INVESTIGATING`, `IDENTIFIED`, `MONITORING`, `RESOLVED`
`severity`	string	No	`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`
`title`	string	No	1-200 characters

At least one field must be provided for an update.

Request Example - Update Status:

{
  "status": "IDENTIFIED"
}

Request Example - Resolve Incident:

{
  "status": "RESOLVED"
}

Success Response (200 OK):

{
  "incident": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "monitor_id": "monitor-uuid",
    "title": "API Degraded Performance",
    "status": "IDENTIFIED",
    "severity": "HIGH",
    "acknowledged": true,
    "started_at": "2024-01-15T10:30:00Z",
    "resolved_at": null,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

When status is changed to RESOLVED, the resolved_at timestamp is automatically set. Subscribers are notified of all status changes.

Acknowledge Incident

POST/api/incidents/:id/acknowledge

Acknowledge an incident to stop escalation

Acknowledging an incident indicates that someone is actively working on it. This stops any further escalation notifications.

Path Parameters:

Parameter	Type	Description
`id`	UUID	Incident ID

Headers:

Header	Value
Authorization	`Bearer {access_token}`
Content-Type	application/json

Request Body (Optional):

Field	Type	Required	Default	Description
`method`	string	No	`web`	How the incident was acknowledged

Acknowledgment Methods:

web - Acknowledged via web dashboard
api - Acknowledged via API call
slack - Acknowledged via Slack integration
email - Acknowledged via email link
sms - Acknowledged via SMS reply

Request Example:

{
  "method": "api"
}

Success Response (200 OK):

{
  "incident": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "monitor_id": "monitor-uuid",
    "title": "API Degraded Performance",
    "status": "INVESTIGATING",
    "severity": "HIGH",
    "acknowledged": true,
    "started_at": "2024-01-15T10:30:00Z",
    "resolved_at": null,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error Responses:

Status	Error	Description
400	`Incident already acknowledged`	Incident was previously acknowledged
404	`Incident not found`	Incident doesn't exist or not owned by user

Resolve Incident

DELETE/api/incidents/:id

Quickly resolve an incident

This is a convenience endpoint that sets the incident status to RESOLVED and sets resolved_at to the current timestamp.

Path Parameters:

Parameter	Type	Description
`id`	UUID	Incident ID

Headers:

Header	Value
Authorization	`Bearer {access_token}`

Success Response (200 OK):

{
  "message": "Incident resolved"
}

Use PUT /api/incidents/:id with {"status": "RESOLVED"} if you want the full incident object returned.

Incident Lifecycle

Automatic Incidents

When a monitor detects a failure that exceeds the failure_threshold, an incident is automatically created:

Incident Created - Status: INVESTIGATING, subscribers notified
Escalation Started - If escalation policy is configured, notifications begin
Acknowledged - Team member acknowledges, escalation stops
Status Updates - Team updates status as investigation progresses
Resolved - Monitor recovers or team marks resolved, resolved_at set

Manual Incidents

For planned maintenance or manual announcements:

Create Incident - Use POST /api/incidents with appropriate severity
Update Status - Progress through IDENTIFIED → MONITORING as needed
Resolve - Use PUT /api/incidents/:id with {"status": "RESOLVED"}

Subscriber Notifications

Incidents automatically trigger notifications to status page subscribers:

Event	Notification Sent
Incident created	"New incident" notification
Status changed	"Incident update" notification
Incident resolved	"Incident resolved" notification

Error Responses

Status	Error	Description
400	Validation errors	Invalid request body
400	`No updates provided`	PUT request with no fields to update
400	`Incident already acknowledged`	Trying to acknowledge twice
404	`Incident not found`	Incident doesn't exist or not authorized
404	`Monitor not found`	Monitor ID invalid when creating incident
500	`Failed to fetch/create/update incident`	Server error