Quickstart: the API

From nothing to a metered response

1. 1

   Create an account

   lobstack.ai/signup takes a Google account, a GitHub account, or an email address. New accounts start on Free, which includes $1 of credit every week and routes no higher than the standard tier. 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.

2. 2

   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 inference and usage:read scopes by default. The Gateway rejects a key without inference with a 403.

   export LOBSTACK_API_KEY="lsk_live_..."

3. 3

   Send one request

   "auto" hands the choice to Nex, the router. You can name a chat model instead; GET /api/gateway/v1/models lists the Gateway catalog, including models that are only for embeddings.

   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": "Say hello." }]
     }'

   Keep the www — the apex eats your key

   Every base URL on this site is on www.lobstack.ai, and the www is load-bearing. The bare apex, lobstack.ai, redirects to it, and RFC 9110 requires a client to drop the Authorization header when a redirect crosses to a different host. Every client honours that: curl, requests, httpx — so the OpenAI SDK — Go, Java, PowerShell.

   So a request sent to the apex with a perfectly good key reaches the Gateway carrying no credential and comes back 401, reading like a key problem when it is a host problem. If a key you have only just minted returns 401, check the host before you check the key.

   The body that comes back is an ordinary OpenAI chat completion: choices[0].message.content, a usage block with prompt and completion tokens, and model set to the model that actually served you rather than the one you asked for.

4. 4

   Read the headers

   Re-run it with -D - to dump the response headers. This is the part that is not in the OpenAI shape.

   curl -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-id	The trace id. Quote it in any support request.
   x-lobstack-model	The model key that served the request.
   x-lobstack-tier	nano, small, standard, premium or flagship.
   x-lobstack-complexity	The 0–100 score the router assigned your prompt.
   x-lobstack-cost-usd	What these tokens cost, to six decimal places.
   x-lobstack-savings-usd	Dollars saved against the baseline model. Empty when there is no baseline.
   x-lobstack-baseline-reason	Why that baseline: “named” if you asked for it, “plan_ceiling” if you sent “auto”. Read it before you quote the saving.
   x-lobstack-quota-meter	Which allowance you are measured against: spend, requests or legacy.
   x-lobstack-priced	false 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.

5. 5

   Point an SDK at it

   Set the base URL to https://www.lobstack.ai/api/gateway/v1 and 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 need stream_options.include_usage, which the Gateway does not read.

   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 read response.headers. If you only want the cost, the usage block plus Console → Usage gets you there without touching headers at all.

6. 6

   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.

Where to go next