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

### Rate limit headers

Every response to a request made with an API key tells you where you stand, so you can slow down before you get a 429.

| Header                  | What it means                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | The limit that applies to this request, then every limit we checked and the window it covers |
| `X-RateLimit-Remaining` | How many requests you have left right now                                                    |
| `X-RateLimit-Used`      | How many requests you have used                                                              |
| `X-RateLimit-Reset`     | Unix timestamp in seconds for when you are back to a full allowance                          |

For example:

```
X-RateLimit-Limit: 60, 1200;window=60, 60;window=60
X-RateLimit-Remaining: 59
X-RateLimit-Used: 1
X-RateLimit-Reset: 1785257176
```

More than one limit can apply to the same request. Here your API key allows 1,200 requests a minute and the endpoint allows 60 a minute. `X-RateLimit-Limit` lists both. `Remaining`, `Used` and `Reset` describe whichever has least left, because that is the one you will run into first.

Limits top up continuously rather than resetting at a set time. The window is in seconds and tells you the rate you can keep up. `1200;window=60` means 1,200 requests a minute, which is 20 requests a second that you can sustain indefinitely.

Two things to expect. `X-RateLimit-Remaining` can drop by more than the number of requests you made, because some limits are shared across all the API keys on your account. And the headers are left out entirely if we cannot work out your limits for a request, so treat them as missing rather than as zero.

### Exceeding a rate limit

When you go over a rate limit, the API responds with `429 Too Many Requests` and a `Retry-After` header giving the number of seconds to wait:

```
Retry-After: 10
X-RateLimit-Limit: 60, 60;window=60
X-RateLimit-Remaining: 0
X-RateLimit-Used: 60
X-RateLimit-Reset: 1785257176
```

Use `Retry-After` to decide how long to back off. It tells you when your next request will go through. `X-RateLimit-Reset` is later than that, because it is when your whole allowance is back.

The response body has the same information:

```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": "2025-04-17T11:17:18Z"
  },
  "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).