Introduction

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 to make requests.

OpenAPI specification

Download the full OpenAPI 3.0 spec to generate clients or feed to your tools.

Command-line interface

Manage incidents, alerts, and schedules from your terminal with inc.

Authentication

For all requests, you’ll need an API key. To create one, visit 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, 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. Set the Authorization header using a Bearer scheme:

Authorization: Bearer <YOUR_API_KEY>

Make your first request

Any key can call the identity endpoint, which returns details of the key you authenticated with:

curl --request GET https://api.incident.io/v1/identity \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

{
  "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 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:

{
  "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:

{
  "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:

{
  "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.

Getting started

Webhooks

Audit logs

Deprecated endpoints

OpenAPI specification

Command-line interface

Authentication

Make your first request

Rate limits

Rate limit headers

Exceeding a rate limit

Errors

Compatibility

OpenAPI specification

Command-line interface

​Authentication

​Make your first request

​Rate limits

​Rate limit headers

​Exceeding a rate limit

​Pagination

​Errors

​Compatibility

Authentication

Make your first request

Rate limits

Rate limit headers

Exceeding a rate limit

Pagination

Errors

Compatibility