Incidents API

List, create, update and resolve incidents

Overview

An incident records an outage or degradation of a monitor, or an issue your team reports manually. UptimeIO opens and resolves system incidents for you; the API lets you read them, acknowledge and resolve them, and record incidents for problems detected elsewhere.

Authentication

Send one of:

• X-API-Key: YOUR_API_KEY: API keys with read scope can call the read endpoints; write endpoints (POST, PUT) need read_write scope.
• Authorization: Bearer YOUR_JWT

Write endpoints also require the can_manage_incidents permission for the authenticated user. Without it they return 403 INSUFFICIENT_PERMISSIONS.

Incidents are scoped to your organization and project. JWT users may add X-Organization-ID and X-Project-ID headers to choose them; otherwise the defaults apply. An API key is tied to one organization.

Concepts

Status lifecycle

Status	Meaning	Allowed next status
open	Detected or created; needs attention.	acknowledged, resolved
acknowledged	Someone is working on it.	resolved, closed
resolved	Service restored.	closed
closed	Finished.	none

Transitions outside this table, including setting the status an incident already has, are rejected with 400 VALIDATION_ERROR.

Severity

critical, major, minor, warning.

Types

Type	Meaning
timeout	The request timed out.
status_code	Unexpected HTTP status code.
keyword_missing	Expected content not found (or forbidden content found).
ssl_error	TLS certificate invalid or expired.
dns_error	DNS resolution failed.
dns_validation_error	DNS records did not match what the monitor expects.
connection_error	Connection refused or lost.
slow_response	Response time exceeded the monitor’s threshold.

Sources

system (opened by UptimeIO) or manual (created through the API or dashboard).

Timestamps

Incident timestamps (started_at, created_at, resolved_at, …) are ISO 8601 strings in UTC.

Endpoints

Method and path	Purpose	API key
GET /api/incidents	List incidents	Yes
POST /api/incidents	Create an incident	Yes
GET /api/incidents/{id}	Get one incident	Yes
PUT /api/incidents/{id}	Update severity, message, regions, description	Yes
PUT /api/incidents/{id}/status	Change status	Yes
POST /api/incidents/{id}/acknowledge	Acknowledge	Yes
GET /api/incidents/{id}/affected-checks	Monitor affected by the incident	Yes
POST /api/incidents/{id}/updates	Add a note	Yes
GET /api/incidents/{id}/updates	Change history	Yes
DELETE /api/incidents/{id}	Delete an incident	No (JWT only)
GET/POST/PATCH/DELETE /api/incidents/{id}/comments	Team comments	No (JWT only)
GET /api/incidents/{id}/notifications	Notification delivery log	No (JWT only)

Common workflows

Respond to an open incident:

# 1. Find open incidents
curl "https://api.uptimeio.com/api/incidents?status=open" -H "X-API-Key: YOUR_API_KEY"

# 2. Acknowledge
curl -X POST https://api.uptimeio.com/api/incidents/INCIDENT_ID/acknowledge \
  -H "X-API-Key: YOUR_API_KEY"

# 3. Resolve with a note
curl -X PUT https://api.uptimeio.com/api/incidents/INCIDENT_ID/status \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "status": "resolved", "note": "Rolled back the faulty deploy" }'

Poll for changes using since (a Unix timestamp in milliseconds) on List Incidents.

Responses and errors

Successful responses use { "success": true, "data": ... }. The list endpoint returns its paging fields inside data, not in a top-level pagination object. Errors use { "success": false, "error": { "code", "message", "details"? } }; see Errors.

Status	Code	Meaning
400	VALIDATION_ERROR	Invalid body, query or path parameter, or an invalid status transition.
401	MISSING_AUTH, INVALID_API_KEY, INVALID_TOKEN	Missing or invalid credentials.
403	READ_ONLY_API_KEY, INSUFFICIENT_PERMISSIONS, JWT_REQUIRED	Key is read-only, user lacks can_manage_incidents, or the endpoint is session-only.
404	RESOURCE_NOT_FOUND	Incident not found in your project.
500	INTERNAL_ERROR	Unexpected failure.