Create Incident

curl --request POST \
  --url "https://api.scaling.cloud/v1/incidents" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Payment service elevated error rate",
    "description": "The payment processing service is returning 5xx errors at 12% above baseline.",
    "severity": "critical",
    "leadScheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "componentIds": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"]
  }'

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "org_01HX4K9MNPQRST",
    "title": "Payment service elevated error rate",
    "severity": "critical",
    "status": "investigating",
    "affectedComponents": [
      { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "Payments API" }
    ],
    "createdAt": "2025-04-07T08:23:11.000Z",
    "updatedAt": "2025-04-07T08:23:11.000Z"
  }
}

{
  "statusCode": 401,
  "type": "not_authorized_error",
  "code": "not_authorized",
  "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
}

{
  "statusCode": 400,
  "type": "invalid_request_error",
  "code": "invalid_component_id",
  "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
}

{
  "statusCode": 404,
  "type": "invalid_request_error",
  "code": "not_found",
  "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
}

{
  "statusCode": 500,
  "type": "invalid_error",
  "code": "server_error",
  "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
}

POST

incidents

curl --request POST \
  --url "https://api.scaling.cloud/v1/incidents" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Payment service elevated error rate",
    "description": "The payment processing service is returning 5xx errors at 12% above baseline.",
    "severity": "critical",
    "leadScheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "componentIds": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"]
  }'

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "org_01HX4K9MNPQRST",
    "title": "Payment service elevated error rate",
    "severity": "critical",
    "status": "investigating",
    "affectedComponents": [
      { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "Payments API" }
    ],
    "createdAt": "2025-04-07T08:23:11.000Z",
    "updatedAt": "2025-04-07T08:23:11.000Z"
  }
}

{
  "statusCode": 401,
  "type": "not_authorized_error",
  "code": "not_authorized",
  "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
}

{
  "statusCode": 400,
  "type": "invalid_request_error",
  "code": "invalid_component_id",
  "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
}

{
  "statusCode": 404,
  "type": "invalid_request_error",
  "code": "not_found",
  "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
}

{
  "statusCode": 500,
  "type": "invalid_error",
  "code": "server_error",
  "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
}

Creates a new incident and sets its initial status to investigating. Pass leadId to assign a specific user, or leadScheduleId to let the server resolve the current on-call responder and attach a matching escalation policy — at least one is required.

Request body

title

string

required

Short title describing the incident. Must be between 1 and 100 characters.

description

string

Optional longer description providing additional context about the incident. Up to 10,000 characters.

severity

string

required

Severity level of the incident. One of critical, high, medium, or low.

At least one of leadId or leadScheduleId is required so the paging path always has a target — a request without either is rejected with 400.

leadId

string

User ID to assign directly as the incident lead. Use this when you already know exactly who should be paged (e.g. the engineer who shipped the change). If leadScheduleId is also supplied, leadId wins for the resolved lead and the schedule is still used to attach an escalation policy.

leadScheduleId

string

UUID of an on-call schedule. The server resolves the current on-call responder (honouring active overrides) as the incident lead and attaches an escalation policy whose layers target this schedule (if one exists). If no one is currently on-call, the incident is still created without a lead. Returns 404 if the schedule does not exist in your organization.

componentIds

array of string

UUIDs of affected components, up to 50. Each ID must reference a component in your organization, and duplicates are rejected.

Choose severity based on customer and business impact, not just technical scope:

critical — Full outage or data loss affecting all or most customers.
high — Significant degradation affecting a large portion of customers or a key feature.
medium — Partial degradation with a workaround available, or affecting a minority of customers.
low — Minor issue with minimal customer impact, or a cosmetic/non-functional defect.

Setting the right severity ensures the correct on-call team is paged and escalation timelines are applied accurately.

Response

Returns 201 Created with the new incident.

data

object

required

Hide properties

string

required

Unique identifier for the incident (UUID).

orgId

string

required

The organization this incident belongs to.

title

string

required

Short title describing the incident.

severity

string

required

Severity level: critical, high, medium, or low.

status

string

required

Always investigating for a newly created incident.

affectedComponents

array of object

required

Components affected by this incident. Each entry has id and name. Empty array if no components were specified.

createdAt

string

required

ISO 8601 timestamp of when the incident was created.

updatedAt

string

required

ISO 8601 timestamp of when the incident was last updated.

Error responses

Status	Code	Description
`400`	`invalid_component_id`	One of the `componentIds` does not exist in your organization.
`400`	`duplicate_component_id`	`componentIds` contains duplicate entries.
`400`	—	Request body failed validation (e.g. `title` exceeds 100 characters, `severity` is not a valid value, or neither `leadId` nor `leadScheduleId` was supplied).
`401`	`not_authorized`	Missing or invalid API key.
`404`	`not_found`	The `leadScheduleId` does not refer to a schedule in your organization.
`500`	`server_error`	An unexpected error occurred on our side.

curl --request POST \
  --url "https://api.scaling.cloud/v1/incidents" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Payment service elevated error rate",
    "description": "The payment processing service is returning 5xx errors at 12% above baseline.",
    "severity": "critical",
    "leadScheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "componentIds": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"]
  }'

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "org_01HX4K9MNPQRST",
    "title": "Payment service elevated error rate",
    "severity": "critical",
    "status": "investigating",
    "affectedComponents": [
      { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "Payments API" }
    ],
    "createdAt": "2025-04-07T08:23:11.000Z",
    "updatedAt": "2025-04-07T08:23:11.000Z"
  }
}

{
  "statusCode": 401,
  "type": "not_authorized_error",
  "code": "not_authorized",
  "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
}

{
  "statusCode": 400,
  "type": "invalid_request_error",
  "code": "invalid_component_id",
  "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
}

{
  "statusCode": 404,
  "type": "invalid_request_error",
  "code": "not_found",
  "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
}

{
  "statusCode": 500,
  "type": "invalid_error",
  "code": "server_error",
  "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
}

List Incidents Get Incident

Overview

Incidents

On-call Schedules

Escalation Policies

Routing Policies

Working Hours

Team

Request body

Response

Error responses

​Request body

​Response

​Error responses

Request body

Response

Error responses