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 or the web app. That part of Ambral has no public HTTP API: the
CLI’s command reference lists everything it does.
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.jsonhttps://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, which shows it once. It starts withak_live_.
Send it as a bearer token:
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.
<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-idheader. 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:
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, andGET /v1/models:
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.
Each endpoint’s page lists the other errors it answers.