# Declare an incident

`POST https://evohub.io/api/v1/incidents`

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

Declares an incident. It starts `investigating`, with the caller as commander
unless `commander_id` names someone else, who must be a member who can respond
to alerts.

To record an incident that already ended, send both `started_at` and
`resolved_at`: it is stored resolved, with those times.

**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_…`).

## Request body (required)

Content type: `application/json`

Type: `IncidentCreate`

- `title` (string, required, max length 200): Not blank.
- `severity` (IncidentSeverity, required, one of `none`, `minor`, `major`, `critical`)
- `summary` (string)
- `commander_id` (string): Defaults to the caller.
- `started_at` (string (date-time)): With `resolved_at`: record an incident that already ended.
- `resolved_at` (string (date-time)): With `started_at`: record an incident that already ended. Must be after `started_at` and not in the future.

## Responses

### 201 — The incident.

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` or `severity` is missing, `title` is blank or longer than 200 characters, `severity` is not one of the four values, or the past times are not a start before an end that has already happened (`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 — `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.

### 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 POST 'https://evohub.io/api/v1/incidents' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
  "title": "Checkout payments failing",
  "summary": "Card payments time out for about 30% of customers.",
  "severity": "major"
}'
```