> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Incidents Guide

> How to view, manage, and resolve incidents through the Dashboard, CLI, and API

This guide covers day-to-day incident management. For conceptual background on how incidents work, see [Incidents overview](/incidents/overview).

## Viewing incidents

### Dashboard

The Dashboard shows active incidents on the overview page with severity, affected monitor, duration, and affected regions. Click an incident to see its full timeline, check results, and update history.

### CLI

```bash theme={null}
# List incidents
devhelm incidents list

# Get incident details
devhelm incidents get <incident-id>

# JSON output for scripting
devhelm incidents list -o json
```

The CLI doesn't filter by status — pipe `-o json` output to `jq`, or use the API's `status` query parameter (below).

### API

```bash theme={null}
# List incidents (paginated)
curl https://api.devhelm.io/api/v1/incidents \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN"

# Filter by status
curl "https://api.devhelm.io/api/v1/incidents?status=CONFIRMED" \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN"
```

## Creating manual incidents

For issues that aren't caught by automated monitoring:

<CodeGroup>
  ```bash CLI theme={null}
  devhelm incidents create \
    --title "Database migration issue" \
    --severity DOWN
  ```

  ```bash API theme={null}
  curl -X POST https://api.devhelm.io/api/v1/incidents \
    -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Database migration issue",
      "severity": "DOWN"
    }'
  ```
</CodeGroup>

## Resolving incidents

### Automatic resolution

Most incidents resolve automatically when the monitor recovers. The recovery policy controls this:

* The monitor must pass a configurable number of **consecutive checks** (default: 2)
* A configurable number of **regions must be passing** (default: 2)
* After resolution, a **cooldown period** prevents the same monitor from immediately re-opening a new incident (default: 5 minutes)

### Manual resolution

<CodeGroup>
  ```bash CLI theme={null}
  devhelm incidents resolve <incident-id>
  ```

  ```bash API theme={null}
  curl -X POST https://api.devhelm.io/api/v1/incidents/<incident-id>/resolve \
    -H "Authorization: Bearer $DEVHELM_API_TOKEN"
  ```
</CodeGroup>

## Updating incidents

Incident severity is set at creation (or by trigger rules for automated incidents) and can't be changed directly. To add context to an active incident — for example, to note that a full outage has degraded into a partial one — post a timeline update via the API:

```bash theme={null}
curl -X POST https://api.devhelm.io/api/v1/incidents/<incident-id>/updates \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Service partially restored — performance still degraded",
    "notifySubscribers": true
  }'
```

## Incident timeline

Each incident tracks a timeline of events:

* **Created** — initial detection with trigger rule and affected regions
* **Severity changed** — escalation or de-escalation
* **Resolved** — automatic recovery or manual resolution
* **Reopened** — monitor failed again after resolution

## Maintenance windows

Schedule maintenance to suppress alerts during planned downtime:

```bash theme={null}
devhelm maintenance-windows create \
  --start "2026-04-15T02:00:00Z" \
  --end   "2026-04-15T04:00:00Z" \
  --reason "Database upgrade" \
  --monitor <monitor-id>
```

During a maintenance window, incidents still record but **notification policies are suppressed** — your team won't get paged.

## Next steps

<CardGroup cols={2}>
  <Card title="Alerting guide" icon="bell" href="/guides/alerting">
    Configure how your team gets notified about incidents.
  </Card>

  <Card title="Monitors guide" icon="signal" href="/guides/monitors">
    Fine-tune incident policies per monitor.
  </Card>
</CardGroup>