> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toktra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Everything you need to know about the Toktra Public API v1.

The Toktra Public API gives you programmatic access to your organization's AI governance data — usage records, policies, budgets, users, and alerts. All endpoints are served over HTTPS and return JSON.

## Base URL

```
https://api.toktra.io/v1
```

A staging environment is available at `https://api.staging.toktra.io/v1` for testing integrations before you go live.

## Authentication

The API uses **OAuth 2.0 Bearer tokens** obtained via the `client_credentials` grant. Pass your token in the `Authorization` header on every request:

```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

You can also authenticate with a long-lived **API key** as a simpler alternative for server-to-server integrations. See [Authentication](/api/authentication) for full details on both methods.

## Rate limiting

The API enforces a limit of **1,000 requests per minute** per API key. Every response includes rate limit headers so you can track your consumption:

| Header                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per minute      |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets    |

When you exceed the limit, the API returns a `429 Too Many Requests` response along with a `Retry-After` header indicating how many seconds to wait before retrying.

## Pagination

List endpoints use **cursor-based pagination**. This approach is stable and efficient for large datasets — pages don't shift when records are added or removed.

Pass `cursor` and `limit` as query parameters:

| Parameter | Type    | Default | Description                                                                         |
| --------- | ------- | ------- | ----------------------------------------------------------------------------------- |
| `cursor`  | string  | —       | Opaque cursor from `next_cursor` in the previous response. Omit for the first page. |
| `limit`   | integer | 25      | Items per page. Min `1`, max `100`.                                                 |

Every paginated response includes:

```json theme={null}
{
  "items": [...],
  "next_cursor": "eyJpZCI6IjAxOTQ1YjM2LTQ1NjctNzAwMC04MDAwLTAwMDAwMDAwMDAwMCJ9",
  "has_more": true,
  "total_count": 142
}
```

When `next_cursor` is `null`, you have reached the last page. See [Pagination](/api/pagination) for a full walkthrough.

## Response format

All responses are JSON with `Content-Type: application/json`. Successful responses return the resource directly or a paginated wrapper object.

## Errors

The API returns standard HTTP status codes. Error bodies follow this schema:

```json theme={null}
{
  "error": "not_found",
  "message": "Policy with ID 01945b36-4567-7000-8000-000000000000 not found",
  "status_code": 404
}
```

| Status code | Error type       | Meaning                                   |
| ----------- | ---------------- | ----------------------------------------- |
| `400`       | `bad_request`    | Invalid request body or query parameters  |
| `401`       | `unauthorized`   | Missing, invalid, or expired access token |
| `403`       | `forbidden`      | Token lacks permission for this resource  |
| `404`       | `not_found`      | Resource does not exist                   |
| `429`       | `rate_limited`   | Rate limit exceeded — check `Retry-After` |
| `500`       | `internal_error` | Unexpected server error                   |

<Tip>
  Always check the `message` field for a human-readable explanation of what went wrong. It typically names the specific field or resource involved.
</Tip>

## Versioning

The current stable version is **`/v1`**, which is generally available (GA). Breaking changes will only be introduced in a new major version (`/v2`, etc.). Additive changes — new fields and new optional parameters — may be made to `/v1` at any time without notice.

<Note>
  Pin your integrations to `/v1` explicitly. The unversioned base URL `https://api.toktra.io` is not supported.
</Note>