API reference

Creates a normalized chat completion. The request body is JSON. Set stream to true for Server-Sent Events.

Request fields

LaneZero removes models before calling a provider and sends only that attempt's provider-local model name. For Anthropic and Google, strict is currently not forwarded. Assistant tool-call arguments must contain valid JSON for Anthropic and a JSON object for Google.

Provider-key passthrough headers

If neither matching header is present, LaneZero looks for that provider in the user's vault. Passthrough values are used for the current request and are not stored.

Request example

{
  "models": [
    "anthropic/claude-sonnet-4-6",
    "openai/gpt-4.1"
  ],
  "messages": [
    {"role": "user", "content": "What is the weather in Liverpool?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Read current weather",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto",
  "stream": false
}

Non-streaming response

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1720000000,
  "model": "openai/gpt-4.1",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Use soft tyres."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 4,
    "total_tokens": 16
  }
}

usage and system_fingerprint are omitted when the provider does not supply them. created is 0 for Anthropic and Google because those adapters do not receive a compatible creation timestamp.

Streaming response

The response uses Content-Type: text/event-stream and Cache-Control: no-cache. Each chunk is one data: event followed by a blank line. The final success chunk has empty choices and a usage object. LaneZero writes data: [DONE] immediately after that usage chunk.

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1720000000,"model":"openai/gpt-4.1","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1720000000,"model":"openai/gpt-4.1","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1720000000,"model":"openai/gpt-4.1","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1720000000,"model":"openai/gpt-4.1","choices":[],"usage":{"prompt_tokens":7,"completion_tokens":2,"total_tokens":9}}

data: [DONE]

Tool calls arrive in delta.tool_calls. Function argument text can be split across chunks. Z.ai and Mistral do not receive stream_options; if they omit usage, LaneZero synthesizes a final usage object containing zeros. For the other OpenAI-compatible adapters, LaneZero requests usage but does not synthesize it. If one of those providers ends with [DONE] and no usage chunk, the downstream response currently ends without a final usage chunk or its own [DONE].

A failure after the first downstream chunk cannot switch providers. The HTTP status is already 200. LaneZero sends event: error with the normal error JSON in data:, then sends data: [DONE].

Routing response headers

These three headers are added to every /v1/chat/completions response, including gateway authentication and JSON errors. Early failures use unknown, 0, and false.

Routing and fallback

The models array is evaluated from left to right. LaneZero makes at most three upstream calls.

• Fallback advances after provider 429, provider 5xx, a transport or upstream-protocol failure, or a request timeout.
• For streaming, fallback is allowed only before the first normalized chunk reaches the client. This includes a timeout waiting for response headers or the first upstream data. Once one chunk exists, later failures become SSE error events.
• Fallback does not advance after provider 400, 401, 403, or another non-429 4xx.
• A fallback entry without a passthrough or vaulted credential is skipped. The skip does not consume the three-call budget.
• An upstream Retry-After delay is honored only when it parses successfully and is no more than two seconds.

The implementation also classifies upstream 3xx responses as retryable upstream errors. Non-streaming timeouts can occur while waiting for the full response body, not only before the first byte.

Returns the embedded chat-model catalog, sorted by namespaced model ID. A gateway bearer key is required.

{
  "object": "list",
  "data": [
    {
      "id": "anthropic/claude-sonnet-4-6",
      "object": "model",
      "owned_by": "anthropic"
    }
  ]
}

The response does not include prices, context limits, or tool capabilities. See Models and providers for catalog details.

Public liveness response. The HTTP status and top-level status remain 200 and ok even when the database check is degraded.

Management API

Management routes use the signed browser session created by GitHub or Google OAuth. They do not accept a gateway bearer key as a substitute. Every POST, PUT, and DELETE also requires X-LaneZero-CSRF: 1. They return 503 when LaneZero runs without DATABASE_URL.

For privacy, usage-event records are retained for 90 days by default. Operators can change the window with RACEWAY_USAGE_RETENTION_DAYS; setting it to 0 disables automatic pruning. Account deletion anonymizes usage unless RACEWAY_DELETE_USAGE_ON_ACCOUNT_DELETE=true.

Error JSON

Gateway-generated errors use one envelope.

{
  "error": {
    "message": "model `openai/not-in-the-catalog` is not present in the catalog",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

See Errors and retries for triggers and caller guidance. Malformed management JSON or query extraction can be rejected by the web framework before this envelope is built.

Limits and spend caps

Rate limits are enforced per gateway key across the authenticated /v1 routes. The configured requests-per-second value is also the burst size. Exceeding it returns 429 with rate_limit_error.

Spend caps are advisory. They use estimated provider cost for the current calendar month. They never block a request. The current wire header is:

x-lz-spend-cap: true

x-lz-spend-cap appears after an authenticated /v1 request when the asynchronously refreshed estimate is greater than the configured cap.