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

# Incidents

> Create and manage incidents to communicate issues to your users

Incidents are how you communicate ongoing issues to your users. When something goes wrong with your services, create an incident to keep users informed.

## Incident Lifecycle

Incidents progress through these statuses:

| Status            | Description                                  |
| ----------------- | -------------------------------------------- |
| **Investigating** | You're aware of an issue and looking into it |
| **Identified**    | You've found the root cause                  |
| **Monitoring**    | A fix has been applied and you're monitoring |
| **Resolved**      | The issue is fully resolved                  |

## Creating an Incident

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Dashboard > Incidents**
    2. Click **Create Incident**
    3. Fill in the title, severity, and affected services
    4. Add an initial update message
    5. Click **Create**
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    kodo incidents create \
      --title "Database connectivity issues" \
      --status investigating \
      --severity major \
      --services "API,Database" \
      --message "We are investigating reports of connection timeouts"
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST "https://kodostatus.com/api/v1/incidents" \
      -H "X-API-Key: your_api_key" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Database connectivity issues",
        "status": "investigating",
        "severity": "major",
        "services": ["API", "Database"],
        "message": "We are investigating reports of connection timeouts"
      }'
    ```
  </Tab>
</Tabs>

## Severity Levels

Choose the appropriate severity based on impact:

| Severity     | Use When                                              |
| ------------ | ----------------------------------------------------- |
| **Minor**    | Small number of users affected, workarounds available |
| **Major**    | Significant impact, core functionality degraded       |
| **Critical** | Complete outage, all users affected                   |

## Posting Updates

Keep users informed by posting updates as the situation evolves:

```bash theme={null}
kodo incidents update inc_abc123 \
  --status identified \
  --message "We've identified a misconfigured database connection pool"
```

## Best Practices

<AccordionGroup>
  <Accordion title="Be transparent">
    Users appreciate honesty. If you don't know the cause yet, say so.
  </Accordion>

  <Accordion title="Update frequently">
    Even if there's no new information, post updates every 30-60 minutes during active incidents.
  </Accordion>

  <Accordion title="Include ETAs carefully">
    Only provide time estimates if you're confident. "We expect to have more information within the hour" is better than a specific time you might miss.
  </Accordion>

  <Accordion title="Post a retrospective">
    After major incidents, consider adding a final update explaining what happened and what you're doing to prevent it.
  </Accordion>
</AccordionGroup>

## Auto-Created Incidents

Kodo can automatically create incidents when monitors detect failures. Auto-created incidents have source tracking (visible as badges in the dashboard) and pass through a safeguard pipeline including flap protection, cooldowns, and dedup.

You can configure auto-created incidents to start as **drafts** (hidden from the public status page until you review them) or to publish immediately.

<Card title="Incident Safeguards" icon="shield" href="/automation/incident-safeguards">
  Learn about flap protection, draft mode, cooldowns, notification batching, and other safeguards that prevent false incidents.
</Card>

### Incident Sources

| Source            | Badge               | Meaning                              |
| ----------------- | ------------------- | ------------------------------------ |
| Manual            | --                  | Created by a team member             |
| API               | `API`               | Created via the REST API             |
| Auto: Uptime      | `Auto: Uptime`      | HTTP monitor detected failures       |
| Auto: Heartbeat   | `Auto: Heartbeat`   | Heartbeat monitor timed out          |
| Auto: Integration | `Auto: Integration` | Third-party integration degraded     |
| Auto: Beacon      | `Auto: Beacon`      | Client error rate exceeded threshold |

### Draft Incidents

When your organization has draft mode enabled (**Settings > Automation**):

* Auto-created incidents show a **Draft** badge in the dashboard
* They are **not** visible on the public status page
* Click **Publish** to make them public, or wait for auto-publish if configured

## Notifications

When you create or update an incident, subscribers are automatically notified based on your [notification settings](/notifications/channels). Auto-created incidents respect your [notification batching](/automation/incident-safeguards#notification-batching) settings.