Create a chat completion

Send a chat request through routeur.ai. The request body is OpenAI-compatible: routing, DLP, and moderation are applied transparently by the gateway before the upstream provider sees the prompt.

POST /v1/chat/completions Stable

https://api.routeur.ai

Request body

model string required

The model to use. Pass auto (or any other alias defined in your routing rules) to let routeur.ai pick the upstream model. Pass an explicit upstream model id (e.g. gpt-4o-mini, claude-3-5-sonnet) to bypass routing and send the request directly to that model.

messages array of object required

Conversation history. Each item has a role and content.

temperature number optional · default 1

Sampling temperature passed through to the upstream provider.

stream boolean optional · default false

When true, the response is streamed as server-sent events (text/event-stream): a sequence of chat.completion.chunk objects terminated by data: [DONE]. For organizations with output-moderation rules the stream is delivered only after moderation completes (see the Streaming section of the guide).

Routeur headers

Routeur-Trace true | false optional

Append a routeur metadata block to the response.

Routeur-Dry-Run true | false optional

Return the route resolution without calling the upstream provider.

Returns

An OpenAI-compatible chat completion object. With Routeur-Trace: true, the response also includes a routeur block describing the route and any redactions applied.

Streaming

Set "stream": true to receive the response as server-sent events. The gateway emits Content-Type: text/event-stream and a sequence of chat.completion.chunk objects — one per data: line — terminated by a final data: [DONE] sentinel. The format matches OpenAI's, so any OpenAI-compatible client (the openai SDKs, the Vercel AI SDK, LangChain) consumes it with no special-casing.

curl https://api.routeur.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEUR_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{"model":"auto","stream":true,"messages":[{"role":"user","content":"Hello"}]}'

Token deltas arrive in choices[].delta.content.
Usage is reported on the final chunk before [DONE] (prompt_tokens, completion_tokens, total_tokens) — routeur always includes it.
Trace metadata. With Routeur-Trace: true, the routeur block is delivered as one extra chunk (empty choices) immediately before [DONE].

Moderated organizations buffer first

If your organization has output-moderation rules, a streamed request is held until the full upstream response has been generated and moderated, then replayed to you as a stream. You still receive a spec-compliant event stream; it simply begins after moderation completes rather than token-by-token. This preserves the guarantee that blocked content never reaches the caller. See Output moderation for the buffered vs chunked modes.

Errors mid-stream

Once the first chunk has been sent the HTTP status is committed to 200, so a failure after that point is delivered as a terminal SSE event rather than an HTTP error:

event: error
data: {"error":{"code":"upstream_error","message":"...","type":"routeur_error"},"request_id":"01K..."}

A pre-stream failure (auth, routing, an upstream that never produced a byte) is returned as the usual JSON error with the appropriate status code. See Errors for the full list.

← Authentication Routes →