--- title: Gateway API reference description: The Gateway's /v1 endpoints, how they authenticate, the request and response headers it adds, and the OpenAPI document that describes them. url: https://agentlab.cresclab.com/docs/en/gateway/api language: en updated: 2026-10-28 --- # Gateway API reference The Gateway's /v1 endpoints, how they authenticate, the request and response headers it adds, and the OpenAPI document that describes them. ## OpenAPI document The endpoints below are described in an OpenAPI 3.1 document, checked against the Gateway's routes on every build: ```text https://agentlab.cresclab.com/docs/openapi/gateway.json ``` Base URL: `https://api.agentlab.cresclab.com`. Error codes are listed in [Errors](https://agentlab.cresclab.com/docs/en/gateway/errors.md). ## Endpoints | Method and path | What it does | | --------------------------------------- | --------------------------------------------------------------------------------------------------- | | `POST /v1/chat/completions` | OpenAI Chat Completions, streaming or not, on any model the workspace allows. | | `POST /v1/messages` | Anthropic Messages, relayed to a Claude model as sent. | | `POST /v1/messages/count_tokens` | Anthropic token counting. Not metered. | | `POST /v1/responses` | OpenAI Responses, relayed to an OpenAI model as sent. | | `POST /v1/prompts/{prompt}/completions` | Call a prompt from the workspace's prompt library with its variables. Answered as Chat Completions. | | `GET /v1/models` | `auto` and the models this key may name, in the OpenAI or the Anthropic list shape. | | `GET /v1/gateway/readiness` | Whether this Gateway server is ready to serve. No key needed. | ## Authentication Send a Gateway key as `Authorization: Bearer `. Every endpoint except `/v1/chat/completions` also takes `x-api-key: `; if both are sent they must be the same key. Requests from a browser (with an `Origin` header) are refused. ## Request headers | Header | Where | Meaning | | ------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `X-AgentLab-Routing` | All inference endpoints | `auto`: let the Gateway choose the model even though the body names one. Must be exactly `auto`. | | `Idempotency-Key` | All inference endpoints, optional | 8 to 128 characters. The same key is never charged twice; reusing it for another request is refused. | | `X-AgentLab-Metadata` | All inference endpoints, optional | Tags for usage reports: one JSON object of at most 16 string values. See [tags](https://agentlab.cresclab.com/docs/en/gateway/usage.md#tags). | | `anthropic-version`, `anthropic-beta` | `/v1/messages` | Passed to the provider as sent. | ## Response headers | Header | Meaning | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `X-Request-Id` | The request's id, the same as `request_id` on the usage page and in the export. | | `X-Agentlab-Model` | The model that answered. | | `X-Agentlab-Decision` | `requested_model`, or how `auto` decided. See [auto](https://agentlab.cresclab.com/docs/en/gateway/auto.md#headers). | | `X-Agentlab-Assessment` | With `auto`, the judgement of the task, such as `analysis/multi_step`. | | `X-Agentlab-Prompt` | On a prompt call, the prompt version that answered, `@`. | | `Retry-After`, `X-Should-Retry` | On refusals, whether and when to retry. See [the three kinds of 429](https://agentlab.cresclab.com/docs/en/gateway/limits.md#429). | ## Chat Completions The body is an OpenAI Chat Completions request. `model` is `auto` or a name from `GET /v1/models`. The response's `model` is the model that answered, and `agentlab_decision.reason` is `auto` or `requested_model`. With `stream_options.include_usage`, the last streamed chunk carries the usage. An optional `agentlab` object states what the request needs, so `auto` only picks a model that has it: `{"schema_version": 1, "tool_calling": true, "vision": false, "structured_output": false, "minimum_context_tokens": 0}`. ## Prompts Owners and admins keep the workspace's prompts on the Gateway's Prompts tab: messages with `{{variables}}`, an optional model (or `auto`) and parameters. Every save is a new version, and one version is published. The call copies Portkey's prompt API: ```bash curl https:///v1/prompts/support-reply/completions \ -H "Authorization: Bearer $AGENTLAB_API_KEY" -H "Content-Type: application/json" \ -d '{"variables": {"company": "Acme", "question": "When does order 1042 ship?"}}' ``` - Name the prompt by its slug or id. Add `@`, such as `support-reply@3`, to pin a version; otherwise the published version answers. - `variables` must name exactly the prompt's variables, each a string. A missing or extra one is refused with `prompt_variables_mismatch` before anything is sent. - Any other Chat Completions member, such as `model`, `stream` or `user`, overrides what the prompt sets. `messages` is refused: the prompt holds them. - The answer is a Chat Completions answer, through the same key, limits, `auto` and usage. The usage page splits requests by prompt, and each request shows its prompt and version. The variables you send are not stored. ## Messages and Responses These two are relayed to the provider as sent, apart from `model`, which becomes the model the Gateway chose. Usage, fast mode, regional inference, service tiers, one-hour cache writes, web search and code-execution time are measured from the provider's own report and priced from the catalog. A few members are refused because they would read or run something the Gateway cannot attribute to your workspace: - Messages: `fallbacks` and advisor tools, which run a second model inside one call. - Responses: `previous_response_id`, `conversation`, `prompt` and item references, which read state stored under the provider's account; the `file_search` and `image_generation` tools. The Gateway sends `store: false`, so the provider does not keep the response for later retrieval.