# Post an incident

Tell your status page's visitors and subscribers what is wrong, post updates as you learn more, and resolve it.

An incident has a title, an impact, a status, the components it affects and a timeline of
plain-text updates. Replace _page-id_ with the status page's id and _incident-id_ with the
incident's, and the component id in the examples (`7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f`) with
one of the page's component ids, as `dcloud monitoring status-pages get` lists them.

| Impact     | While the incident is open, its components are at least |
| ---------- | ------------------------------------------------------- |
| `none`     | Operational                                             |
| `minor`    | Degraded performance                                    |
| `major`    | Partial outage                                          |
| `critical` | Major outage                                            |

An open incident without components still counts toward the page's banner. The status is
`investigating`, `identified`, `monitoring` or `resolved`. A resolved incident stays on the public
page for 14 days.

## Prerequisites

- Permission on the page, `rn:ews::<organization id>:monitoring:status-page/<page id>`:
  `monitoring:CreateIncident` to post one, `monitoring:UpdateIncident` to post an update or resolve
  it, `monitoring:DeleteIncident` to remove one. Without them the console says, for example,
  "Needs monitoring:CreateIncident."
- In the console, also `monitoring:DescribeStatusPages` on the page to open it.

## Post the incident

Every confirmed subscriber is emailed and every webhook subscriber called.

**Console**
1. Open **Monitoring**, then **Status pages**, and choose the page.
2. Under **Post an incident**, enter the title and the first update.
3. For **Impact**, choose `none`, `minor`, `major` or `critical`, and select the components it
   affects.
4. Choose **Post incident**.

The console posts it as `investigating`.

**CLI**
```sh
dcloud monitoring incidents create page-id --title "Payments failing" --impact major \
  --body "We are investigating." --component-ids 7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f
```

**API**
```http
POST /monitoring/api/status-pages/page-id/incidents
{ "title": "Payments failing", "impact": "major", "body": "We are investigating.",
  "componentIds": ["7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f"] }
```

`status` defaults to `investigating`; `resolved` posts it already closed.

## Post an update or resolve it

**Console**
1. On the page, find the incident under **Incidents**. The console lists the open incidents and
   those resolved in the last 30 days.
2. Choose its new status (the field starts at `monitoring`, or `resolved` for a resolved
   incident), enter what changed, and choose **Post update**. The status `resolved` closes the
   incident. The console does not change the impact.

**CLI**
```sh
dcloud monitoring incidents update page-id incident-id --status resolved \
  --body "Fixed: a certificate had expired."
```

**API**
```http
POST /monitoring/api/status-pages/page-id/incidents/incident-id/updates
{ "status": "resolved", "body": "Fixed: a certificate had expired." }
```

An update may also change the `impact`.

An update with any status other than `resolved` reopens a resolved incident.

## Remove an incident

Removing an incident deletes it and its updates from the page; nobody is told. In the console,
choose the incident's delete button and confirm "Delete “…” and its updates? Nobody is told.".
With the CLI:

```sh
dcloud monitoring incidents delete page-id incident-id
```

## Result

The answer carries the incident and `notified`, what was sent, for example "emailed 3, webhooks 1".

## When the incident is refused

- `400` "Component … is not on this page" for a component of another page.
- `404` "Status page not found" or "Incident not found".

## Related

- [Manage subscribers](manage-subscribers.md)
- [Add components to a status page](add-components.md)
- `monitoring.incidents.create` · `dcloud monitoring incidents create`
