Skip to main content
POST
/
v1
/
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",
    "ownerScheduleId": "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"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.scaling.cloud/llms.txt

Use this file to discover all available pages before exploring further.

Creates a new incident and sets its initial status to investigating. Pass ownerId to assign a specific user, or ownerScheduleId 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 ownerId or ownerScheduleId is required so the paging path always has a target — a request without either is rejected with 400.
​
ownerId
string
User ID to assign directly as the incident owner. Use this when you already know exactly who should be paged (e.g. the engineer who shipped the change). If ownerScheduleId is also supplied, ownerId wins for the resolved owner and the schedule is still used to attach an escalation policy.
​
ownerScheduleId
string
UUID of an on-call schedule. The server resolves the current on-call responder (honouring active overrides) as the incident owner 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 an owner. 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

​
Error responses

StatusCodeDescription
400invalid_component_idOne of the componentIds does not exist in your organization.
400duplicate_component_idcomponentIds contains duplicate entries.
400—Request body failed validation (e.g. title exceeds 100 characters, severity is not a valid value, or neither ownerId nor ownerScheduleId was supplied).
401not_authorizedMissing or invalid API key.
404not_foundThe ownerScheduleId does not refer to a schedule in your organization.
500server_errorAn 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",
    "ownerScheduleId": "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"
  }
}