Introduction

​

Authentication

Every API request must include an authentication key in the x-api-key header.

• Obtaining a key: To acquire an API key, customers must contact the technical team.

​

Authorization

Each key is scoped to a single organization, ensuring that access and data are restricted to the appropriate entity. Keys can also be limited by specific scopes, such as awareness:read, simulation:read, breach:read, or workspace:read which define the endpoints that can be accessed.

​

Pagination

All endpoints that return an array of objects support pagination through two request headers: x-item-limit and x-next-cursor. Even for endpoints with a limited number of items (e.g., /courses), pagination is available to maintain consistency across all endpoints.

• x-item-limit: Specifies the maximum number of items per page. The maximum allowed value is 100, with a default of 50.
• x-next-cursor: Pagination cursor for retrieving the next page of results. On the first request, the client may omit this header or include only x-item-limit. This value must be obtained from the ‘x-next-cursor’ response header of a previous API call. The cursor should be passed unchanged to fetch next pages. Here are some snippets to showcase the usage:

import requests

# Setup headers for API requests
headers = {
    'x-api-key': 'your_api_key',
    'x-item-limit': '50'
}

# First request
response = requests.get('https://public-api.tryriot.com/courses', headers=headers)
# Process first page of results...

# Add cursor to headers for next page request
headers['x-next-cursor'] = response.headers.get('x-next-cursor')

# Second request with updated headers including cursor
response = requests.get('https://public-api.tryriot.com/courses', headers=headers)
# Process second page of results...

​

Rate limits

Rate limiting is enforced across all API endpoints and is scoped by the authentication key. This ensures fair usage and prevents abuse of the system.

• Scope: Rate limits are applied per key, meaning all requests made with the same key share the same limit.
• Configuration: Specific rate limits are defined and managed by the technical team.
• Behavior: The rate limiting mechanism operates within fixed time intervals. If the limit is exceeded within a given interval, further requests will return 429 status code until the next interval begins.