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.

Last updated 2026-10-28

View Markdown Open in Claude Open in ChatGPT

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.

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 <key>. Every endpoint except /v1/chat/completions also takes x-api-key: <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.
`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.
`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, `<prompt id>@<version>`.
`Retry-After`, `X-Should-Retry`	On refusals, whether and when to retry. See the three kinds of 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://<gateway>/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 @<version>, 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.