---
title: "Post Incident Update"
description: "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. `resolved` resolves it (`status` and `resolvedAt`) 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`). `resolved` resolves it on the status pages and sends the all-clear there; any other status reopens it there. The monitoring incident stays as it is: its `status` and `resolvedAt` follow 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](/api/monitoring/update-incident). [Get Incident Details](/api/monitoring/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 or `publicId` (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)

```bash
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.

```json
{
  "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`) when `status` is missing or not one of the four values, or `body` is empty or longer than 5,000 characters
- `400 Bad Request` (`incidentNoCustomer`) when the incident has neither a customer nor a status page
- `401 Unauthorized` when not authenticated
- `403 Forbidden` (`forbidden`) when your role or customer scope does not allow the update
- `404 Not Found` (`incidentNotFound`) when the incident does not exist in your organization