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

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

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

{
  "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 [e-mail].