Update Status

curl --request PATCH \
  --url "https://api.scaling.cloud/v1/incidents/YOUR_INCIDENT_ID/status" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "status": "identified"
  }'

curl --request PATCH \
  --url "https://api.scaling.cloud/v1/incidents/YOUR_INCIDENT_ID/status" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "status": "resolved",
    "resolutionNote": "Root cause was a misconfigured rate limit on the payment gateway introduced in deploy v3.14.2. Rolled back and applied fix in v3.14.3. Monitoring confirms error rate has returned to baseline."
  }'

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

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

{
  "statusCode": 401,
  "type": "not_authorized_error",
  "code": "not_authorized",
  "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"
}

PATCH

incidents

{id}

status

curl --request PATCH \
  --url "https://api.scaling.cloud/v1/incidents/YOUR_INCIDENT_ID/status" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "status": "identified"
  }'

curl --request PATCH \
  --url "https://api.scaling.cloud/v1/incidents/YOUR_INCIDENT_ID/status" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "status": "resolved",
    "resolutionNote": "Root cause was a misconfigured rate limit on the payment gateway introduced in deploy v3.14.2. Rolled back and applied fix in v3.14.3. Monitoring confirms error rate has returned to baseline."
  }'

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

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

{
  "statusCode": 401,
  "type": "not_authorized_error",
  "code": "not_authorized",
  "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"
}

Advances an incident through its fixed lifecycle. Each call moves the incident exactly one step forward. You cannot skip steps, go backwards, or re-open a resolved incident.

This endpoint coexists with Post Incident Update. They are not redundant:

Use PATCH /status for a simple, status-only transition with an optional staff-only resolutionNote. The note never reaches your public status page.
Use POST /updates when you want the same write to publish a customer-visible message on your status page (visibility: 'public', statusChange: <next>, body: <what customers should read>), or when you want to post a free-text note without changing status.

Internally, PATCH /status is now a thin alias that posts an internal update via the same engine path.

Status lifecycle

investigating → identified → monitoring → resolved

Current status	Valid next status
`investigating`	`identified`
`identified`	`monitoring`
`monitoring`	`resolved`
`resolved`	— (terminal state)

Status transitions are one-way and must follow the exact sequence above. Attempting to transition to any status other than the immediate next step — including skipping ahead, going backwards, or updating a resolved incident — will return a 400 error with code invalid_status_transition.

Path parameters

string

required

The UUID of the incident to update.

Request body

status

string

required

The status to transition to. Must be the next valid status in the lifecycle sequence. One of investigating, identified, monitoring, or resolved.

resolutionNote

string

Optional note to record alongside this transition. Must be between 1 and 2000 characters. Leading and trailing whitespace is trimmed automatically. Commonly used when transitioning to resolved to summarize the root cause and fix.

Response

Returns the updated incident object.

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

The new current status after the transition.

affectedComponents

array of object

required

Components affected by this incident. Each entry has id and name. Empty array if none.

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_status_transition`	The requested status does not follow the required sequence.
`400`	`incident_resolved`	The incident is already `resolved`; no further status changes are accepted.
`401`	`not_authorized`	Missing or invalid API key.
`404`	`not_found`	No incident with the given ID exists in your organization.
`422`	—	Request body failed validation (e.g. `resolutionNote` exceeds 2000 characters).
`500`	`server_error`	An unexpected error occurred on our side.

curl --request PATCH \
  --url "https://api.scaling.cloud/v1/incidents/YOUR_INCIDENT_ID/status" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "status": "identified"
  }'

curl --request PATCH \
  --url "https://api.scaling.cloud/v1/incidents/YOUR_INCIDENT_ID/status" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "status": "resolved",
    "resolutionNote": "Root cause was a misconfigured rate limit on the payment gateway introduced in deploy v3.14.2. Rolled back and applied fix in v3.14.3. Monitoring confirms error rate has returned to baseline."
  }'

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

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

{
  "statusCode": 401,
  "type": "not_authorized_error",
  "code": "not_authorized",
  "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"
}

Get Incident Change Severity

Overview

Incidents

On-call Schedules

Escalation Policies

Routing Policies

Working Hours

Team

Status lifecycle

Path parameters

Request body

Response

Error responses

​Status lifecycle

​Path parameters

​Request body

​Response

​Error responses

Status lifecycle

Path parameters

Request body

Response

Error responses