Skip to main content
POST
/
v1
/
incidents
/
{id}
/
updates
curl --request POST \
  --url "https://api.scaling.cloud/v1/incidents/YOUR_INCIDENT_ID/updates" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "body": "We have identified the cause as a misconfigured rate limit on the payment gateway. Working on a rollback now.",
    "statusChange": "identified",
    "visibility": "public"
  }'

{
  "data": {
    "id": "0193e1a2-3b4c-7890-abcd-ef1234567890",
    "incidentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "body": "We have identified the cause as a misconfigured rate limit on the payment gateway. Working on a rollback now.",
    "statusChange": "identified",
    "visibility": "public",
    "postedBy": { "id": "user_2b9a3d4e5f6g7h8j", "name": "Alice Chen" },
    "postedAt": "2025-04-07T09:14:00.000Z",
    "redactedAt": null,
    "redactedBy": null
  }
}

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.

Posts a new update on an incident. The update may carry a message body, a status transition, or both — at least one is required. Updates are append-only; to correct a previous statement, redact the original and post a new one.

​
Visibility

visibility is required on every request — there is no default.
VisibilityRenders on the public status page?Body required?
internalOnly as a bare transition row when statusChange is set; the body is never exposed publicly.No
publicYes — the body is the message bubble customers read.Yes
Posting public is rejected with no_public_surface (400) when the incident has no published Status Page whose selected components overlap with the incident’s affected components. Subscribe a Status Page to the affected components before publishing. Resolved incidents are terminal — POST against a resolved incident returns 400 incident_resolved. You may still redact updates on a resolved incident.

​
Path parameters

​
id
string
required
The UUID of the incident.

​
Request body

​
visibility
string
required
internal or public. No default — must be set explicitly.
​
body
string
Free-text message up to 10,000 characters. Required when visibility is public. Optional when visibility is internal — but at least one of body or statusChange must be set.
​
statusChange
string
Optional lifecycle transition. One of investigating, identified, monitoring, resolved. Must follow the existing sequence — see Update Status for the rules. When set, the incident’s status advances in the same write.

​
Response

Returns the created incident update.
​
data
object
required

​
Error responses

StatusCodeDescription
400body_required_for_publicvisibility=public was set but no body was provided.
400no_public_surfaceThe incident has no published Status Page that covers its affected components. Cannot publish.
400incident_resolvedThe incident is already resolved; no further updates are accepted (you may still redact).
400invalid_status_transitionstatusChange does not follow the lifecycle sequence.
400update_must_carry_body_or_status_changeNeither body nor statusChange was provided.
401not_authorizedMissing or invalid credentials.
404not_foundNo incident with the given ID exists in your organization.
422—Request body failed validation (e.g. unknown visibility, body over 10,000 chars).
500server_errorAn unexpected error occurred on our side.
curl --request POST \
  --url "https://api.scaling.cloud/v1/incidents/YOUR_INCIDENT_ID/updates" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "body": "We have identified the cause as a misconfigured rate limit on the payment gateway. Working on a rollback now.",
    "statusChange": "identified",
    "visibility": "public"
  }'

{
  "data": {
    "id": "0193e1a2-3b4c-7890-abcd-ef1234567890",
    "incidentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "body": "We have identified the cause as a misconfigured rate limit on the payment gateway. Working on a rollback now.",
    "statusChange": "identified",
    "visibility": "public",
    "postedBy": { "id": "user_2b9a3d4e5f6g7h8j", "name": "Alice Chen" },
    "postedAt": "2025-04-07T09:14:00.000Z",
    "redactedAt": null,
    "redactedBy": null
  }
}

​
End-to-end example

A typical “investigate → publish update → resolve” flow: 
# 1. Create the incident
curl -X POST "https://api.scaling.cloud/v1/incidents" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Payments elevated error rate","severity":"critical","ownerScheduleId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","componentIds":["6ba7b810-9dad-11d1-80b4-00c04fd430c8"]}'
# → { "data": { "id": "INC_ID", ... } }

# 2. Publish "we are investigating" to the status page
curl -X POST "https://api.scaling.cloud/v1/incidents/INC_ID/updates" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"body":"We are investigating elevated error rates on the Payments API.","visibility":"public"}'

# 3. Publish the resolution and transition to resolved in one call
curl -X POST "https://api.scaling.cloud/v1/incidents/INC_ID/updates" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"body":"Rolled back deploy v3.14.2. Error rates back to baseline.","statusChange":"resolved","visibility":"public"}'
This endpoint does not yet support client-supplied idempotency keys at the API layer. Retrying a transient 5xx may create a duplicate update — guard your callers with their own dedupe key (e.g. cache the id from the first 200 response) until end-to-end idempotency is exposed.