Download OpenAPI Specification

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

​
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 TypePermissions
Global API KeyGlobal API Keys are assigned 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 KeyTeam 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 KeyPersonal API Keys inherit the permissions of the user who created the API key.

​
JSON:API Specification

Rootly is using 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

We use standard HTTP Authentication over HTTPS to authorize your requests.

curl --request GET \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer YOUR-TOKEN' \
--url https://api.rootly.com/v1/incidents

​
Rate limiting

  • There is a default limit of approximately 3000 GET calls per API key every 60 seconds. The limit is calculated over a 60-second 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 approximately 3000 PUT, POST, PATCH or DELETE calls per API key every 60 seconds. The limit is calculated over a 60-second 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.
  • The response to the API call will return 429 HTTP status code - Request Limit Exceeded and Rootly will not ingest the event.
  • Additional headers will be returned giving you information about the limit:
    • RateLimit-Limit - The maximum number of requests that the consumer is permitted to make.
    • RateLimit-Remaining - The number of requests remaining in the current rate limit window.
    • 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

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