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

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

## Rate limits

The default rate limit is **1,200 requests/minute** per API key. Some endpoints interacting with external systems have lower limits.

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."
    }
  ]
}
```

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