Start here
Quickstart: the API
One account, one key, one request. At the end you will have a metered response and an OpenAI SDK pointed at the Gateway.
Want the desktop app instead? Start with Quickstart: the app.
The Gateway speaks the OpenAI Chat Completions format. For a basic chat request, an existing OpenAI client needs a new base URL and key. Model-specific request options can vary by provider; the Chat Completions page says which options are forwarded and how to see any that were dropped.
From nothing to a metered response
Create an account
lobstack.ai/signup/gateway takes a Google account, a GitHub account, or an email address. New accounts start on Free. A verified API or app sign-in adds $5 of Gateway credit for 30 days, once, and Free routes no higher than the
standardtier. No card, and nothing is provisioned: a plan is a key and an allowance, and nothing of yours runs anywhere.The email option sends a one-time link. It is an OTP link rather than a PKCE one, which means it verifies in whatever browser you open it in — including the in-app browser your mail client opens it in, which a PKCE link cannot do because the verifier it needs never left the browser that asked for the link.
Mint a key in the Console
Open Console → API Keys and create a key. Keys look like
lsk_live_a1b2c3d4…: a nine-character environment marker, an eight-character selector, and forty-eight characters of secret. The full string is shown once, at creation, and cannot be recovered afterwards, because only its SHA-256 hash is stored.A new key carries the
inferenceandusage:readscopes by default. The Gateway rejects a key withoutinferencewith a 403.export LOBSTACK_API_KEY="lsk_live_..."Send one request
"auto"hands the choice to Nex, the router. You can name a chat model instead;GET /api/gateway/v1/modelslists the Gateway catalog. Choose an entry whosecapabilitiesincludes"chat"; entries with only"embedding"are for/embeddings. A named chat model is exact and is never silently replaced. Send"auto"when you want Nex to route by complexity and plan ceiling.POST /api/gateway/v1/chat/completionsbashcurl 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": "Say hello." }] }'The body that comes back is an ordinary OpenAI chat completion:
choices[0].message.content, ausageblock with prompt and completion tokens, andmodelset to the model that served you. It matches a named model exactly; with"auto"it reports Nex's choice.Successful response (abridged)json{ "object": "chat.completion", "model": "gemini-3.1-flash-lite", "choices": [{ "message": { "role": "assistant", "content": "Hello!" } }], "usage": { "prompt_tokens": 12, "completion_tokens": 3, "total_tokens": 15 } }Read the headers
Re-run it with
-D -to dump the response headers. This is the part that is not in the OpenAI shape.Same request, headers printedbashcurl -sS -D - -o /dev/null \ 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":"Say hello."}]}'Header What it says x-lobstack-request-idThe trace id. Quote it in any support request. x-lobstack-modelThe model key that served the request. x-lobstack-tiernano, small, standard, premium or flagship. x-lobstack-complexityThe 0–100 score the router assigned your prompt. x-lobstack-cost-usdWhat these tokens cost, to six decimal places. x-lobstack-provider-cost-usdThe provider's list-price cost for these tokens. x-lobstack-savings-usdDollars saved against the baseline model. Empty when there is no baseline. x-lobstack-baseline-reasonWhy that baseline: “named” if you asked for it, “plan_ceiling” if you sent “auto”. Read it before you quote the saving. x-lobstack-quota-meterWhich allowance you are measured against: spend, requests or legacy. x-lobstack-pricedfalse when the served model is missing from the price catalog. The full list, including the rest of the quota headers and
x-lobstack-dropped-params, is on Metering & cost. On a streamed response the cost headers are absent and the same figures arrive on the final SSE chunk instead.Point an SDK at it
Set the base URL to
https://www.lobstack.ai/api/gateway/v1and the key to your Lobstack key. That is all a basic Chat Completions request needs. Streaming and tool calls work, while model-specific options can be dropped when the serving provider does not accept them. The trailing usage chunk is sent unconditionally — you do not needstream_options.include_usage, which the Gateway does not read.If you are starting from a blank project, install the client first:
npm install openaifor TypeScript/JavaScript orpip install openaifor Python.import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.LOBSTACK_API_KEY, baseURL: "https://www.lobstack.ai/api/gateway/v1", }); const res = await client.chat.completions.create({ model: "auto", messages: [{ role: "user", content: "Say hello." }], }); console.log(res.choices[0].message.content);SDKs put the response headers behind a raw-response accessor rather than on the parsed object. In the TypeScript client, call
.withResponse()on the promise and readresponse.headers. If you only want the cost, the usage block plus Console → Usage gets you there without touching headers at all.Find the request again
Every request writes a trace row keyed by the id in
x-lobstack-request-id, including the ones that failed before they reached a provider. Open Console → Logs, find the row and expand it: the model, the provider, the latency, the token counts and the priced cost for that exact call are all on the trace, with the request id at the top of it.