> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uptimeio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](/api-reference/incidents/list) | List incidents | Yes |
| [`POST /api/incidents`](/api-reference/incidents/create) | Create an incident | Yes |
| [`GET /api/incidents/{id}`](/api-reference/incidents/get) | Get one incident | Yes |
| [`PUT /api/incidents/{id}`](/api-reference/incidents/update) | Update severity, message, regions, description | Yes |
| [`PUT /api/incidents/{id}/status`](/api-reference/incidents/update-status) | Change status | Yes |
| [`POST /api/incidents/{id}/acknowledge`](/api-reference/incidents/acknowledge) | Acknowledge | Yes |
| [`GET /api/incidents/{id}/affected-checks`](/api-reference/incidents/affected-checks) | Monitor affected by the incident | Yes |
| [`POST /api/incidents/{id}/updates`](/api-reference/incidents/add-update) | Add a note | Yes |
| [`GET /api/incidents/{id}/updates`](/api-reference/incidents/get-updates) | Change history | Yes |
| [`DELETE /api/incidents/{id}`](/api-reference/incidents/delete) | Delete an incident | No (JWT only) |
| [`GET/POST/PATCH/DELETE /api/incidents/{id}/comments`](/api-reference/incidents/comments) | Team comments | No (JWT only) |
| [`GET /api/incidents/{id}/notifications`](/api-reference/incidents/notifications) | Notification delivery log | No (JWT only) |

## Common workflows

Respond to an open incident:

```bash theme={null}
# 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](/api-reference/incidents/list).

## 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](/api-reference/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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.