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

# Introduction

> The incident.io API — endpoints, authentication, rate limits, and error handling.

This is the API reference for incident.io. It documents available API endpoints, provides examples of how to use them, and covers authentication, rate limits, and error handling.

The API is hosted at `https://api.incident.io/`, and you will need an API key from your [incident.io dashboard](https://app.incident.io/~/settings/api-keys) to make requests.

<CardGroup cols={2}>
  <Card title="OpenAPI specification" icon="file-code" href="https://api.incident.io/v1/openapiV3.json">
    Download the full OpenAPI 3.0 spec to generate clients or feed to your tools.
  </Card>

  <Card title="Command-line interface" icon="terminal" href="/integrations/cli">
    Manage incidents, alerts, and schedules from your terminal with `inc`.
  </Card>
</CardGroup>

## Authentication

For all requests, you'll need an API key. To create one, visit [Settings → API keys](https://app.incident.io/~/settings/api-keys). When you create the key, you'll choose what actions it can take. Keys can have account-level permissions, [team-scoped permissions](/admin/api-keys#team-scoped-permissions), or both. We'll only show the token once, so store it somewhere safe.

API keys remain valid even if the creating user is deactivated. For more details on managing keys and permissions, see [API keys](/admin/api-keys).

Set the `Authorization` header using a Bearer scheme:

```
Authorization: Bearer <YOUR_API_KEY>
```

### Make your first request

Any key can call the [identity endpoint](/api-reference/utilities-v1/show-identity), which returns details of the key you authenticated with:

```bash theme={null}
curl --request GET https://api.incident.io/v1/identity \
  --header 'Authorization: Bearer <YOUR_API_KEY>'
```

```json theme={null}
{
  "identity": {
    "name": "Alertmanager token",
    "roles": ["viewer"],
    "dashboard_url": "https://app.incident.io/my-org"
  }
}
```

If you get a `401`, check the key is passed exactly as shown, with no quotes around the token.

## Rate limits

The default rate limit is **1,200 requests/minute** per API key. Some endpoints have lower limits documented below. Note that these limits are subject to change unless otherwise contracted:

| Endpoint                                       | Burst | Sustained |
| ---------------------------------------------- | ----- | --------- |
| List incidents (v1 and v2), Show incident (v2) | 60    | 60/min    |
| Bulk update catalog entries (v3)               | 10    | 60/min    |
| Update catalog entry (v3)                      | 25    | 300/min   |
| Show post-mortem document content (v1)         | 60    | 60/min    |
| Preview schedule entries (v2)                  | 10    | 6/min     |
| Create retrospective status page incident (v2) | 300   | 300/min   |
| Update telemetry data source (v2)              | 5     | 30/min    |

Burst is how many requests you can make at once; sustained is the rate at which your allowance refills.

Creating incidents is limited separately: an API key can create **10 incidents per hour** where a chat channel is created, and **300 per hour** otherwise. If you're importing historical incidents, [contact support](mailto:support@incident.io) to raise this temporarily.

When you exceed a rate limit, the API responds with `429 Too Many Requests`:

```json theme={null}
{
  "type": "too_many_requests",
  "status": 429,
  "request_id": "b839a403-7704-41c1-bf6a-39a2d68caefa",
  "rate_limit": {
    "name": "api_key_name",
    "limit": 1200,
    "remaining": 0,
    "retry_after": "Thu, 17 Apr 2025 11:17:18 UTC"
  },
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests. We recommend exponential backoff."
    }
  ]
}
```

## Pagination

List endpoints are cursor-paginated. Pass `page_size` to control how many records you get per request (default 25), and use the `after` cursor from `pagination_meta` to fetch the next page:

```json theme={null}
{
  "incidents": [...],
  "pagination_meta": {
    "after": "01FCNDV6P870EA6S7TK1DSYDG0",
    "page_size": 25
  }
}
```

To iterate through all records, repeat the request with `after` set to the cursor from the previous response, until a response returns fewer records than `page_size`. The maximum `page_size` varies by endpoint and is documented on each endpoint's page.

## Errors

We use standard HTTP response codes. The response body is JSON with a `type`, `status`, `request_id`, and a list of `errors`:

```json theme={null}
{
  "type": "validation_error",
  "status": 422,
  "request_id": "631766c4-4afd-4803-997c-cd700928fa4b",
  "errors": [
    {
      "code": "is_required",
      "message": "A severity is required to open an incident",
      "source": { "field": "severity_id" }
    }
  ]
}
```

The `request_id` can be provided to support to help debug issues.

## Compatibility

We won't make breaking changes to existing endpoints, but expect integrators to upgrade within 3 months of deprecation. Backwards-compatible changes include:

* Adding new endpoints
* Adding new properties to responses
* Reordering response properties
* Adding optional request parameters
* Altering the format or length of IDs
* Adding new enum values

When breaking changes are unavoidable, we create a new version on a separate path (e.g. `/v1/incidents` → `/v2/incidents`) and run them in parallel.

For questions, email [support@incident.io](mailto:support@incident.io).