Gateway API
Concepts
Eleven terms the rest of these pages use without stopping to define them. One short section each.
Most of Lobstack is one request path: a credential arrives, it resolves to a context, the context bounds which models the router may reach, the router picks one, a provider answers, and a trace row is written; successful metered calls also write a ledger row. Everything below is a name for a step in that sentence.
API keys and scopes
A Lobstack key is lsk_<env>_<selector><secret>: an environment marker (live or test), eight hex characters of selector, and forty-eight hex characters of secret. The selector is not secret. It is stored as the key's prefix and is what makes a key identifiable in a list or a log line after issue.
What the database holds is the SHA-256 of the whole key and nothing else. Verification is one indexed read on the prefix followed by a constant-time hash comparison. A key you have lost cannot be recovered, only revoked and replaced.
| Scope | Grants |
|---|---|
inference | Calling Gateway inference endpoints, including chat completions, embeddings and web search. |
usage:read | Reading the usage and cost API. |
agents:read | Vestigial. See Legacy, below. |
agents:write | Vestigial. See Legacy, below. |
Absence of a scope is a denial. Standard org keys get inference and usage:read by default; client-bound keys get only inference. A key may optionally expire; that is set at creation and cannot be added later.
The Gateway request path
The primary chat endpoint is POST /api/gateway/v1/chat/completions. Its request id is allocated before authentication, so even a rejected request has an id you can quote back. Embeddings and web search share authentication, quota and receipt behavior, but do not use this chat-routing path. The lifecycle below describes a request that reaches model selection; authentication, rate-limit, quota and validation failures stop earlier.
1 authenticate → a context: org, plan tier, mode, principal
2 check quota → against one of three meters; enforced for every credential
3 select model → complexity score, tool floor, tier, then a model in that tier
4 relay → buffered, or streamed as SSE
5 write records → a trace row for every attempt; a priced ledger row when usage is metered
6 respond → OpenAI JSON + x-lobstack-* headersEvery attempt gets a trace row carrying its status and error class, including failures before a provider call. A priced ledger row is written only when the request reaches the metering path; early authentication, rate-limit, quota and validation failures have no token ledger row. Use the trace table for complete error-rate accounting.
Model keys and provider model ids
You address models by a Lobstack model key, such as claude-sonnet-5 or gemini-3.1-pro. Each key maps to a provider and to that provider's own model id, which is often different: gemini-3.1-pro sends gemini-3.1-pro-preview, gpt-5.6 sends gpt-5.6-sol.
Some keys are aliases that deliberately point somewhere else: an older key resolves to the model that replaced it, so grok-3 is served by grok-4.3 and a configuration that still names it keeps working. The registry holds 36 keys in all — 18 you can ask for today across 4 providers, and 18 previous-generation keys retained for compatibility with older configurations. Those keys are still listed and can be named explicitly, but new integrations should choose from the current-generation lineup. A separate table of non-canonical spellings resolves onto those, and resolves for pricing as well as for routing. Every one carries a price per million tokens, and every one comes from a US model company.
Tiers and complexity
Every prompt is scored 0–100 by a heuristic that looks at length, code fences, multi-step phrasing, analysis verbs and conversation depth. The score selects a tier, and the tier selects a model. A request with tools asks for a standard tier floor: tool definitions do not raise the score, but they keep the request off a tier that is too weak for dependable function calling. The floor cannot exceed the plan ceiling, so a plan capped below standard keeps its existing cap.
| Tier | Handles complexity up to | First choice on “auto” |
|---|---|---|
| nano | 20 | gemini-3.1-flash-lite |
| small | 40 | claude-haiku-5-5 |
| standard | 70 | claude-sonnet-5-5 |
| premium | 90 | gemini-3.1-pro |
| flagship | 100 | claude-opus-5-5 |
Plan ceilings
A ceiling is the highest tier an auto request may reach. The plan sets it: Free is capped at standard, and every paid plan reaches flagship. Naming a model does not lower a routing ceiling; it selects that exact catalog model.
The effective ceiling applies only to auto. A hard prompt onFree does not get a flagship model; it gets the best standardmodel and a tier header that says so. An exact model above that ceiling is refused rather than silently downgraded.
Subscriptions bought on the older messages-per-month tiers keep their own ceilings, which are held in a separate table and are not being migrated.
Plans, allowances and meters
A plan buys access, a ceiling, and an allowance. The allowance is denominated in dollars of model spend on every plan on sale, priced at the same rates every response reports. A message was never a unit of cost: the same word covered a forty-token ping and a two-hundred-thousand-token context, so an allowance denominated in messages bounded nothing.
| Meter | Who is on it | The unit |
|---|---|---|
spend | Every plan that includes model spend | Dollars, at Lobstack rates |
requests | The BYOK plan, no longer sold | Requests per calendar month |
legacy | Subscriptions on the older messages tiers | Messages, counted as they always were |
Successful, authenticated inference responses name the meter they were measured against in x-lobstack-quota-meter, because the counters mean different things on each. Early error responses guarantee the request id, but may not include quota headers. The plans themselves, and what each includes, are on Pricing & plans.
Metering, and the two prices
Each round writes a ledger row that carries its own arithmetic: token counts, the per-million prices that were in force at the time, and the resulting cost. Prices are frozen into the row, so editing the catalog later cannot move a historical invoice. A model missing from the catalog is priced as null, never as zero, and the response says so via x-lobstack-priced: false.
A request has two costs and they are not the same number. cost_usd is what the customer owes. Included paid-plan usage and Free-trial usage are charged at the provider's list price; managed usage after the included allowance is priced at 1.5 times list price. Calls that ran on your own provider key are pass-through, because you already paid your provider. provider_cost_usd is what we paid and is recorded on the row; it is also exposed as x-lobstack-provider-cost-usd on buffered responses and as provider_cost_usd in the final streamedx_lobstack frame.
The baseline, and why it has a reason
A baseline is the model a saving is measured against, and it always arrives with baseline_reason saying why that model was chosen. named is the legacy reason retained for historical rows where a named request was routed away; new exact named requests have no baseline or saving. plan_ceiling means you sent "auto" and named nothing, so the comparison is against the most expensive model your plan may reach.
Both are real subtractions between two real prices, and they are not the same claim. A plan-ceiling comparison is also the most flattering one available to us, which is exactly why it is labelled. Where neither applies the baseline is null and no saving is reported.
Principals
The principal is which door a caller came through. It is recorded on every trace row, because "which credential caused this spend" is the first question anyone asks when a bill moves.
| Principal | Credential | Notes |
|---|---|---|
api_key | Authorization: Bearer lsk_… | Org-owned, scoped, revocable. Quota is enforced. |
An unbound key is org-level: managed mode, the org's plan tier, and no agent on the usage row. Every key minted today is this kind.
Allowances are enforced for every credential. API keys are the supported way for a new caller to reach the Gateway.
Modes
The mode says who paid the provider. It is on every ledger row and in x-lobstack-mode.
| Mode | Whose provider key | Effect on routing |
|---|---|---|
managed | Lobstack's | Routes freely across providers, restricted to those whose key is actually configured. |
byok | Yours, added in Settings › Provider keys on a paid plan | Adds that provider to what the router can reach. Your key is sent only to the provider that issued it. |
An organization provider key joins the routing pool; it does not make every request BYOK. With auto, Nex may select a managed provider or one of the organization's providers for each request. If it selects your provider, the call switches to byok: the prompt is sent only with your key, the call is pass-through priced, and it does not consume the managed allowance. Check x-lobstack-mode and x-lobstack-model if the billing path matters to your application.
Once a managed allowance is exhausted, routing narrows to your usable provider keys; if none are available, the Gateway returns 402. Naming a model from another provider does not bypass that limit.
The Gateway first works out which providers a key exists for — Lobstack's, plus any your organization added — and routes only among those. The mode is then set per call by whose key the chosen provider runs on. Without that check, "auto" could select an unkeyed provider and every request would fail with a 503 raised one layer too late.
Legacy
Hosted agent VMs, runtime credentials, agent bindings and direct execution are retired. Historical fields remain for compatibility and interpreting old traces; they are not part of current Gateway development. See the legacy agent and VM migration reference for the complete migration notes.