Gateway API
Gateway
One OpenAI-compatible endpoint in front of 4 model providers. The answer comes back in the shape you already parse; the routing decision and the price come back with it, in headers.
Chat completions is a single POST endpoint. It authenticates the caller, scores the request for complexity, picks a model, relays to that provider, prices the tokens the provider reports, and writes a ledger row and a trace row before it answers. What you get back is an OpenAI-shaped completion plus a set of x-lobstack-* headers describing every one of those decisions.
There is nothing to install. If your code already talks to the OpenAI Chat Completions API, point its base URL at Lobstack and change the key.
Endpoints
| Endpoint | What it does |
|---|---|
POST /chat/completions | Chat, routed and receipted. Chat Completions |
POST /embeddings | OpenAI embedding models, metered on input tokens. Embeddings |
POST /search | Web search results, priced per search. Web search |
GET /models | The catalog, with explicit chat, embedding and router capabilities. Models & providers |
Paths are relative to https://www.lobstack.ai/api/gateway/v1.
One request
curl https://www.lobstack.ai/api/gateway/v1/chat/completions \
-H "Authorization: Bearer $LOBSTACK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [{ "role": "user", "content": "What time zone is Lisbon in during summer?" }]
}'What comes back
The body is an OpenAI chat completion: choices[0].message.content, a finish_reason, and a usage block with prompt, completion and total tokens. The model field carries the Lobstack key that served the request, which is not necessarily the one you asked for.
The headers are the part you do not get elsewhere. This is the response to the request above, sent with "model": "auto":
x-lobstack-request-id: 8f2b1e0c-4d5a-4b91-9c3e-6a7f0d2b5c41
x-lobstack-model: gemini-3.1-flash-lite
x-lobstack-tier: nano
x-lobstack-complexity: 5
x-lobstack-savings-pct: 98
x-lobstack-routed: true
x-lobstack-mode: managed
x-lobstack-principal: api_key
x-lobstack-cost-usd: 0.000123
x-lobstack-savings-usd: 0.004014
x-lobstack-baseline-model: claude-fable-5-1
x-lobstack-baseline-reason: plan_ceiling
x-lobstack-baseline-usd: 0.004137
x-lobstack-priced: true
x-lobstack-metered: true
x-lobstack-quota-meter: spend
x-lobstack-quota-allowance-usd: 10.000000
x-lobstack-quota-spent-usd: 1.284000
x-lobstack-quota-remaining-usd: 8.716000The request said auto, so nobody named a model, and x-lobstack-baseline-reason says so: plan_ceiling means the saving is measured against the most expensive model this plan may reach — what the caller would have paid had they asked for the best one. That is a real comparison and it is not the same claim as named, which measures against a model the caller actually asked for. Read the reason before you render the figure. Every header is listed on Metering & cost.
x-lobstack-quota-meter names which allowance the counters beside it describe. A plan that includes dollars of model spend reports dollars and no request counters; the BYOK plan (no longer sold) and the older messages-per-month tiers report counts instead. The three meters are set out on Pricing & plans.
x-lobstack-request-id is allocated before anything can fail, so even a 401 comes back with one. It is the id of the trace row, which means quoting it in a support thread turns a description into a lookup.
The 4 providers
One credential reaches all of them. Lobstack holds the provider keys and routing can cross vendors freely. On a paid plan you can add your own key for any of them in Settings › Provider keys; a call to that provider then runs on your key, is not marked up, and does not spend the allowance.
| Provider | Current models | Keys in registry |
|---|---|---|
| Anthropic | Claude Opus 5.5, Claude Fable 5.1, Claude Sonnet 5.5, Claude Haiku 5.5 | 9 |
| OpenAI | GPT-6 Astra, GPT-6 Sol, GPT-6.1 Sol, GPT-6 Luna | 12 |
| Gemini 4 Argon, Gemini 3.1 Pro, Gemini 3.8 Flash, Gemini 3.1 Flash Lite, Gemini 3.5 Flash Lite | 8 | |
| xAI | Grok 4.7, Grok 4.6, Grok 4.5, Grok 4.3, Grok Build 0.1 | 7 |
The larger number counts previous-generation keys kept alive so stored configurations keep resolving. The full catalog, with prices and context windows, is on Models & providers.
When to send auto, and when to name a model
Send "auto" when the traffic is mixed and you care more about the bill than about which engine answers. The router scores each request 0–100 and takes the lowest tier that clears the score, bounded by your plan.
Name a model when the output has to be reproducible, when you are comparing engines, or when a downstream evaluation is pinned to one vendor. Naming a model serves that model. Ask for Opus 5 and a one-line greeting is still Opus 5. If the model is above your plan, unavailable, or not a chat model, the request is refused. x-lobstack-routed is false on that response, and true only when you sent "auto".