# Update an incident

`PUT https://evohub.io/api/v1/incidents/{id}`

Part of the [On-Call API](https://docs.evohub.io/oncall.md) reference · operationId `updateIncident`.

Changes the title, summary, severity or commander. A field left out or empty
keeps its value, so a field cannot be cleared this way. `severity` must be
one of the four values, and a `commander_id` other than the caller must be a
member of the organization who can respond to alerts, as on create. When the
incident is published to a status page, a new title — and a changed
severity, as the public impact — is relayed there.

Send the incident's `version` to make the edit conditional: if someone
changed the incident since you read it, nothing is written (409
`EDIT_CONFLICT`).

**Permission (API-key scope):** `oncall:incident:write`.

## Authorization

Any one of:

- `bearerAuth` (oncall:incident:write)
- `apiKeyHeader` (oncall:incident:write)

Where:

- `bearerAuth`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `apiKeyHeader`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Path parameters

- `id` (string, required, example `2e7f9a1b-3c4d-4e5f-8a9b-0c1d2e3f4a5b`): The incident's id.

## Request body (required)

Content type: `application/json`

Type: `IncidentUpdate`

Empty or omitted fields keep their value.

- `title` (string, max length 200): Not blank; empty keeps the stored title.
- `summary` (string)
- `severity` (IncidentSeverity, one of `none`, `minor`, `major`, `critical`)
- `commander_id` (string)
- `version` (integer): The incident's `version` this edit was made against. When it is no longer the current one, nothing is changed (409 `EDIT_CONFLICT`). Omitted, the edit applies to whatever is stored.

## Responses

### 200 — The incident after the change.

Content type: `application/json`

Type: `object`

- `data` (Incident, required)
  - `id` (string, required)
  - `org_id` (string)
  - `number` (integer, required): Sequential number within the organization.
  - `title` (string, required)
  - `summary` (string)
  - `severity` (IncidentSeverity, required, one of `none`, `minor`, `major`, `critical`)
  - `status` (IncidentStatus, required, one of `investigating`, `identified`, `monitoring`, `resolved`)
  - `commander_id` (string)
  - `started_at` (string (date-time), required)
  - `identified_at` (string (date-time))
  - `resolved_at` (string (date-time))
  - `timeline` (array of IncidentTimelineEntry): The timeline entries, oldest first. Only in the answer of Get an incident.
    - `id` (string)
    - `incident_id` (string)
    - `author_id` (string)
    - `status` (string): The incident's status when the entry was written.
    - `message` (string)
    - `created_at` (string (date-time))
  - `created_at` (string (date-time))
  - `updated_at` (string (date-time))
  - `version` (integer): Goes up by one on every edit of the title, summary, severity or commander (not on acknowledge or resolve). Send it with an update to refuse the edit if someone else changed the incident first.
- `success` (boolean, required, value `true`)

### 400 — The body is not JSON (`INVALID_BODY`), `title` is blank or longer than 200 characters, or `severity` is not one of the four values (`VALIDATION_FAILED`).

Content type: `application/json`

Type: `ValidationError`

- `error` (object, required)
  - `code` (string, required, value `VALIDATION_FAILED`)
  - `message` (string, required)
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.
  - `details` (array of object, required)
    - `field` (string)
    - `message` (string)

### 401 — No API key was sent, or it is unknown, revoked or expired (`UNAUTHORIZED`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 403 — The key lacks the scope this endpoint needs (`FORBIDDEN`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 404 — No incident with this id in your organization (`NOT_FOUND`), or `commander_id` is not a member of the organization (`NOT_A_MEMBER`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 409 — `version` is not the incident's current version; it was changed since you read it (`EDIT_CONFLICT`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 422 — The person cannot respond to alerts: they do not hold `oncall:alert:respond` (`CANNOT_RESPOND`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 429 — Too many requests (`RATE_LIMITED`). Wait `Retry-After` seconds.

Headers:

- `Retry-After` (integer): Seconds to wait.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 500 — Something went wrong on EvoHub's side (`INTERNAL_ERROR`). Retry later.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 503 — Whether the person may be paged could not be checked right now; nothing was changed (`MEMBER_CHECK_UNAVAILABLE`). Retry shortly.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

## Example request

```bash
curl -X PUT 'https://evohub.io/api/v1/incidents/2e7f9a1b-3c4d-4e5f-8a9b-0c1d2e3f4a5b' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
  "severity": "critical"
}'
```