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

# incident.io

> Open incident.io incidents automatically when DevHelm detects an outage

Connect DevHelm to [incident.io](https://incident.io) to declare an incident automatically when an outage is detected. DevHelm calls the **incident.io v2 API** (`POST /v2/incidents`); from there incident.io runs its own escalation, status page updates, and team communication.

## Setup

<Steps>
  <Step title="Create an incident.io API key (and find a severity ID)">
    1. In incident.io, go to **Settings** → **API keys** and create a key with the **Create incidents** permission enabled
    2. Copy the key — incident.io shows it only once
    3. *(Optional)* Severities are specific to your organization, so fetch their IDs with the List Severities API:

    ```bash theme={null}
    curl https://api.incident.io/v1/severities \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    Copy the `id` of the severity you want DevHelm-created incidents to use. If you omit it, the incident is created without an explicit severity.
  </Step>

  <Step title="Create the alert channel in DevHelm">
    <CodeGroup>
      ```bash CLI theme={null}
      devhelm alert-channels create \
        --name "incident.io" \
        --type incident_io \
        --config '{"channelType":"incident_io","apiKey":"inc_live_xxxxxxxx","severityId":"01FCNDV6P870EA6S7TK1DSYDG0","visibility":"public"}'
      ```

      ```yaml devhelm.yml theme={null}
      alertChannels:
        - name: incident.io
          config:
            channelType: incident_io
            apiKey: ${INCIDENT_IO_API_KEY}
            severityId: ${INCIDENT_IO_SEVERITY_ID} # optional
            visibility: public
      ```
    </CodeGroup>
  </Step>

  <Step title="Test the channel">
    ```bash theme={null}
    devhelm alert-channels test <channel-id>
    ```
  </Step>
</Steps>

## Configuration

| Field        | Description                                                          | Required |
| ------------ | -------------------------------------------------------------------- | -------- |
| `apiKey`     | incident.io API key with the **Create incidents** permission         | Yes      |
| `severityId` | Severity ID from `GET /v1/severities`; omit for no explicit severity | No       |
| `visibility` | Incident visibility: `public` or `private` (default: `public`)       | No       |

## Lifecycle behavior

incident.io is a **trigger-resolve** channel:

| DevHelm event     | incident.io action                  |
| ----------------- | ----------------------------------- |
| Incident created  | Declares a new incident             |
| Incident resolved | Resolves the corresponding incident |

Once the incident exists, incident.io drives escalation, status page updates, and communications — DevHelm just keeps the incident state in sync.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed (HTTP 401 / 403)">
    The API key is missing the **Create incidents** permission, or it was revoked. In **Settings → API keys**, create a new key with that permission and update the channel config.
  </Accordion>

  <Accordion title="Severity ID doesn't exist">
    Severities are organization-specific. Re-fetch them with `GET https://api.incident.io/v1/severities` and copy a current `id`. Note the version split: **severities live on v1**, incidents are created on **v2**.
  </Accordion>

  <Accordion title="Visibility rejected">
    `visibility` must be exactly `public` or `private` (lowercase). Any other value is rejected by incident.io.
  </Accordion>
</AccordionGroup>