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.

​
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

  • There is a default limit of 3000 GET, HEAD, and OPTIONS calls per API key every minute. The limit is calculated over a 1-minute sliding window looking back from the current time. While the limit can be configured to support higher thresholds, you must first contact your Rootly Customer Success Manager to make any adjustments.
  • There is a default limit of 3000 POST, PUT, PATCH or DELETE calls per API key every minute. Alert creation is limited to 50 per minute per API key. The limit is calculated over a 1-minute sliding window looking back from the current time. While the limit can be configured to support higher thresholds, you must first contact your Rootly Customer Success Manager to make any adjustments.
    • Note: The default rate limit for Alert Creation is 50 alerts every minute, per API key or alert source.
  • When rate limits are 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 time window (for example, “3000, 3000;window=60” for 3000 requests per minute)
    • 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

​
Pagination

  • Pagination is supported for all endpoints that return a collection of items.
  • Pagination is controlled by the page query parameter

​
Example