> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rootly API overview: authentication and conventions

> Learn how to authenticate with the Rootly API using bearer tokens, work with rate limits, pagination, filtering, and JSON:API endpoints.

<CardGroup cols={2}>
  <Card title="Download OpenAPI Specification" icon="download" href="https://rootly.com/swagger/v1/swagger.json">
    Download the OpenAPI/Swagger specification to explore the Rootly API endpoints or generate client libraries.
  </Card>

  <Card title="Official SDKs" icon="code" href="/api-reference/sdks">
    Use the official Go and Python SDKs to integrate with the Rootly API.
  </Card>

  <Card title="OAuth 2.0 & OpenID Connect" icon="shield-halved" href="/api-reference/oauth2">
    Browser-based login, scoped third-party access, and user-independent client credentials tokens.
  </Card>
</CardGroup>

## 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`:

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/v1/ai/chat` | Send a message and receive a reply |
| `POST` | `/v1/ai/chat/stream` | Send a message and receive a server-sent event stream |
| `GET` | `/v1/ai/chat/sessions/{session_id}/messages` | Read a session's message history |
| `DELETE` | `/v1/ai/chat/sessions/{id}` | Delete a session |

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](https://rootly.com/swagger/v1/swagger.json) 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`](/api-reference/oauth2) 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:

| API Key Type | Permissions |
| - | - |
| Global API Key | Global API Keys are assigned an On-Call and Incident Response role when they're generated. The assigned role's permissions control the key's permissions. Global API Keys are able to interact with all entities within your Rootly instance. |
| Team API Key | Team API Keys inherit the same permissions of a Team Admin. They have full read and edit access to any Rootly entity that team owns, such as the team's Schedules and Escalation Policies. |
| Personal API Key | Personal API Keys inherit the permissions of the user who created the API key. |

<Warning>
  **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.
</Warning>

## JSON:API Specification

Rootly is using the **JSON:API** ([https://jsonapi.org](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:

| Method | Token source | Best for |
| - | - | - |
| **API Key** | Generated in **Organization Settings → API Keys** | Scripts, Terraform, Zapier, quick integrations |
| **OAuth 2.0 Access Token** | Obtained via [OAuth 2.0 / OIDC](/api-reference/oauth2) flows | CLI/TUI tools, third-party apps, MCP clients, CI with scoped access |

Both token types work with the same header — the API detects which one you sent automatically.

```bash theme={null}
curl --request GET \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer YOUR-API-KEY-OR-OAUTH-TOKEN' \
--url https://api.rootly.com/v1/incidents
```

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

```bash theme={null}
curl --request GET \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer YOUR-TOKEN' \
--url https://api.rootly.com/v1/incidents?page[number]=1&page[size]=10
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.