Passthrough

Passthrough endpoints.

This page is GENERATED from the OpenAPI spec (openapi.yaml) — it can never drift from the served API. Set UR_BASE_URL (required: your gateway’s URL) and UR_API_KEY (an ur_sk_* key); secrets are always the $UR_API_KEY placeholder.

Create a response (OpenAI Responses API passthrough)

POST /v1/responses

Native passthrough for the OpenAI Responses API: point the official openai SDK at ultrarouter by changing only the base URL and the key. The JSON body is FORWARDED VERBATIM to OpenAI (no routing, no compression, no model remapping, no field injection) and the response is returned UNTOUCHED — the gateway only meters, caps and captures. stream:true forwards the upstream SSE bytes verbatim. The ur extensions ride request headers (X-UR-Call-Type, X-UR-Timeout-Ms clamped 1 s–600 s (default 300 s), X-UR-Trace); the response carries X-UR-Request-Id and (non-streaming) X-UR-Cost-Micro-USD. An allowlist of request headers (openai-beta, openai-organization, openai-project, idempotency-key) is forwarded upstream; the caller's own Authorization is never forwarded. Upstream errors pass through with their status and body; gateway failures (auth, caps, timeout) use the normalized error envelope. EXPERIMENT-BOUND calls: a call carrying X-UR-Experiment-Execution (an execution enrolled on POST /v1/flywheel/experiments/{id}/executions; the key also needs flywheel:experiment:run) is authorized against its execution, reserved against the experiment budget before dispatch and settled from the measured cost; it must send max_output_tokens, a call type and an attempt in X-UR-Trace. The learned pack is never placed into a Responses body (a treated lever-stage call here is refused by name). A call without the header is unaffected. Requires API-key scope: gateway:invoke.

Auth: API key (Authorization: Bearer ur_sk_…).

curl -sS -X POST "$UR_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $UR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "string"
  }'

Create a message (Anthropic Messages API passthrough)

POST /v1/messages

Native passthrough for the Anthropic Messages API: point the official @anthropic-ai/sdk at ultrarouter by changing only the base URL and the key. The ur key is accepted via Authorization: Bearer OR x-api-key (the Anthropic SDK style); the body is FORWARDED VERBATIM to Anthropic and the response is returned UNTOUCHED — the gateway only meters, caps and captures. stream:true forwards the upstream SSE bytes verbatim. The ur extensions ride request headers (X-UR-Call-Type, X-UR-Timeout-Ms clamped 1 s–600 s (default 300 s), X-UR-Trace); the response carries X-UR-Request-Id and (non-streaming) X-UR-Cost-Micro-USD. An allowlist of request headers (anthropic-version, anthropic-beta, idempotency-key) is forwarded upstream; the caller's own key headers are never forwarded. Upstream errors pass through with their status and body; gateway failures (auth, caps, timeout) use the normalized error envelope. EXPERIMENT-BOUND calls: a call carrying X-UR-Experiment-Execution (an execution enrolled on POST /v1/flywheel/experiments/{id}/executions; the key also needs flywheel:experiment:run) is authorized against its execution (workspace, live experiment, open phase, bound candidate) BEFORE dispatch, reserved against the experiment budget from max_tokens and the dispatched bytes, claimed once (a retry of the same attempt is refused) and settled from the measured cost. For the TREATED arm’s lever call type only, the frozen learned pack is placed as a NEW FIRST TEXT BLOCK of the first user message — system and every cache_control marker are untouched; other stages and the control arm are forwarded unchanged. Refusals are named in the error message. A call without the header is unaffected. Requires API-key scope: gateway:invoke.

Auth: API key (Authorization: Bearer ur_sk_…).

curl -sS -X POST "$UR_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $UR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "string"
  }'