Incidents API

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.

Introduction

Monitors

Groups

Incidents

Status Pages

Status Page Incidents

Overview

Authentication

Concepts

Status lifecycle

Severity

Types

Sources

Timestamps

Endpoints

Common workflows

Responses and errors

​Overview

​Authentication

​Concepts

​Status lifecycle

​Severity

​Types

​Sources

​Timestamps

​Endpoints

​Common workflows

​Responses and errors

Overview

Authentication

Concepts

Status lifecycle

Severity

Types

Sources

Timestamps

Endpoints

Common workflows

Responses and errors