> ## 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 Incident Management

> Create and manage manual incidents in DevHelm when automated detection isn't enough

By the end of this guide, you'll know how to create manual incidents, post updates, and resolve them — covering the full workflow for issues that automated monitors don't catch.

<Accordion title="Prerequisites">
  * DevHelm CLI installed or an API token
  * Familiarity with the [incident lifecycle](/incidents/overview)
</Accordion>

For conceptual background, see [Manual incidents](/incidents/manual-incidents).

## When to create a manual incident

* A customer reports an issue that your monitors haven't detected
* A deployment caused problems visible to users but not to health checks
* You're proactively tracking a known degradation
* An internal system is down but not covered by monitoring yet

## Full workflow

<Steps>
  <Step title="Create the incident">
    <CodeGroup>
      ```bash CLI theme={null}
      devhelm incidents create \
        --title "Checkout flow returning 500 for EU users" \
        --severity DOWN \
        --body "Customer reports started at 14:00 UTC. Affecting payment processing."
      ```

      ```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": "Checkout flow returning 500 for EU users",
          "severity": "DOWN",
          "body": "Customer reports started at 14:00 UTC. Affecting payment processing."
        }'
      ```
    </CodeGroup>

    Manual incidents are immediately set to `CONFIRMED` — no waiting for trigger rules or confirmation.
  </Step>

  <Step title="Investigate and post updates">
    Keep your team informed as you investigate. Timeline updates are posted 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": "Identified root cause — EU payment gateway connection pool exhaustion",
        "notifySubscribers": true
      }'
    ```

    Setting `notifySubscribers` to `true` sends the update through matched notification policies.
  </Step>

  <Step title="Associate with a monitor (optional)">
    If you find a related monitor, associate it for Dashboard visibility:

    ```bash 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": "Checkout flow 500s",
        "severity": "DOWN",
        "monitorId": "<checkout-monitor-id>"
      }'
    ```
  </Step>

  <Step title="Resolve the incident">
    <CodeGroup>
      ```bash CLI theme={null}
      devhelm incidents resolve <incident-id> \
        --message "Deployed hotfix v2.4.1 — connection pool limits increased"
      ```

      ```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": "Deployed hotfix v2.4.1 — connection pool limits increased"
        }'
      ```
    </CodeGroup>
  </Step>
</Steps>

## Severity selection

| Severity      | When to use                                               |
| ------------- | --------------------------------------------------------- |
| `DOWN`        | Complete failure — users cannot use the feature           |
| `DEGRADED`    | Partial failure — feature works but is slow or unreliable |
| `MAINTENANCE` | Planned issue — you're aware and working on it            |

## Alerting for manual incidents

Manual incidents flow through notification policies just like automated ones. If the incident is associated with a monitor, policies matching that monitor's tags, type, or ID apply. Otherwise, only catch-all policies (empty `matchRules`) and policies with `incident_status` rules match.

## Next steps

<CardGroup cols={2}>
  <Card title="Incident timeline" icon="clock" href="/incidents/timeline">
    Review the full event history for an incident.
  </Card>

  <Card title="Incidents guide" icon="wrench" href="/guides/incidents">
    Day-to-day incident management workflow.
  </Card>

  <Card title="Alerting guide" icon="bell" href="/guides/alerting">
    Configure how manual incident alerts are routed.
  </Card>
</CardGroup>