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

EndpointWhat it does
POST /chat/completionsChat, routed and receipted. Chat Completions
POST /embeddingsOpenAI embedding models, metered on input tokens. Embeddings
POST /searchWeb search results, priced per search. Web search
GET /modelsThe catalog, with explicit chat, embedding and router capabilities. Models & providers

Paths are relative to https://www.lobstack.ai/api/gateway/v1.

OpenAI compatibility contractThe supported endpoints, parameter forwarding and drops, unsupported OpenAI features, and SDK/runtime floors.

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":

Response headershttp
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.716000

The 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.

ProviderCurrent modelsKeys in registry
AnthropicClaude Opus 5.5, Claude Fable 5.1, Claude Sonnet 5.5, Claude Haiku 5.59
OpenAIGPT-6 Astra, GPT-6 Sol, GPT-6.1 Sol, GPT-6 Luna12
GoogleGemini 4 Argon, Gemini 3.1 Pro, Gemini 3.8 Flash, Gemini 3.1 Flash Lite, Gemini 3.5 Flash Lite8
xAIGrok 4.7, Grok 4.6, Grok 4.5, Grok 4.3, Grok Build 0.17

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".

The rest of this section