Skip to main content
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.

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

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