Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.keystoneos.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Base URL

https://api.keystoneos.xyz/v1

​
Authentication

All API requests require a Bearer token in the Authorization header: 
Authorization: Bearer {access_token}
See Authentication for details on obtaining tokens.

​
Content type

All requests and responses use JSON: 
Content-Type: application/json

​
Pagination

List endpoints support pagination with query parameters:
ParameterTypeDefaultDescription
limitinteger50Items per page (1-200)
offsetinteger0Number of items to skip
Paginated responses return: 
{
  "items": [...],
  "total": 142,
  "limit": 50,
  "offset": 0
}

​
Versioning

The API uses header-based versioning with semantic versions. Each platform environment is pinned to a specific API version on creation and will continue to receive that version’s response shapes, even as the API evolves.

​
How it works

  1. Environment pin (default) - When you create an environment, it is pinned to the current API version. All requests from that environment automatically use that version.
  2. Per-request override - Send the Keystone-Version header to override the pinned version for a single request.
  3. Backward compatibility - The API always runs the latest logic internally. When your pinned version is older than the current version, responses are automatically transformed to match the schema you expect.
# Override the version for a single request
curl -H "Keystone-Version: 0.1.0" \
     -H "Authorization: Bearer {token}" \
     https://api.keystoneos.xyz/v1/settlements
The Keystone-Version response header confirms which version was used: 
Keystone-Version: 0.1.0
The /v1/ URL prefix is a structural namespace, not the version itself. The actual version is controlled via the header and environment pin.
Admin endpoints (/v1/admin/*) are never versioned - they always return the latest schema.

​
Rate limits

The default rate limit is 600 requests per minute per environment. Rate-limited requests receive a 429 response with a Retry-After header indicating when to retry.
HeaderDescription
X-RateLimit-LimitMaximum requests per minute
X-RateLimit-RemainingRemaining requests in the current window
X-RateLimit-ResetUnix timestamp when the window resets
Retry-AfterSeconds to wait before retrying (only on 429)
Per-environment rate limits can be configured via the environments API. Contact support for limits above 600 RPM.

​
Endpoints

The full API reference is auto-generated from the OpenAPI specification served by the KeyStone API. Browse the endpoints using the sidebar navigation.