Introduction

With the Rillet API you can access and manage your own data.

Environments

Production: https://api.rillet.com
Test: https://sandbox.api.rillet.com

Authentication

The Rillet API uses API keys to authenticate requests. You can contact your Rillet team to enable access for you and after that create and manage your API keys in the Organization Settings page.

The key needs to be added to the Authorization header of all requests.

Example:

curl --request GET \
  --url https://sandbox.api.rillet.com/products \
  --header 'Authorization: Bearer [API key]'

Versioning

To target a specific version of the API you will need to include a HTTP request header. By default (if no header is provided) the requests will target v1.0 of the API.

curl --request GET \
  --url https://sandbox.api.rillet.com/products \
  --header 'X-Rillet-API-Version: 2'

Pagination

The Rillet API supports keyset based pagination for all GET endpoints that return lists of objects. This ensures fixed-size payloads with consistent response times across the API. Objects are returned in reverse chronological order and each response includes a pagination object with the cursor needed to access the next page:

"pagination": {
    "next_cursor": "VdW1ptsZbOB4E1fq"
  }

In order to access the next page, the cursor is passed with the cursor query parameter. Subsequent calls will also return a next cursor or no cursor if this is the last page. Cursor values are valid for 2 hours. If an invalid or expired cursor is passed, a new pagination sequence will begin from the first page.

Page size is defined by the limit query parameter. If no value is defined, a default size of 25 is used. The maximum allowed value for the page size is 100.

Idempotency

The Rillet API supports idempotency keys for safely retrying POST requests so that if a connection error occurs, you can safely repeat the request without risk of creating a second object. Idempotency keys in other requests other than POST will be ignored.

To perform an idempotent request, provide an Idempotency-Key header to the request.

Example:

curl --request POST  
  --url https://sandbox.api.rillet.com/products
  --header 'Idempotency-Key: f0e9a51e-905d-4caf-a5dc-64d326574646'
  --header 'Authorization: Bearer [API key]'

The resulting status code and response is saved on the first request and returned on every following request. We save responses for 24 hours. After that a request with the same idempotency key will create a new object. If the object creation fails because of an error (for example failing a validation), the response will not be saved and can be retried. If a second requests arrives before the first one finished processing, the API will respond with 409 Conflict.

The client decides the unique idempotency key to use. We recommend random keys with high entropy to avoid collisions, such as version 4 UUIDs.

Error handling

The Rillet API uses standard HTTP response codes to indicate the success or failure of a request. For some 4xx errors, a more detailed response body is returned that also allows for error handling, this response is produced according to RFC 9457, e.g.:

{
  "type": "https://rillet.com/illegal-argument",
  "title": "Bad Request",
  "status": 400,
  "detail": "The start date (2026-01-01) must not be after the end date (2025-12-31). Please review the contract item."
}

Rate limiting

Rillet allows a maximum of 60 API requests over a rolling window of one minute. Requests over that threshold will fail with HTTP code 429.

Monetary values

Monetary values are represented with an object containing both amount and currency:

{
  "amount": "100.99",
  "currency": "USD"
}

The amount property is a string representation of the decimal monetary value, using a period . as the decimal separator. In most cases, the number of decimal places will be no larger than the decimal places for the given currency, as defined in ISO-4217. However, Rillet allows more decimal places for specific amounts (e.g. unit price of a product), so API consumers are encouraged to implement flexible parsing in order to avoid inaccuracies.

The currency property is always the three-letter currency acronym, as defined in ISO-4217.

OpenAPI specification

Rillet's API is available for download using the OpenAPI specification here.