# API Reference

> Authentication, request format, errors and endpoints for the Thoth runtime API, served from your unified tenant API base URL.

Source: https://docs.atensecurity.com/docs/api-reference

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

```http
X-API-Key: <your-runtime-api-key>
Content-Type: application/json
```

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` | `agent`
  - `scope_target_id` (required for fleet/endpoint/agent scopes)
  - `permissions`: any subset of `read`, `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

```json
{ "detail": "Invalid request body: expected an array of events or an object with an events array" }
```

---

## 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](https://docs.atensecurity.com/docs/api-reference/events).

## Available endpoints

| Method | Path | Purpose |
| ------ | ---- | ------- |
| `POST` | [`/v1/enforce`](https://docs.atensecurity.com/docs/api-reference/enforcement#check-a-tool-call) | Check a tool call against policy |
| `GET`  | [`/v1/enforce/hold/{hold_token}`](https://docs.atensecurity.com/docs/api-reference/enforcement#poll-a-step-up-hold) | Poll a step-up hold |
| `POST` | [`/v1/explain`](https://docs.atensecurity.com/docs/api-reference/explain#create-an-explanation) | Explain a decision in plain language |
| `GET`  | [`/v1/explain/{violation_id}`](https://docs.atensecurity.com/docs/api-reference/explain#retrieve-an-explanation) | Retrieve a stored explanation |
| `POST` | [`/v1/events/batch`](https://docs.atensecurity.com/docs/api-reference/events#send-a-batch-of-events) | 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](https://docs.atensecurity.com/docs/api-reference/enforcement), [Explain](https://docs.atensecurity.com/docs/api-reference/explain) and
[Events](https://docs.atensecurity.com/docs/api-reference/events) for each endpoint's parameters and examples.