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
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
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 |
429 Too Many Requests response along with a Retry-After header indicating how many seconds to wait before retrying.
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. |
{
"items": [...],
"next_cursor": "eyJpZCI6IjAxOTQ1YjM2LTQ1NjctNzAwMC04MDAwLTAwMDAwMDAwMDAwMCJ9",
"has_more": true,
"total_count": 142
}
next_cursor is null, you have reached the last page. See Pagination for a full walkthrough.
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:
{
"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 |
Always check the message field for a human-readable explanation of what went wrong. It typically names the specific field or resource involved.
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.
Pin your integrations to /v1 explicitly. The unversioned base URL https://api.toktra.io is not supported.