Incidents API

Overview

The Incidents API provides comprehensive tools for managing, tracking, and resolving incidents detected by UptimeIO monitors or reported manually by your team. Incidents represent outages, degradations, or anomalies in your monitored services.

Core Concepts

Incident Status Lifecycle

Incidents follow a strict workflow through their lifecycle:

open ──acknowledge──> acknowledged ──resolve──> resolved ──close──> closed
  └────────────────────────────────────────────────────────────┘
                    direct resolution path

Status	Meaning
open	Initial state when incident is detected or created. Requires attention from team.
acknowledged	Team member has seen the incident and is working on it.
resolved	Technical issue has been fixed and service is restored.
closed	Post-incident work is complete. Terminal state - no further changes allowed.

Incident Severity

Incidents are classified by severity level:

Level	Usage
critical	Complete service outage, all users affected, data loss risk
major	Significant degradation, many users affected, feature unavailable
minor	Limited impact, few users affected, workaround available
warning	Potential issues, no immediate impact, preventive action needed

Incident Types

Each incident is categorized by the type of failure detected:

timeout - Request exceeded timeout threshold
status_code - Unexpected HTTP status code returned
keyword_missing - Expected content not found in response
ssl_error - SSL/TLS certificate validation failed
dns_error - DNS resolution failed
connection_error - TCP connection refused or lost
slow_response - Response time exceeded expected threshold

Incident Sources

Incidents can originate from two sources:

Source	Description
system	Automatically detected by UptimeIO monitoring probes
manual	Created by team members via API to report external issues

Authentication

All Incidents API endpoints require authentication via either:

API Key: X-API-Key: YOUR_API_KEY

The header is required for all endpoint requests.

Endpoint Overview

List & Retrieve

List Incidents

GET /api/incidents - Retrieve all incidents with filtering and pagination

Get Incident

GET /api/incidents/ - Get complete details for a specific incident

Create & Modify

Create Incident

POST /api/incidents - Create a manual incident or system incident record

Update Incident

PUT /api/incidents/ - Update incident fields (severity, message, regions)

Status Management

Update Status

PUT /api/incidents//status - Change incident status through workflow

Acknowledge

POST /api/incidents//acknowledge - Quick acknowledge shorthand

Details & Timeline

Affected Checks

GET /api/incidents//affected-checks - Get monitors affected by incident

Add Update

POST /api/incidents//updates - Add comment to incident timeline

Get Updates

GET /api/incidents//updates - View incident timeline with all changes

Common Workflows

Quick Incident Response

List active incidents: GET /api/incidents?status=open
Acknowledge incident: POST /api/incidents/{id}/acknowledge
Add investigation update: POST /api/incidents/{id}/updates
Update status: PUT /api/incidents/{id}/status

Manual Incident Reporting

When you detect an issue outside of UptimeIO monitoring:

# Create manual incident
POST /api/incidents
{
  "title": "Payment gateway timeout",
  "severity": "critical",
  "type": "timeout",
  "error_message": "Third-party payment API not responding",
  "affected_monitor_ids": ["check-1", "check-2"]
}

Incident Investigation

Get complete incident context:

# Get incident details
GET /api/incidents/{id}

# Get affected monitors
GET /api/incidents/{id}/affected-checks

# Get investigation timeline
GET /api/incidents/{id}/updates

Resolution & Closure

Move incident through completion:

# Add final update
POST /api/incidents/{id}/updates
{
  "message": "Issue resolved, all services restored"
}

# Transition to resolved
PUT /api/incidents/{id}/status
{
  "status": "resolved"
}

# When ready, close incident
PUT /api/incidents/{id}/status
{
  "status": "closed"
}

Rate Limiting

All API endpoints are subject to rate limiting based on your subscription plan:

Free Plan: 60 requests per minute
Pro Plan: 600 requests per minute
Enterprise: Custom limits

Rate limit headers are included in all responses:

X-RateLimit-Limit - Total allowed requests
X-RateLimit-Remaining - Requests remaining in current window
X-RateLimit-Reset - Unix timestamp when limit resets

Error Codes

All endpoints follow consistent error response format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional context"
    }
  }
}

Common Error Codes

Code	Status	Meaning
`VALIDATION_ERROR`	400	Invalid request parameters
`AUTHENTICATION_ERROR`	401	Missing or invalid authentication
`FORBIDDEN`	403	Authenticated but not authorized
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Invalid state transition
`INTERNAL_ERROR`	500	Server error

Response Format

All successful responses follow this format:

{
  "success": true,
  "data": {
    // Endpoint-specific data
  },
  "pagination": {
    // Present in list endpoints
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5,
    "hasNext": true,
    "hasPrevious": false
  }
}

Pagination

List endpoints support cursor-based pagination:

GET /api/incidents?limit=20&offset=0

Query parameters:

limit - Items per page (1-100, default: 20)
offset - Number of items to skip (default: 0)
sort_by - Field to sort by (default: created_at)
sort_order - Sort direction: asc or desc (default: desc)

Filtering

The list endpoint supports several filters:

# Filter by status
GET /api/incidents?status=open

# Filter by severity
GET /api/incidents?severity=critical

# Filter by monitor
GET /api/incidents?check_id=<uuid>

# Polling for changes
GET /api/incidents?since=1703001300000

Integrations

The Incidents API integrates with:

Monitoring Probes: System incidents are created automatically
Notification System: Incidents trigger alerts and notifications
Status Pages: Incidents can update public status pages
Audit Logs: All changes are tracked for compliance
Webhooks: External systems can create and update incidents

Introduction

Monitors

Groups

Incidents

Status Pages

Status Page Incidents

Overview

Core Concepts

Incident Status Lifecycle

Incident Severity

Incident Types

Incident Sources

Authentication

Endpoint Overview

List & Retrieve

List Incidents

Get Incident

Create & Modify

Create Incident

Update Incident

Status Management

Update Status

Acknowledge

Details & Timeline

Affected Checks

Add Update

Get Updates

Common Workflows

Quick Incident Response

Manual Incident Reporting

Incident Investigation

Resolution & Closure

Rate Limiting

Error Codes

Common Error Codes

Response Format

Filtering

Integrations

Introduction

Monitors

Groups

Incidents

Status Pages

Status Page Incidents

​Overview

​Core Concepts

​Incident Status Lifecycle

​Incident Severity

​Incident Types

​Incident Sources

​Authentication

​Endpoint Overview

​List & Retrieve

List Incidents

Get Incident

​Create & Modify

Create Incident

Update Incident

​Status Management

Update Status

Acknowledge

​Details & Timeline

Affected Checks

Add Update

Get Updates

​Common Workflows

​Quick Incident Response

​Manual Incident Reporting

​Incident Investigation

​Resolution & Closure

​Rate Limiting

​Error Codes

​Common Error Codes

​Response Format

​Pagination

​Filtering

​Integrations

Overview

Core Concepts

Incident Status Lifecycle

Incident Severity

Incident Types

Incident Sources

Authentication

Endpoint Overview

List & Retrieve

Create & Modify

Status Management

Details & Timeline

Common Workflows

Quick Incident Response

Manual Incident Reporting

Incident Investigation

Resolution & Closure

Rate Limiting

Error Codes

Common Error Codes

Response Format

Pagination

Filtering

Integrations