Skip to main content

Download OpenAPI Specification

Download the OpenAPI/Swagger specification to explore the Rootly API endpoints or generate client libraries.

Official SDKs

Use the official Go and Python SDKs to integrate with the Rootly API.

OAuth 2.0 & OpenID Connect

Browser-based login, scoped third-party access, and user-independent client credentials tokens.

​
Chat API

The Chat API lets your application talk to Rootly AI, with optional incident or alert context. Its endpoints are under https://api.rootly.com/v1/ai/chat: Send message with either POST request. You can also send incident_id or alert_id to give the conversation context; these two fields are mutually exclusive. Pass session_id to continue an existing conversation. In the paths above, {session_id} and {id} both mean the same session UUID; the names follow each operation’s OpenAPI definition. The OpenAPI specification describes the complete request and response schemas. Chat API availability is controlled separately for each team. Rootly must enable the API chat rollout and API chat setting for the selected team, and Rootly Agent in Slack must also be enabled under AI SRE → Atlas → Conversations → Slack, or under AI & Agents → Features → Slack where that navigation is still in use. The API chat setting is not a self-service toggle either way; contact your Rootly account team to verify or enable access. If the surface is disabled, the API returns 403 with “AI chat is not enabled for this team.” Authenticate with a bearer API key or an OAuth token. OAuth calls need ai.chat:write for POST and DELETE, or ai.chat:read for GET; ai.chat:write also grants read access. The API checks the caller’s access to any incident or alert supplied as context.

​
How to generate an API Key?

To generate a new API key, navigate to: Organization dropdown > Organization Settings > API Keys > Generate New API Key. Rootly supports three scopes of API Keys:
Personal API Keys are bound to the user account that created them. If that user is removed from your organization, the key stops working and any automation depending on it breaks along with it. For production automation — Terraform runs, incident or alert creation from external tools like Jira, Zapier, scheduled scripts — use a Global or Team API Key instead, so the credential doesn’t depend on any single user’s account.

​
API key expiry and rotation

Every new API key must have an expiry date. It must be in the future and can be at most 5 years out, so plan how you will rotate a key before you issue it. name, description, and expires_at can be changed afterwards. The key’s kind, its role, and the token itself cannot — to issue a new token, rotate the key; to change its role or kind, revoke it and create a new one.

​
Rotation

Rotating a key issues a new token and returns it once. Store it immediately; it cannot be retrieved again. Two things to plan around:
  • Through the API, you can only rotate the key you authenticated with. Rotating a different key returns 403 Forbidden.
  • The grace period is what avoids downtime. The previous token keeps working for grace_period_minutes after rotation — from 0 to 1,440 minutes (24 hours), defaulting to 30. Set it to 0 to invalidate the old token immediately. The response’s grace_period_ends_at gives the exact moment the old token stops working.
A rotation that does not name a new expires_at sets one 90 days out. The usual sequence: rotate, deploy the new token everywhere, let the grace period elapse, and the old token invalidates itself.
Revoking a key is immediate and cannot be undone.

​
JSON:API Specification

Rootly is using the JSON:API (https://jsonapi.org) specification:
  • JSON:API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests.
  • JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability.
  • JSON:API requires use of the JSON:API media type (application/vnd.api+json) for exchanging data.

​
Authentication and Requests

All API requests use the Authorization: Bearer header over HTTPS. Rootly supports two token types: Both token types work with the same header — the API detects which one you sent automatically.

​
Rate limiting

Each API key has three separate per-minute budgets. By default, each one is 50 requests per minute:
  • When the per-key limit is exceeded, the API will return a 429 Too Many Requests HTTP status code with the response: {"error": "Rate limit exceeded. Try again later."}
    • Rootly recommends configuring your Alert Sources to handle this response and retry to create your Alert in Rootly.
  • X-RateLimit headers are included in every API response, providing real-time rate limit information:
    • X-RateLimit-Limit - The maximum number of requests permitted and the length of the window, in seconds
    • X-RateLimit-Remaining - The number of requests remaining in the current rate limit window
    • X-RateLimit-Used - The number of requests already made in the current window
    • X-RateLimit-Reset - The time at which the current rate limit window resets, in UTC epoch seconds

​
Per-IP limit

Requests are also limited to 10,000 every 5 minutes per IP address, and a request has to satisfy both this and the per-key limits above. Clients that share one IP address, such as a CI fleet or a NAT gateway, can reach it while every key is under its own limit.
A 429 from the per-IP limit looks different from a per-key 429. It does not use the X-RateLimit-* headers. Instead it carries a Retry-After header with the number of seconds to wait, and its body is {"error": "Too Many Requests. Retry Later."}.

​
Pagination

Endpoints that return a collection of items are paginated. /v1/alerts, /v1/incidents, and /v1/alert_events use cursor pagination; use it whenever you list these.

​
Cursor pagination

  1. Make the first request without page[number]. Set page[size] if you want something other than the default of 50.
  2. Read meta.next_cursor from the response and send it back as page[after] to get the next page.
  3. Stop when meta.next_cursor is empty.
  • If a request fails, wait and retry it with the same page[after] value. Do not start over from the first page.
  • To keep a copy of your data up to date, fetch only what changed since your last run with filter[updated_at][gte] instead of downloading everything again. This works on /v1/alerts and /v1/incidents.
  • page[size] can be up to 1,000. On /v1/alert_events the maximum is 50.
How each endpoint orders its results:
Page-number pagination on /v1/alerts is deprecated and will be removed. Requests for deep pages are slow and can time out. Switch to cursor pagination now.

​
Page-number pagination

Other endpoints use page numbers:
  • page[number] defaults to 1.
  • page[size] defaults to 50 items. The maximum is 1,000; a larger value is rejected with 400 Bad Request. Some endpoints have a lower maximum, listed in each endpoint’s entry in the API Reference.
GET /v1/oncalls is not paginated and returns every matching on-call in a single response. On a large roster, narrow it with its filters (filter[schedule_ids], filter[escalation_policy_ids], filter[user_ids], filter[service_ids], filter[group_ids]) and the since / until window.

​
Example

List alerts 100 at a time, then request the next page with the cursor from the first response: