> ## 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.

# Create Incident

> Record a manual incident, or attach one to a monitor

## Overview

Creates an incident with status `open`. Use it to record problems UptimeIO cannot see, such as a third-party outage, or to open an incident against a specific monitor.

`POST /api/incidents`

## Authentication

`X-API-Key: YOUR_API_KEY` (`read_write` scope) or `Authorization: Bearer YOUR_JWT`. The user also needs the `can_manage_incidents` permission.

## Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `severity` | string | Yes | `critical`, `major`, `minor` or `warning`. |
| `type` | string | Yes | `timeout`, `status_code`, `keyword_missing`, `ssl_error`, `dns_error`, `dns_validation_error`, `connection_error` or `slow_response`. |
| `error_message` | string | Yes | 1-1000 characters. |
| `title` | string | See rules | 1-255 characters. |
| `check_id` | UUID | See rules | Monitor the incident relates to. |
| `source` | string | No | `system` or `manual`. Defaults to `system` when `check_id` is given, otherwise `manual`. |
| `status_page_update` | string | No | Up to 1000 characters. |
| `affected_regions` | string\[] | No | Default `[]`. |
| `affected_monitor_ids` | UUID\[] | No | Up to 100 monitor IDs. Default `[]`. |
| `failure_count` | integer | No | Minimum 1. Default `1`. |
| `started_at` | string | No | ISO 8601 datetime (for example `2026-09-30T09:12:04Z`). Defaults to now. |

Rules:

* At least one of `title` or `check_id` is required.
* A manual incident (no `check_id`, or `source: "manual"`) requires a `title`.
* `source: "system"` requires a `check_id`.

## Example

```bash theme={null}
curl -X POST https://api.uptimeio.com/api/incidents \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Payment gateway outage",
    "severity": "critical",
    "type": "connection_error",
    "error_message": "Third-party payment API is unreachable",
    "affected_regions": ["europe"],
    "status_page_update": "We are investigating payment failures."
  }'
```

## Response

`201 Created` with the new [incident object](/api-reference/incidents/get#incident-object):

```json theme={null}
{
  "success": true,
  "data": {
    "incident": {
      "id": "3f6c1a52-9d1e-4b0a-8f7d-2a1b3c4d5e6f",
      "organization_id": "0b0f7a0e-2c3d-4f55-9a11-6f1c2f1d9a10",
      "project_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "open",
      "severity": "critical",
      "type": "connection_error",
      "source": "manual",
      "title": "Payment gateway outage",
      "status_page_update": "We are investigating payment failures.",
      "started_at": "2026-09-30T10:05:00.000Z",
      "error_message": "Third-party payment API is unreachable",
      "affected_regions": ["europe"],
      "failure_count": 1,
      "notification_sent": false,
      "notification_channels": [],
      "acknowledged_by_name": null,
      "created_at": "2026-09-30T10:05:00.000Z",
      "updated_at": "2026-09-30T10:05:00.000Z"
    }
  }
}
```

## Errors

| Status | Code | When |
| - | - | - |
| `400` | `VALIDATION_ERROR` | Field validation failed, for example `Manual incidents must have a title` or `Either check_id or title must be provided`. `details.errors` names the field. |
| `401` | `MISSING_AUTH`, `INVALID_API_KEY`, `INVALID_TOKEN` | Missing or invalid credentials. |
| `403` | `READ_ONLY_API_KEY`, `INSUFFICIENT_PERMISSIONS` | Key is read-only, or the user cannot manage incidents. |
| `500` | `INTERNAL_ERROR` | Also returned today for `source: "system"` without a `check_id` (message `System incidents must have a check_id`). |


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