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

# Create incidents via API

> For IR automation and ChatOps integrations.

Every console action on incidents has an API equivalent. You can
wire alerting (PagerDuty, Opsgenie) or ChatOps (Slack slash
commands, GitHub Actions) to file and update incidents directly.

## Auth

API keys are issued per organisation. Four scopes cover incidents
and maintenance:

* `read:incidents` and `write:incidents`: list and retrieve; create,
  patch, publish, resolve, delete.
* `read:maintenances` and `write:maintenances`: list and retrieve;
  create, patch, start, complete, cancel.

Grant `read:incidents` / `write:incidents` and `read:maintenances` /
`write:maintenances` as needed; write scopes do not include read.

## File a new incident from a Slack slash command

```bash theme={null}
curl -X POST https://use.observer/api/v1/incidents \
  -H "Authorization: Bearer obs_pub_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Checkout API errors",
    "severity": "major",
    "affected_services": ["<service-uuid>"],
    "publish": true,
    "initial_message": {
      "type": "Investigating",
      "description": "Investigating elevated error rate on checkout."
    }
  }'
```

The response includes `id`, the projected lifecycle state, and the
affected-service rollup. Use the `id` for follow-up calls.

## Append a status update

```bash theme={null}
curl -X POST https://use.observer/api/v1/incidents/$ID/messages \
  -H "Authorization: Bearer obs_pub_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Identified",
    "description": "Identified bad deploy. Rolling back."
  }'
```

A `Resolved` message auto-marks the parent incident resolved.

## Resolve

```bash theme={null}
curl -X POST https://use.observer/api/v1/incidents/$ID/resolve \
  -H "Authorization: Bearer obs_pub_..." \
  -H "Content-Type: application/json" \
  -d '{"description": "Rollback complete. Error rate back to baseline."}'
```

## Schedule a maintenance window

```bash theme={null}
curl -X POST https://use.observer/api/v1/maintenances \
  -H "Authorization: Bearer obs_pub_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Database upgrade",
    "scheduled_start_at": "2026-06-01T02:00:00Z",
    "scheduled_end_at": "2026-06-01T04:00:00Z",
    "affected_services": ["<service-uuid>"]
  }'
```

## Idempotency

The `from-metric` endpoint is dedupe-protected:

```bash theme={null}
curl -X POST https://use.observer/api/v1/incidents/from-metric/$METRIC_ID \
  -H "Authorization: Bearer obs_pub_..."
```

Returns the existing unpublished draft with the same title created in
the last 30 minutes or, failing that, an unresolved incident affecting
any of the metric's services created in the last 60 minutes. Useful
when an alert hook may fire duplicate webhooks.

> [!NOTE]
>
> **Lifecycle reference**
>
> Every endpoint above corresponds to a documented state transition.
> See [Incident lifecycle reference](https://docs.use.observer/docs/reference/incident-lifecycle.md)
> for the full state machine.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.