API Reference
Authentication, request format, errors and endpoints for the Thoth runtime API, served from your unified tenant API base URL.
Connection and authentication
Use the unified tenant API base URL supplied for your environment. It serves
/v1/enforce, hold polling, and /v1/events/batch. It is separate from GovAPI,
which the configuration providers use. Do not derive the SDK endpoint from a
tenant ID or assume a global API host.
Runtime requests use an execute API key:
The enforcer also accepts a bearer credential for compatible callers. Do not infer permissions from a key's prefix; scope and permissions are validated server-side. Keep the runtime key separate from administrative credentials.
Key creation (control plane)
Create keys through the Thoth control-plane endpoint:
POST /:tenant-id/thoth/api-keys- Request fields:
name(optional)scope_level:organization|fleet|endpoint|agentscope_target_id(required for fleet/endpoint/agent scopes)permissions: any subset ofread,write,execute
The plaintext key is returned once at creation and is not retrievable afterward.
Key permissions
| Permission | Capabilities |
|---|---|
read | Read-only control-plane access |
write | Control-plane mutations |
execute | Runtime decisions, hold polling, and API-key fallback for event ingestion |
Request format
All endpoints accept and return application/json. Request bodies must include a Content-Type: application/json header.
Response codes
| Code | Meaning |
|---|---|
200 OK | Request succeeded (decision, hold poll, explanation) |
202 Accepted | Events queued for ingestion (POST /v1/events/batch) |
400 Bad Request | Malformed request body |
401 Unauthorized | Missing or invalid API key |
403 Forbidden | Valid key but insufficient scope |
404 Not Found | Resource not found (for example unknown hold token) |
422 Unprocessable Entity | Body failed schema validation (for example a missing required field) |
429 Too Many Requests | Rate limit exceeded (see Retry-After header) |
500 Internal Server Error | Transient server error — retry with exponential backoff |
503 Service Unavailable | Temporary backend/config dependency failure |
Error response body
Rate limits
Limits depend on the deployment and trial configuration. On 429, honor
Retry-After when supplied and use bounded backoff. Do not assume fixed global
request limits or that every response includes rate-limit headers.
Event ingestion can use a dedicated X-Thoth-Event-Ingest-Token when configured;
otherwise it falls back to runtime API-key validation. Batches must belong to
one tenant. See the Events API.
Available endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /v1/enforce | Check a tool call against policy |
GET | /v1/enforce/hold/{hold_token} | Poll a step-up hold |
POST | /v1/explain | Explain a decision in plain language |
GET | /v1/explain/{violation_id} | Retrieve a stored explanation |
POST | /v1/events/batch | Send behavioral events |
SDKs vs. direct API
Most users interact with Thoth exclusively through the language SDKs, which handle authentication, batching, retries, and error translation automatically. Use the raw API directly if you are:
- Building a custom SDK or integration
- Auditing events from a non-SDK source (e.g. a log aggregator)
- Implementing a step-up approval webhook
See Enforcement, Explain and Events for each endpoint's parameters and examples.