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

> ## Agent Instructions
> To set Ambral up in a project, run `npx ambral@latest skill install` in the project's root. It installs Ambral's skill, matched to the CLI's version, and the skill says how to do everything these pages describe with the `ambral` CLI. Prefer it to working from these pages. Never ask anyone for an Ambral API key, and never handle one: the person creates it in the web app and stores it where their app reads its secrets.

# API overview

> Ambral's two HTTP APIs: the hosts that serve them, the key they take, the x-ambral-eval header, rate limits and errors.

> [!NOTE]
>
> These two APIs are only where your inference routes and how your offline evals report results. Everything else, such as setting up workloads and their models, building tasksets,
> scoring, running shadow evals and reading their results and traces, you do with the
> [`ambral` CLI](https://docs.ambral.ai/cli/index) or the [web app](https://app.ambral.ai). That part of Ambral has no public HTTP API: the
> CLI's [command reference](https://docs.ambral.ai/cli/reference/global-flags.md) lists everything it does.

Ambral has two HTTP APIs, on two hosts. Both take the same key.

| API | Host | What calls it |
| - | - | - |
| Gateway | `https://api.ambral.ai` | Your agent's model client. It serves OpenAI's Chat Completions API and Anthropic's Messages API under `/v1`. |
| Report API | `https://app.ambral.ai` | Your eval suite, through Ambral's SDKs. It opens an offline run, takes reports of its scenarios and closes it, under `/api/report/v1`. |

Point an OpenAI client at the base URL `https://api.ambral.ai/v1`, and Anthropic's SDK at `https://api.ambral.ai`.

Each API serves its OpenAPI document, which needs no key:

* `https://api.ambral.ai/v1/openapi.json`
* `https://app.ambral.ai/api/report/v1/openapi.json`

## The key

Every request carries an Ambral API key, which belongs to one org. You create it on the **API keys** page of the
[web app](https://app.ambral.ai), which shows it once. It starts with `ak_live_`.

Send it as a bearer token:

```text theme={null}
Authorization: Bearer ak_live_…
```

`POST /v1/messages` also takes the key alone in the `x-api-key` header, when no bearer is sent, since
Anthropic's SDK and Claude Code send their key there. Every other endpoint takes it only as a bearer.

A request with no key, or with one that isn't a live key of an active org, is answered 401.

## The `x-ambral-eval` header

A Gateway request that carries `x-ambral-eval` is a model call of an offline run. It is recorded as an eval trace
of that run, never as production traffic.

```text theme={null}
x-ambral-eval: <run>; workload=<workload>; model=<model>
```

`<run>` is the id that opening an offline run answers, `<workload>` the workload the run was opened on, and
`<model>` the model the run serves. Ambral's SDKs set the header for you.

* A request that names no workload is for the run's workload.
* A request for the run's workload is served the run's model. A request for another workload is served that
  workload's primary model.
* The request must name its session too, with the `x-session-id` header. Without a session it is answered 400.
* A value that doesn't parse is answered 400.

## Rate limits

The Report API limits how many requests it takes:

| Counted by | Limit |
| - | - |
| Org | About 600 requests in 10 seconds |
| IP address | About 300 requests in 10 seconds |

The counts are approximate, and each is kept per location your requests reach Ambral through.

A request past a limit is answered 429 with a `TooManyAttempts` body. Its `retryAfter` is the number of seconds to
wait, the same as the response's `Retry-After` header. Nothing was stored, so send the same request again after the
wait. Ambral's SDKs do this themselves.

The Report API also refuses a request whose body is larger than 8 MiB, with 413.

On the Gateway, a 429 means the model's provider is limiting the rate of requests.

## Errors

The two APIs answer errors in different shapes.

### Gateway

Each of the Gateway's APIs answers every error in the envelope of the API it serves, so its SDKs read the message
as they would the provider's.

Chat Completions, and `GET /v1/models`:

```json theme={null}
{ "error": { "message": "…", "type": "…", "code": "…" } }
```

Messages:

```json theme={null}
{ "type": "error", "error": { "type": "…", "message": "…", "code": "…" }, "request_id": "…" }
```

| Status | Meaning |
| - | - |
| 400 | The request is invalid: its body, a header, the workload it names, or a model other than `ambral/auto`. |
| 401 | No key, or one that isn't a live key of an active org. |
| 402 | The org has no credits available. |
| 404 | No workload has the name the request gives. |
| 429 | The provider is limiting the rate of requests. |
| 502 | The provider couldn't be reached. Retry the request. |
| 503 | The key, or the route of the workload the request names, couldn't be read. Retry the request. |

An error the provider answers reaches your client with the provider's status, in the same envelope.

A streamed answer can fail after its 200. Chat Completions then sends a chunk whose `error` says what failed, or
the error envelope itself as an event when Ambral couldn't read the provider's event. Messages sends an `error`
event, which holds its envelope.

### Report API

Each error is a JSON object whose `_tag` names it. Some carry more fields, such as `retryAfter` on
`TooManyAttempts`.

```json theme={null}
{ "_tag": "TooManyAttempts", "message": "…", "retryAfter": 10 }
```

| Status | Meaning |
| - | - |
| 401 | `Unauthorized`: no key, or one that isn't a live key of an active org. |
| 413 | `OfflineRequestTooLarge`: the body is larger than 8 MiB. |
| 429 | `TooManyAttempts`: a rate limit refused the request. |
| 503 | `ServiceUnavailable`: Ambral couldn't complete the request. Retry it. |

Each endpoint's page lists the other errors it answers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.