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

# API Reference

> Complete REST API documentation for KeyStone OS.

## 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](/getting-started/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:

| Parameter | Type    | Default | Description             |
| --------- | ------- | ------- | ----------------------- |
| `limit`   | integer | 50      | Items per page (1-200)  |
| `offset`  | integer | 0       | Number of items to skip |

Paginated responses return:

```json theme={null}
{
  "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.

```bash theme={null}
# 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.

<Note>
  Admin endpoints (`/v1/admin/*`) are never versioned - they always return the latest schema.
</Note>

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

| Header                  | Description                                   |
| ----------------------- | --------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per minute                   |
| `X-RateLimit-Remaining` | Remaining requests in the current window      |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets         |
| `Retry-After`           | Seconds 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.