API quickstart

Base URL: https://YOUR-GATEWAY-HOST/v1. Authenticate with Authorization: Bearer gw_… (or x-api-key).

curl https://YOUR-GATEWAY-HOST/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_KEY" -H "content-type: application/json" \
  -d '{"model":"fast","messages":[{"role":"system","content":"Be brief."},{"role":"user","content":"Hi"}]}'

With an OpenAI SDK, set baseURL to the gateway's /v1 URL and apiKey to the gateway key.

Supported: model, messages (system/user/assistant, text content), max_tokens, temperature, top_p, stop, user, stream, stream_options.include_usage. Not yet: tools/function calling, images, n > 1.

Streaming

With "stream": true the gateway answers with text/event-stream in the OpenAI chat.completion.chunk format (a role delta, content deltas, a final chunk with finish_reason, then data: [DONE]), for every provider type: Anthropic streams are translated. Add "stream_options": {"include_usage": true} to get a last chunk with token usage.

Fallback works until the first content reaches your client. After that, a provider failure or a stall longer than your workspace timeout ends the stream with data: {"error":{...}} in the usual error shape (no [DONE]). Rate limits and plan limits are checked before the stream starts, so those errors are ordinary JSON responses. Usage is metered from the provider's usage events; if a provider sends none, tokens are estimated (about 4 characters per token) and the log entry says so. Closing the connection stops the provider request and is logged with status 499.

Errors use the OpenAI shape {"error":{"message","type","param","code"}}: 401 invalid key, 404 unknown model, 429 key rate limit (with retry-after), 402 plan limit, 502/504 when every target failed.

Responses include headers x-gateway-provider, x-gateway-upstream-model, x-gateway-attempts and x-gateway-request-id (matches the log entry).