Skip to main content

​
Overview

Create a new incident manually or for reporting system issues. Manual incidents allow you to record outages and issues detected outside of UptimeIO monitors. System incidents can also be created programmatically when you detect issues in your infrastructure.

​
Authentication

Requires API Key authentication:
  • API Key: X-API-Key: YOUR_API_KEY

​
Request Body

​
severity
string
required
Incident severity level. Valid values: critical, major, minor, warning
​
type
string
required
Incident type. Valid values: timeout, status_code, keyword_missing, ssl_error, dns_error, connection_error, slow_response
​
error_message
string
required
Description of the error or issue. Maximum 1000 characters.
​
check_id
string
Associated monitor/check ID (UUID). If provided, incident is treated as a system incident.
​
title
string
Incident title. For system incidents, auto-generated if not provided. For manual incidents, required if check_id is not provided. Maximum 255 characters.
​
source
string
default:"manual"
Incident source. Valid values: system, manual. Defaults to manual unless check_id is provided.
​
affected_regions
array
List of geographic regions affected by this incident. Defaults to empty array.
​
affected_monitor_ids
array
Array of monitor/check IDs (UUIDs) affected by this incident. Maximum 100 monitors. Defaults to empty array.
​
failure_count
number
default:"1"
Number of consecutive failures. Defaults to 1.
​
status_page_update
string
Custom status page update text. Maximum 1000 characters.
​
started_at
string
ISO 8601 datetime when the incident started. If not provided, current time is used.

​
Request Validation

  • Manual Incident: Either title or check_id must be provided
  • Title Required: If source=manual and check_id is not provided, title is required
  • Check Relationship: If both title and check_id are provided, the incident can reference a specific monitor while having a custom title

​
Response Format

​
success
boolean
Whether the incident was created successfully
​
data
object

​
Example Requests

curl -X POST 'https://api.uptimeio.com/api/incidents' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Third-party API outage",
    "severity": "critical",
    "type": "connection_error",
    "error_message": "Payment gateway API is completely down",
    "affected_monitor_ids": [
      "660e8400-e29b-41d4-a716-446655440000",
      "770e8400-e29b-41d4-a716-446655440001"
    ],
    "affected_regions": ["us-east-1", "eu-west-1"],
    "status_page_update": "We are experiencing issues with our payment processing due to third-party API outage"
  }'

​
Example Responses

{
  "success": true,
  "data": {
    "incident": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "check_id": null,
      "check_name": null,
      "check_url": null,
      "status": "open",
      "severity": "critical",
      "type": "connection_error",
      "title": "Third-party API outage",
      "error_message": "Payment gateway API is completely down",
      "started_at": 1703001600000,
      "resolved_at": null,
      "affected_regions": ["us-east-1", "eu-west-1"],
      "failure_count": 1,
      "notification_sent": true,
      "created_at": 1703001600000
    }
  }
}

​
Status Codes

StatusDescription
201 CreatedIncident successfully created
400 Bad RequestInvalid request parameters or validation failed
401 UnauthorizedAuthentication failed or invalid credentials
500 Internal Server ErrorServer error during incident creation

​
Error Codes

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Manual incidents must have a title",
    "details": {
      "title": "Manual incidents must have a title"
    }
  }
}

​
Notes

  • Incident status always starts as open when created
  • Notifications are sent automatically based on organization notification settings
  • The affected_regions should use geographic region identifiers (e.g., “us-east-1”, “eu-west-1”)
  • Use affected_monitor_ids to indicate which monitors are affected by the incident
  • Manual incidents are useful for recording issues detected by external monitoring or customer reports