Gateway

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.

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

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

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.

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.

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.

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 does not force it: it sets the ceiling. Ask for Opus 5 and send a one-line greeting and the request still goes to the nano tier. If you need a specific model on every request regardless of complexity, pin the model and read x-lobstack-routed to see when it was not used.