Post Incident Update
Posts a public update to the timeline of a manual or monitor incident and notifies status page subscribers.
POST /api/incidents/:id/updates
Posts a timeline update to an incident: the text appears on every status page the incident is shown on and goes to the subscribers of those pages. This is what "Post update" in the status pages module and the MCP tool post_incident_update do.
What the update's status changes depends on the incident (since 28 October 2026):
- Manual incident: the incident follows the update.
resolvedresolves it (statusandresolvedAt) and sends the all-clear; any other status on a resolved incident reopens it and notifies subscribers again. - Monitor incident: only the public status changes (
publicStatus,publicResolvedAt).resolvedresolves it on the status pages and sends the all-clear there; any other status reopens it there. The monitoring incident stays as it is: itsstatusandresolvedAtfollow the monitor checks, not the update. While the incident is still open on the pages, a recovering monitor sends no all-clear.
The all-clear and the reopen notice are sent only on a real change of the public status. A second resolved update on an incident that is already resolved on the pages is posted, but sends no second all-clear.
Repeats: a call with the same status and body as an update the incident already has creates nothing new. It answers 200 OK with the existing update and deduplicated: true, and sends nothing again. Repeat a call whose response did not arrive without risk.
To change the internal status, title or links instead, use Update Incident. Get Incident Details returns publicStatus and publicResolvedAt.
Authentication
Requires role admin or editor within the incident's customer scope. An incident without a customer needs an organization-wide role or token; for any other organization it answers 404 incidentNotFound. readonly gets 403 forbidden.
- Header:
Authorization: Bearer <token>
Path Parameters
id(required): numeric id orpublicId(UUID).
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
status | string | yes | investigating, identified, monitoring or resolved. |
body | string | yes | The update text, 1 to 5,000 characters after trimming. |
notifySubscribers | boolean | no | Default true. false records the update in the feed and history of the pages without email or webhook notifications; this also applies to the all-clear or reopen notice it triggers. |
Example (cURL)
curl -X POST "$BASE_URL/api/incidents/5121/updates" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "status": "identified", "body": "The cause is a faulty database node. We are switching to the replica." }'Response
201 Created for a new update, 200 OK for a repeat.
{
"update": {
"id": 8812,
"publicId": "3f6c2a8e-6b1d-4c39-9a57-2d0e5b7c1f44",
"status": "identified",
"body": "The cause is a faulty database node. We are switching to the replica.",
"createdAt": "2026-10-28T09:41:12.000Z"
},
"deduplicated": false
}| Field | Description |
|---|---|
update | The posted update, or for a repeat the existing one. |
deduplicated | true when the same status and body was already posted; nothing was created or sent. |
Common Errors
400 Bad Request(invalidRequestBody) whenstatusis missing or not one of the four values, orbodyis empty or longer than 5,000 characters400 Bad Request(incidentNoCustomer) when the incident has neither a customer nor a status page401 Unauthorizedwhen not authenticated403 Forbidden(forbidden) when your role or customer scope does not allow the update404 Not Found(incidentNotFound) when the incident does not exist in your organization