---
title: "Declare an incident"
method: POST
path: "/incidents"
tags: ["Incidents"]
---

# Declare an incident

`POST /incidents`

## Request

- Base URL: `https://api.spectate.net/v1`
- URL: `https://api.spectate.net/v1/incidents`
- Auth: HTTP bearer

It starts `investigating`. With Slack connected it's announced there like an incident
declared in the dashboard, with its own channel when the Slack settings say so.

## Request body

- CreateIncident: A new incident.
  - `title` string, required: What's going on, up to 255 characters
  - `severity` 'critical' | 'high' | 'medium' | 'low', required: How urgent an alert or incident is. Escalation paths can branch on it. | | |---| | `critical` <br/> Customers are affected right now. | | `high` <br/> Serious, needs attention soon. | | `medium` <br/> Should be looked at. | | `low` <br/> Informational. |
  - `summary` string, nullable: More about it, in Markdown

## Response `201`

The new incident.

- Incident: An incident: a problem that affects customers, worked on by the team, with updates, roles and eventually a postmortem. Incidents are declared by hand, through the API, from Slack, or by an escalation path's `create_incident` step.
  - `id` string, uuid, required: Incident ID
  - `number` integer, nullable, required: The team's sequence number: `INC-42` is 42. `null` for some older incidents
  - `reference` string, required: The human reference
  - `title` string, required: What's going on
  - `summary` string, nullable, required: More about it, in Markdown
  - `severity` 'critical' | 'high' | 'medium' | 'low', required: How urgent an alert or incident is. Escalation paths can branch on it. | | |---| | `critical` <br/> Customers are affected right now. | | `high` <br/> Serious, needs attention soon. | | `medium` <br/> Should be looked at. | | `low` <br/> Informational. |
  - `status` 'investigating' | 'identified' | 'monitoring' | 'resolved', required: Where an incident stands. | | |---| | `investigating` <br/> Declared; the cause isn't known yet. | | `identified` <br/> Acknowledged: the cause is known and someone works on it. | | `monitoring` <br/> A fix is out; watching whether it holds. | | `resolved` <br/> Over. |
  - `started_at` string, date-time, required: When it started
  - `acknowledged_at` string, date-time, nullable, required: When someone acknowledged it
  - `resolved_at` string, date-time, nullable, required: When it was resolved
  - `alert_id` string, uuid, nullable, required: The alert that opened it, for incidents declared by an escalation path
  - `roles` IncidentRoleAssignment[], required: Who has which role
    - `role` 'commander' | 'communications_lead', required: A role in handling an incident; one member each. | | |---| | `commander` <br/> Leads the response and makes the calls. | | `communications_lead` <br/> Keeps customers and the company informed, for example through the status page. |
    - `member` MemberReference, required: A member of the team.
      - `id` string, uuid, required: Member (user) ID
      - `name` string, required: Name
      - `email` string, email, required: Email address
  - `created_at` string, date-time, required: When it was declared

## Other responses

- `401`: `UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.
- `403`: `FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.
- `422`: `VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.
- `429`: `RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.

---

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