---
title: "Write to an incident's timeline"
method: POST
path: "/incidents/{incident_id}/comments"
tags: ["Incidents"]
---

# Write to an incident's timeline

`POST /incidents/{incident_id}/comments`

## Request

- Base URL: `https://app.getorchestra.io/api/engine/public`
- URL: `https://app.getorchestra.io/api/engine/public/incidents/{incident_id}/comments`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://app.getorchestra.io/oauth/authorize`
    - Token URL: `https://app.getorchestra.io/oauth/token` scopes: `orchestra:write`

Append a row to an incident's timeline, returning the event it wrote.

`eventType` says what the row records - `COMMENT_ADDED` (the default) for an ordinary comment, or `AI_DIAGNOSIS_REQUESTED`, `AI_DIAGNOSIS_COMPLETED` and `AI_DIAGNOSIS_FAILED` to record the start, result or failure of a diagnosis.

`agentSessionId` names the Orchestra agent session behind the write. The row is then attributed to Orchestra AI and linked to that session rather than to the API key; an agent takes the id from its `ORCHESTRA_AGENT_SESSION_ID` environment variable. The `AI_DIAGNOSIS_*` types require it. A session may write several over its life, but posting the same text twice returns the row already written.

`description` sets the incident's description alongside an `AI_DIAGNOSIS_COMPLETED` or `AI_DIAGNOSIS_FAILED` row, and needs edit permission on the incident. It is not applied over a description a person wrote.

The timeline is append-only: nothing can edit or delete a row once it is there.

## Path parameters

- `incident_id` string, uuid4, required

## Headers

- `X-Orchestra-Account-Id` string, uuid4, nullable

## Request body

- CreateIncidentCommentRequest: A comment to append to an incident's timeline. Stripped before the length check: a timeline row cannot be edited or deleted once written, so whitespace alone must not put a blank one there.
  - `comment` string, required

## Response `201`

Successful Response

- IncidentEventResponse: One row on an incident's timeline.
  - `incidentEventId` string, uuid4, required
  - `incidentId` string, uuid4, required
  - `eventType` 'AI_DIAGNOSIS_COMPLETED' | 'AI_DIAGNOSIS_FAILED' | 'AI_DIAGNOSIS_REQUESTED' | 'ARCHIVED' | 'ASSIGNED' | 'CHILD_MERGED' | 'COMMENT_ADDED' | 'CREATED' | 'DESCRIPTION_CHANGED' | 'EVENT' | 'MERGED_INTO' | 'MUTED' | 'RENAMED' | 'SEVERITY_CHANGED' | 'STATUS_CHANGED' | 'SUBSCRIBERS_CHANGED' | 'UNASSIGNED' | 'UNMERGED' | 'UNMUTED', required
  - `actorType` 'AI' | 'API' | 'OTHER' | 'SYSTEM' | 'USER', required
  - `actorId` string, nullable
  - `comment` string, nullable
  - `insertedAt` string, required
  - `environmentId` string, uuid4, nullable
  - `resourceType` 'ASSET' | 'EXTERNAL' | 'OPERATION' | 'PIPELINE' | 'SENSOR' | 'TASK'
  - `triggerType` 'ANOMALY' | 'EXTERNAL' | 'FAILED' | 'WARNING': The kind of signal that produced an incident event. Producers state what happened; the Incident Manager maps it to a severity and applies the grouping invariants.
  - `pipelineId` string, uuid4, nullable
  - `pipelineRunId` string, uuid4, nullable
  - `taskRunId` string, uuid4, nullable
  - `sensorId` string, nullable
  - `assetId` string, uuid4, nullable
  - `connectionId` string, nullable
  - `commitSha` string, nullable
  - `groupBy` string, nullable
  - `hasExternalEvent` boolean

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-03** `e45165e7e223`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/getorchestra/apis/orchestra-api/changes/incidents/:incident_id/comments/post.md)

---

[API](https://skmtc.dev/getorchestra/apis/orchestra-api.md) - [All operations](https://skmtc.dev/getorchestra/apis/orchestra-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getorchestra/apis/orchestra-api/revisions/daf2c16b3057?raw)