Chat completions (unified compat endpoint)

Note

The endpoint requires a gateway token in the Authorization: Bearer <token> header while auth_required: true is set on the gateway. That is the default.

Send the request as POST to the path /v1/{tenant}/{gateway}/compat/chat/completions.

Description

Send a chat completion request to the gateway. The gateway resolves the provider automatically from the model name using prefix matching, with OpenRouter as the catch-all fallback. Always returns an OpenAI-shaped response regardless of which provider handled the request. Existing clients using the OpenAI SDK can switch to this endpoint by changing only the base_url — no other code changes are required.

Request

The following parameters are available:

Parameter	In	Type	Required	Description
tenant	path	string	yes	Tenant slug (from the tenant's slug field).
gateway	path	string	yes	Gateway slug (from the gateway's slug field).
x-aig-byok-alias	header	string	no	Selects which stored BYOK key to use for this request. Defaults to default. Use when you have stored multiple keys for the same provider under different aliases.
x-aig-extensions	header	string	no	Opts a STREAMING request into the gateway's aig_* SSE side channel (thinking, tool telemetry, sources, PII/tool notices). Accepted values: 1, true, yes, on, matched exactly. Deliberately not an enum: any other value — including 0 and an empty value — is legal to send and is treated as absent, and the response is then a pure OpenAI stream (chat.completion.chunk frames, an optional error frame, and [DONE]). Implied by a valid x-aig-turn-id.
x-aig-meta-*	header	string	no	Custom metadata attached to this request. Any header matching x-aig-meta-{key} is captured in the log entry and can be used as a routing rule condition via {"field": "meta.{key}", "op": "eq", "value": "..."}.
x-aig-collect-log-payload	header	string	no	Set to false to suppress storing the request and response body text in the log for this specific request. Useful for requests containing sensitive data that should not be logged even when log_payloads: true is configured on the gateway.

Example

Example of the request body:

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": {},
      "name": "string",
      "tool_calls": [
        {}
      ]
    }
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 1024,
  "top_p": 0.0,
  "n": 1,
  "stop": {},
  "tools": [
    {}
  ],
  "tool_choice": {},
  "response_format": {
    "type": "text"
  },
  "user": "string",
  "metadata": {}
}

Responses

The endpoint answers the request with the following status codes:

Status code	Description
200	Chat completion response (or SSE stream when stream=true).
400	Request blocked by guardrail or invalid request.
401	Missing or invalid auth token.
403	Token valid but lacks permission, or IP not in allowlist.
424	provider_key_missing — the selected model routes to a provider that requires an API key, but no key is stored for this gateway (and alias). An admin must add a provider key. Returned before any upstream call.
429	Rate limit or budget quota exceeded.
502	Upstream provider error (all retries and fallbacks exhausted).