Post Incident Update

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"
  }'

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": "Paging the payments lead — context in incident channel.",
    "visibility": "internal"
  }'

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 '{
    "statusChange": "monitoring",
    "visibility": "internal"
  }'

{
  "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
  }
}

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

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

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

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

POST

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"
  }'

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": "Paging the payments lead — context in incident channel.",
    "visibility": "internal"
  }'

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 '{
    "statusChange": "monitoring",
    "visibility": "internal"
  }'

{
  "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
  }
}

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

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

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

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

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.

Visibility	Renders on the public status page?	Body required?
`internal`	Only as a bare transition row when `statusChange` is set; the body is never exposed publicly.	No
`public`	Yes — 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

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

Hide properties

string

required

Server-generated ID of the update (UUID).

incidentId

string

required

Incident this update belongs to.

body

string or null

required

Update message. null when the update is a status-only internal update or has been redacted.

statusChange

string or null

required

Lifecycle status the incident transitioned to, or null if the update is body-only.

visibility

string

required

internal or public.

postedBy

object

required

The user who posted the update. { id, name }.

postedAt

string

required

ISO 8601 timestamp.

redactedAt

string or null

required

ISO 8601 timestamp when the update was redacted, or null.

redactedBy

object or null

required

The user who redacted the update ({ id, name }), or null.

Error responses

Status	Code	Description
`400`	`body_required_for_public`	`visibility=public` was set but no `body` was provided.
`400`	`no_public_surface`	The incident has no published Status Page that covers its affected components. Cannot publish.
`400`	`incident_resolved`	The incident is already `resolved`; no further updates are accepted (you may still redact).
`400`	`invalid_status_transition`	`statusChange` does not follow the lifecycle sequence.
`400`	`update_must_carry_body_or_status_change`	Neither `body` nor `statusChange` was provided.
`401`	`not_authorized`	Missing or invalid credentials.
`404`	`not_found`	No incident with the given ID exists in your organization.
`422`	—	Request body failed validation (e.g. unknown `visibility`, body over 10,000 chars).
`500`	`server_error`	An 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"
  }'

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": "Paging the payments lead — context in incident channel.",
    "visibility": "internal"
  }'

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 '{
    "statusChange": "monitoring",
    "visibility": "internal"
  }'

{
  "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
  }
}

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

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

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

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

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","leadScheduleId":"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.

Change Severity List Incident Updates

Overview

Incidents

On-call Schedules

Escalation Policies

Routing Policies

Working Hours

Team

Visibility

Path parameters

Request body

Response

Error responses

End-to-end example

​Visibility

​Path parameters

​Request body

​Response

​Error responses

​End-to-end example

Visibility

Path parameters

Request body

Response

Error responses

End-to-end example