LobstackGateway API
OpenAI compatibility contract
What the Gateway accepts and what it does not. Contract version 2026-10-25.
Endpoint matrix
| Path | Kind | Status | Contract |
|---|---|---|---|
POST /chat/completions | OpenAI-shaped | Supported | Routed chat completions, including tool calls and SSE streaming. |
POST /embeddings | OpenAI-shaped | Supported | OpenAI embeddings for the two listed embedding models. |
GET /models | OpenAI-shaped | Supported | Model discovery with Lobstack capability and pricing extensions. |
POST /route-preview | Gateway extension | Supported | Unauthenticated routing preview; it does not call a provider or spend tokens. |
POST /search | Gateway extension | Supported | Lobstack web search, priced per search rather than an OpenAI operation. |
POST /runs/{id}/finish | Gateway extension | Supported | Marks a tagged Gateway run complete. |
The OpenAI-shaped surface is POST /chat/completions,POST /embeddings and GET /models./route-preview, /search and/runs/{id}/finish are Lobstack extensions, not OpenAI endpoints. The extensions use the same base URL but are not expected to work with an unmodified OpenAI resource client. Methods not listed in the matrix are outside the contract (the route returns 405), and other /v1/* resources are not implemented.
Unsupported OpenAI features
| Feature | Result |
|---|---|
POST /responses | Not implemented; do not build an integration around it. |
POST /completions (legacy text completions) | Not implemented; do not build an integration around it. |
POST /moderations | Not implemented; do not build an integration around it. |
POST /images/generations | Not implemented; do not build an integration around it. |
POST /audio/speech | Not implemented; do not build an integration around it. |
POST /audio/transcriptions | Not implemented; do not build an integration around it. |
POST /assistants | Not implemented; do not build an integration around it. |
POST /threads and /runs | Not implemented; do not build an integration around it. |
POST /files | Not implemented; do not build an integration around it. |
POST /batches | Not implemented; do not build an integration around it. |
POST /fine_tuning/jobs | Not implemented; do not build an integration around it. |
Idempotency-Key request replay semantics | Not implemented; do not build an integration around it. |
Parameter contract
Core fields are model, messages,stream, max_tokens,temperature and tools. They are validated and then forwarded or translated according to the serving model; reasoning models receive max_completion_tokens instead ofmax_tokens. Optional fields are listed below.
| Field | Accepted validation | Provider behavior | Drop header |
|---|---|---|---|
user | string, at most 256 characters | Caller value is never forwarded; the Gateway supplies an HMAC identity to OpenAI. | x-lobstack-dropped-params |
response_format | object with a string type | Forwarded to OpenAI-compatible providers; dropped for Anthropic. | x-lobstack-dropped-params |
tool_choice | string or object | Forwarded with tools; translated to Anthropic auto/none/any/tool with tools. | x-lobstack-dropped-params |
parallel_tool_calls | boolean | Only meaningful with tools; OpenAI-compatible non-OpenAI providers drop it. | x-lobstack-dropped-params |
top_p | finite number from 0 to 1 | Dropped for reasoning models and for Anthropic models that reject sampling controls. | x-lobstack-dropped-params |
stop | string or an array of at most 4 strings | Sent as stop_sequences to Anthropic; dropped for reasoning models. | x-lobstack-dropped-params |
seed | integer | Forwarded only to OpenAI; dropped elsewhere. | x-lobstack-dropped-params |
presence_penalty | finite number from -2 to 2 | Forwarded only to non-reasoning OpenAI models. | x-lobstack-dropped-params |
frequency_penalty | finite number from -2 to 2 | Forwarded only to non-reasoning OpenAI models. | x-lobstack-dropped-params |
A valid field that cannot reach the selected provider is not silently lost: its name is included in x-lobstack-dropped-params. The caller'suser value is validated and reported as dropped; it is never forwarded. The provider receives a Gateway-generated HMAC identity instead.
Accepted by some SDKs, ignored by the Gateway
| Field | Behavior |
|---|---|
n | Accepted in the JSON body but not sent upstream; no dropped-parameter header is emitted. |
logprobs | Accepted in the JSON body but not sent upstream; no dropped-parameter header is emitted. |
top_logprobs | Accepted in the JSON body but not sent upstream; no dropped-parameter header is emitted. |
stream_options.include_usage | Accepted in the JSON body but not sent upstream; no dropped-parameter header is emitted. |
metadata (client and run fields are Gateway-only; none are forwarded) | Accepted in the JSON body but not sent upstream; no dropped-parameter header is emitted. |
Unknown JSON properties follow the same ignored-field rule. Malformed values for fields the Gateway reads return HTTP 400 with error_code: INVALID_PARAMETER. The Gateway does not accept an idempotency key or promise safe replay after a client retry.
Routing and model selection
auto delegates to Nex and routes within the plan ceiling. A named chat model is served exactly: response.model and x-lobstack-model are that model, including when the prompt is trivial. If it is above the plan, unavailable, or not a chat model, the request is refused. A row in GET /models means the deployment lists that model; naming it is the request for it. Embeddings are exact as well: the default or a named embedding model is never routed through Nex, and naming an embedding model on chat completions is refused. See the Nex routing documentation and model capability documentation.
SDKs and runtimes
| Ecosystem | Client and versions | Runtime | Notes |
|---|---|---|---|
| TypeScript / JavaScript | openai — 4.x and later Chat Completions clients | Node.js 18+ (or a runtime with fetch, Headers and ReadableStream) | Use baseURL ending in /api/gateway/v1; read receipt headers with withResponse(). |
| Python | openai — 1.x and later Chat Completions clients | Python 3.9+ | Use base_url ending in /api/gateway/v1; streamed usage is in the final chunk. |
| Raw HTTP | curl, requests, httpx, Go, Java, PowerShell, or equivalent — Any client that supports JSON POST and Server-Sent Events | Any runtime with TLS and HTTP/1.1+ | No Lobstack package is required. |
These are protocol floors, not bundled dependencies. A later SDK release is compatible when it still uses the documented Chat Completions resources and does not require an unsupported OpenAI feature. Frameworks that wrap an OpenAI client inherit this same contract, including the limitation that wrappers may hide receipt headers.