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.

Response

201 Created with the new incident object:

{
  "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	Cause
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).

Example

cURL

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."
  }'