HTTP API

The OpenAI-compatible surface of a self-hosted warpllm gateway.

The HTTP gateway has landed on main but is not part of a published release. To run it today you build it from source or from the Dockerfile in the repository root. Flags, endpoints, and the error envelope may still change before it ships.

This reference describes the HTTP surface of a gateway you run. There is no hosted warpllm API — see Run the gateway to start one.

Base URL

http://localhost:8080

That is the default bind (0.0.0.0:8080). Chat completions live under /v1, so an OpenAI client’s base URL is http://localhost:8080/v1.

Authentication

None, on this surface. The gateway ignores the caller’s Authorization header — it is never forwarded — and authenticates upstream with its own provider keys from the environment. Whatever key a client sends is unused.

Because there is no caller authentication, do not expose a gateway to a network you do not control.

Endpoints

Create a chat completion

POST /v1/chat/completions — whole or streamed.

Liveness check

GET /health — status and version.

Conventions

Model strings carry a provider prefix

openai/gpt-5-nano, not gpt-5-nano. The roster is closed — an unlisted name returns 400 rather than being forwarded to an upstream default. See Model routing.

Unmodeled request fields are forwarded

A field not in the request schema reaches the provider untouched rather than being rejected, so a provider parameter warpllm has not learned yet is still usable.

The response echoes your routing string

model in every response and every chunk is what you asked for, not the upstream’s own name.

Errors use the OpenAI envelope, plus extras

So an official SDK raises its own typed exception. warpllm adds origin, warpllm_code, provider, provider_status, and provider_code — additive fields a client can ignore. See Errors.

There is no /v1/models endpoint

The roster is compiled into the binary. The model roster page is generated from it.

Status codes

Status	Meaning
200	Success — one JSON body, or a text/event-stream
400	Malformed request, unlisted model, oversized prompt, or content filtered
401	No key for the routed provider, or the provider rejected it
403	Valid credential, not entitled
404	The provider does not serve that model
429	Rate limited or quota exhausted — read code
500	warpllm could not set itself up
502	The provider was never reached, answered unreadably, or ended a stream early
503	The provider is shedding load
504	The stream went silent past --stream-read-timeout-secs

502 covers the case OpenAI has no spelling for: a client talking to OpenAI directly never sees “the thing behind this gateway did not answer”.