> ## 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.

# Manual Incidents

> Create and manage manual incidents in DevHelm for issues not caught by automated monitoring

Manual incidents let you track problems that automated monitors don't cover — deployment issues, customer-reported outages, or known degradations that haven't triggered a monitor yet.

## When to use manual incidents

* **Deployment failures** — a bad deploy causes user-facing issues before monitors detect it
* **Customer reports** — users report problems that your checks haven't caught
* **Partial outages** — a subset of users is affected but aggregate metrics look healthy
* **Proactive tracking** — you know something is wrong and want to start the incident timeline before automation kicks in

## Creating a manual incident

<CodeGroup>
  ```bash CLI theme={null}
  devhelm incidents create \
    --title "Database latency spike" \
    --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 latency spike",
      "severity": "DOWN"
    }'
  ```
</CodeGroup>

### Request fields

| Field       | Type   | Required | Description                          |
| ----------- | ------ | -------- | ------------------------------------ |
| `title`     | string | Yes      | Short summary of the issue           |
| `severity`  | string | Yes      | `DOWN`, `DEGRADED`, or `MAINTENANCE` |
| `monitorId` | UUID   | No       | Associate with a specific monitor    |
| `body`      | string | No       | Detailed description or context      |

Manual incidents have source `MANUAL` and are immediately set to `CONFIRMED` status — they skip the watching and trigger phases since a human has already confirmed the problem.

<Note>
  Associating a `monitorId` links the incident to a specific monitor in the Dashboard and timeline. The monitor's notification policies will apply for alert routing.
</Note>

## Adding updates

Post updates to the incident timeline to keep your team informed. Timeline updates are posted via the API:

```bash API 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": "Identified root cause — connection pool exhaustion",
    "notifySubscribers": true
  }'
```

### Update fields

| Field               | Type    | Required | Description                                   |
| ------------------- | ------- | -------- | --------------------------------------------- |
| `body`              | string  | Yes      | Update message or context                     |
| `newStatus`         | string  | No       | Transition to a new status (e.g., `RESOLVED`) |
| `notifySubscribers` | boolean | No       | Send notification to subscribed channels      |

## Resolving a manual incident

<CodeGroup>
  ```bash CLI theme={null}
  devhelm incidents resolve <incident-id> \
    --message "Connection pool limits increased, latency back to normal"
  ```

  ```bash API theme={null}
  curl -X POST https://api.devhelm.io/api/v1/incidents/<incident-id>/resolve \
    -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "body": "Connection pool limits increased, latency back to normal"
    }'
  ```
</CodeGroup>

Resolved manual incidents get `resolutionReason: MANUAL`.

## Manual vs automated incidents

| Aspect             | Automated                                                 | Manual                                                                         |
| ------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------ |
| **Source**         | `MONITORS`, `STATUS_DATA`, `RESOURCE_GROUP`               | `MANUAL`                                                                       |
| **Initial status** | `WATCHING` → `TRIGGERED` → `CONFIRMED`                    | `CONFIRMED` immediately                                                        |
| **Recovery**       | Auto-resolves when recovery policy is met                 | Must be resolved by a user                                                     |
| **Reopening**      | Reopens automatically if the monitor fails again          | Does not reopen automatically                                                  |
| **Alerting**       | Routes through notification policies based on the monitor | Routes through policies matching the associated monitor, or catch-all policies |

## Next steps

<CardGroup cols={2}>
  <Card title="Incident timeline" icon="clock" href="/incidents/timeline">
    Track all status changes and updates.
  </Card>

  <Card title="Incidents overview" icon="circle-exclamation" href="/incidents/overview">
    Understand the full incident lifecycle.
  </Card>

  <Card title="Alerting overview" icon="bell" href="/alerting/overview">
    Configure where manual incident notifications are sent.
  </Card>
</CardGroup>