> For the complete documentation index, see [llms.txt](https://docs.visualsentinel.com/llms.txt)

# Incidents API

Incident tracking and management. This page lists all 12 endpoints in the Incidents area of the Visual Sentinel REST API.

Base URL: `https://visualsentinel.com`. Unless an endpoint says otherwise it accepts an API key or a session cookie, see [Authentication](https://docs.visualsentinel.com/guides/authentication.md). Most error responses use the [ErrorResponse](https://docs.visualsentinel.com/reference/models/error-response.md) shape, see [Errors](https://docs.visualsentinel.com/guides/errors.md) and [Rate limits](https://docs.visualsentinel.com/guides/rate-limits.md).

## Endpoints

- [List incidents](#list-incidents): `GET /api/incidents`
- [Create incident](#create-incident): `POST /api/incidents`
- [Get incident](#get-incident): `GET /api/incidents/{id}`
- [Update incident](#update-incident): `PUT /api/incidents/{id}`
- [Update incident (partial)](#patch-incident): `PATCH /api/incidents/{id}`
- [Delete incident](#delete-incident): `DELETE /api/incidents/{id}`
- [Get incident summary](#get-incident-summary): `GET /api/incidents/{id}/summarize`
- [Generate incident summary](#summarize-incident): `POST /api/incidents/{id}/summarize`
- [Post incident update](#create-incident-update): `POST /api/incidents/{id}/updates`
- [Get incident detail context](#get-incident-context): `GET /api/incidents/{id}/context`
- [Ways to resolve an incident](#get-incident-resolve-options): `GET /api/incidents/{id}/resolve`
- [Resolve an incident, optionally changing its limit or turning its check off](#resolve-incident): `POST /api/incidents/{id}/resolve`

## List incidents

`GET /api/incidents`

List incidents, open ones first, newest first within each group.

**Parameters**

- `status` (query, string, optional): `active` returns open incidents (investigating, identified, monitoring); `resolved` returns resolved and postmortem ones; an exact status matches one status. Case-insensitive. One of: `active`, `resolved`, `all`, `INVESTIGATING`, `IDENTIFIED`, `MONITORING`, `RESOLVED`, `POSTMORTEM`. Default: `all`.
- `severity` (query, string, optional): One of: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO`.
- `monitorId` (query, string (uuid), optional)
- `q` (query, string, optional): Search title, description and cause. Max length 200.
- `startDate` (query, string, optional): ISO date or date-time.
- `endDate` (query, string, optional): ISO date or date-time.
- `page` (query, integer, optional): Default: `1`. Minimum 1.
- `limit` (query, integer, optional): Values above 100 are served 100 rows. Default: `50`. Minimum 1, maximum 100.

**Responses**

- `200`: Incidents. Body: object.
- `400`: Invalid query parameters, for example an unknown status.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `incidents` | array of [Incident](https://docs.visualsentinel.com/reference/models/incident.md) | No |   |
| `pagination` | object | No |   |
| `pagination.page` | integer | No |   |
| `pagination.total` | integer | No |   |
| `pagination.limit` | integer | No |   |

## Create incident

`POST /api/incidents`

Manually create a new incident.

Request body (required): object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `monitorId` | string (uuid) | Yes |   |
| `title` | string | Yes | Max length 200. |
| `description` | string | No | Max length 2000. |
| `severity` | string | No | One of: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`. |

**Responses**

- `200`: Incident created.

## Get incident

`GET /api/incidents/{id}`

Get details of a specific incident.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Incident details. Body: [Incident](https://docs.visualsentinel.com/reference/models/incident.md).
- `404`: Incident not found.

## Update incident

`PUT /api/incidents/{id}`

Change an incident: status, severity, title, description, resolution notes, acknowledgement or auto-resolve. Every field is optional. `{ "acknowledged": true }` acknowledges; `{ "status": "RESOLVED" }` resolves. A status change is sent at once to the incident's alert channels and status page subscribers, unless `notify` is false.

**Parameters**

- `id` (path, string (uuid), required)

Request body (required): [UpdateIncidentRequest](https://docs.visualsentinel.com/reference/models/update-incident-request.md).

**Responses**

- `200`: Incident updated. Body: object.
- `400`: Invalid request data.
- `403`: Read-only role, or an API key without `incidents:write`.
- `404`: Incident not found.
- `409`: The actionId was already used on another incident.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | No |   |
| `incident` | object | No |   |
| `incident.id` | string (uuid) | No |   |
| `incident.status` | string | No |   |
| `incident.severity` | string | No |   |
| `incident.title` | string | No |   |
| `incident.acknowledgedAt` | string (date-time) or null (date-time) | No |   |
| `incident.acknowledgedById` | string or null | No |   |
| `warning` | string | No |   |
| `replayed` | boolean | No | true when this repeated a status change already made with the same actionId. Nothing was changed or sent again. |

## Update incident (partial)

`PATCH /api/incidents/{id}`

Same as PUT: every field is optional. The dashboard acknowledges with `PATCH { "acknowledged": true }`.

**Parameters**

- `id` (path, string (uuid), required)

Request body (required): [UpdateIncidentRequest](https://docs.visualsentinel.com/reference/models/update-incident-request.md).

**Responses**

- `200`: Incident updated. Body: object.
- `400`: Invalid request data.
- `403`: Read-only role, or an API key without `incidents:write`.
- `404`: Incident not found.
- `409`: The actionId was already used on another incident.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | No |   |
| `incident` | object | No |   |
| `incident.id` | string (uuid) | No |   |
| `incident.status` | string | No |   |
| `incident.severity` | string | No |   |
| `incident.title` | string | No |   |
| `incident.acknowledgedAt` | string (date-time) or null (date-time) | No |   |
| `incident.acknowledgedById` | string or null | No |   |
| `warning` | string | No |   |
| `replayed` | boolean | No | true when this repeated a status change already made with the same actionId. Nothing was changed or sent again. |

## Delete incident

`DELETE /api/incidents/{id}`

Delete an incident.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Incident deleted.

## Get incident summary

`GET /api/incidents/{id}/summarize`

Get the cached AI summary for an incident.

Authentication: session cookie only. API keys are refused.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Cached summary.

## Generate incident summary

`POST /api/incidents/{id}/summarize`

Generate an AI-powered summary and postmortem for an incident.

Authentication: session cookie only. API keys are refused.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: AI-generated summary.

## Post incident update

`POST /api/incidents/{id}/updates`

Post a status update on an incident. It shows on the incident page and on every status page that shows this incident, and the incident status changes to match. It is sent at once to the incident's alert channels and status page subscribers, unless `notify` is false. Needs the owner or admin role.

**Parameters**

- `id` (path, string (uuid), required)

Request body (required): object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | Yes | Case-insensitive. One of: `INVESTIGATING`, `IDENTIFIED`, `MONITORING`, `RESOLVED`, `POSTMORTEM`. |
| `message` | string | Yes | Min length 1, max length 2000. |
| `notify` | boolean | No | true (the default) sends the update at once to the incident's alert channels and to the subscribers of its status pages. false posts it without notifying anyone; it still shows on the incident timeline and on the status page. PagerDuty, Opsgenie and Prometheus only receive an update that closes or reopens an alert a check opened. Default: `true`. |
| `actionId` | string (uuid) | No | A UUID you choose for this update. Posting again with the same actionId returns the update already posted (200) and sends nothing. An actionId already used on another incident returns 409. |

**Responses**

- `200`: This actionId was already posted. Returns that update; nothing is posted or sent again. Body: object.
- `201`: Update posted. Body: object.
- `400`: Missing or invalid status or message.
- `403`: Not an owner or admin, or an API key without `incidents:write`.
- `404`: Incident not found.
- `409`: The actionId was already used on another incident.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | No |   |
| `status` | string | No |   |
| `message` | string | No |   |
| `notified` | boolean | No | false when the update was posted without notifying anyone. |
| `authorId` | string or null | No |   |
| `author` | object or null | No |   |
| `author.id` | string | No |   |
| `author.name` | string or null | No |   |
| `author.email` | string | No |   |
| `createdAt` | string (date-time) | No |   |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | No |   |
| `status` | string | No |   |
| `message` | string | No |   |
| `notified` | boolean | No | false when the update was posted without notifying anyone. |
| `authorId` | string or null | No |   |
| `author` | object or null | No |   |
| `author.id` | string | No |   |
| `author.name` | string or null | No |   |
| `author.email` | string | No |   |
| `createdAt` | string (date-time) | No |   |

## Get incident detail context

`GET /api/incidents/{id}/context`

Returns everything the incident detail view shows in one read: plain-language headline and summary, the checks around the incident, per-region results, the monitor's settings, suggested fixes, alerts sent, status page preview, updates and related incidents. API keys need the `incidents:read` scope. The response is not cached.

**Parameters**

- `id` (path, string (uuid), required): Incident ID.
- `tz` (query, string, optional): IANA time zone (for example `Europe/Berlin`) that decides where "today" starts for `uptimeToday`. Missing or unknown zones use UTC.

**Responses**

- `200`: Incident context. Body: [IncidentContext](https://docs.visualsentinel.com/reference/models/incident-context.md).
- `401`: Not signed in, or no valid API key.
- `403`: No membership in the organization, or the incident belongs to another organization you are a member of (`error` is `wrong_org`, with that organization's ID and name so the client can switch) Body: object.
- `404`: Incident not found.
- `503`: Database unavailable.

## Ways to resolve an incident

`GET /api/incidents/{id}/resolve`

The actions this incident accepts, with the suggested limit and what each stop would turn off. Needs `incidents:read`.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Resolve options. Body: [IncidentResolveOptions](https://docs.visualsentinel.com/reference/models/incident-resolve-options.md).
- `404`: Incident not found.

## Resolve an incident, optionally changing its limit or turning its check off

`POST /api/incidents/{id}/resolve`

Closes the incident, after saving the chosen change to the site's own settings (the same save as PUT /api/monitors/{id}, so it can be undone there; the response lists the undo requests). An API key needs `incidents:write`, plus `monitors:write` for every action except `resolve`. Outages and possible malware never accept stop_alerting. The resolve is told to the incident's alert channels and status page subscribers as "This incident has been resolved." unless `notify` is false; the settings change is not shown to them.

**Parameters**

- `id` (path, string (uuid), required)

Request body (required): [IncidentResolveRequest](https://docs.visualsentinel.com/reference/models/incident-resolve-request.md).

**Responses**

- `200`: Resolved (and the setting saved) Body: object.
- `400`: Unknown action, or a limit missing or out of range.
- `403`: Read-only role, or an API key without `incidents:write` (or `monitors:write` for a settings change)
- `404`: Incident not found.
- `409`: This incident does not offer that action (for example stop_alerting on an outage or possible malware), or it is already resolved.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `incident` | object | No |   |
| `incident.id` | string (uuid) | No |   |
| `incident.status` | string | No |   |
| `action` | string | No |   |
| `kind` | string | No |   |
| `settingChanged` | boolean | No |   |
| `summary` | string or null | No | What changed, in plain words. |
| `undo` | array of object | No | The requests that put the setting back. |
| `undo[].method` | string | No | One of: `PUT`. |
| `undo[].path` | string | No |   |
| `undo[].body` | object | No |   |
| `warning` | string | No |   |

## Data models

Request and response shapes these endpoints use: [Incident](https://docs.visualsentinel.com/reference/models/incident.md), [UpdateIncidentRequest](https://docs.visualsentinel.com/reference/models/update-incident-request.md), [IncidentContext](https://docs.visualsentinel.com/reference/models/incident-context.md), [IncidentResolveOptions](https://docs.visualsentinel.com/reference/models/incident-resolve-options.md), [IncidentResolveRequest](https://docs.visualsentinel.com/reference/models/incident-resolve-request.md).

Generated from the OpenAPI 3.1 specification at [https://docs.visualsentinel.com/openapi.json](https://docs.visualsentinel.com/openapi.json), the same file the interactive reference reads.