---
title: "Chat Completions"
method: POST
path: "/v1/chat/completions"
tags: ["openai-compat"]
---

# Chat Completions

`POST /v1/chat/completions`

OpenAI-compatible chat completions endpoint.

Thin shell over :func:`services.inference.adapters.openai_chat.run_chat_completion`.
The adapter handles LLM-passthrough vs Pioneer-task dispatch, SSE
rendering with ``<think>...</think>`` folding for reasoning models,
tool-call deltas, finish-reason mapping, persistence, and error
mapping. The router keeps only HTTP-shaped concerns: route
declaration, auth, rate limiting.

Args:
    body: Validated :class:`ChatCompletionRequest`.
    request: FastAPI request (forwarded so the adapter can read
        API-key billing context out of ``request.state`` for
        streaming responses).
    auth: Authenticated request context.

Returns:
    :class:`ChatCompletionResponse` for non-streaming, or a
    :class:`StreamingResponse` of ``chat.completion.chunk`` SSE
    events terminated by ``data: [DONE]`` when ``body.stream``
    is true.

## Request body

- ChatCompletionRequest — OpenAI-compatible chat completion request.
  - `model` string, required
  - `messages` SchemasOpenaiCompatChatMessage[], required
    - `role` string, required
    - `content` union
      - string
      - object[]
    - `name` string, nullable
    - `tool_calls` unknown[], nullable
      - unknown
    - `tool_call_id` string, nullable
    - `reasoning_content` string, nullable
  - `system` union
    - string
    - object[]
  - `temperature` number, nullable
  - `max_tokens` integer, nullable
  - `response_format` object, nullable
  - `stop` union
    - string[]
    - string
  - `stream` boolean
  - `extra_headers` object, nullable
  - `extra_body` object, nullable
  - `reasoning` object, nullable — Opt-in reasoning / extended-thinking controls. Accepts the OpenRouter-normalized shape with keys ``enabled`` (bool), ``max_tokens`` (int, Anthropic-style budget), ``effort`` (one of minimal/low/medium/high/xhigh/max/none, OpenAI/Grok-style tier), and ``exclude`` (bool, hide reasoning tokens from the response). ``effort`` and ``max_tokens`` are mutually exclusive. Pioneer extensions for Claude routes (Anthropic direct + Bedrock): ``mode`` (manual/adaptive — adaptive lets the model pick thinking depth per request, required on Opus 4.7+) and ``display`` (summarized/omitted — controls whether thinking text streams back; omitted preserves only the signature for multi-turn). On Chat Completions, provider reasoning text is hidden by default and is returned on ``message.reasoning_content`` / ``delta.reasoning_content`` only when the caller explicitly requests visible reasoning with ``exclude=false`` or ``display=summarized``. Pioneer canonicalizes this into InferenceRequest.reasoning at the adapter boundary and each provider renders it to its native wire field (Anthropic ``thinking``, OpenAI ``reasoning_effort``, OpenRouter ``reasoning``). Pioneer does not enable reasoning by default.
  - `store` boolean
  - `metadata` object, nullable
  - `top_p` number, nullable
  - `n` integer, nullable
  - `presence_penalty` number, nullable
  - `frequency_penalty` number, nullable
  - `logit_bias` object, nullable
  - `user` string, nullable
  - `seed` integer, nullable
  - `tools` unknown[], nullable
    - unknown
  - `tool_choice` union
    - string
    - object
  - `schema` union — Schema for the Pioneer encoder. **Deprecated when supplied as a flat list** of entity labels; use the unified dict shape (``entities`` / ``classifications`` / ``structures`` / ``relations``) instead. Deprecated submissions emit ``Deprecation: true`` and ``Sunset: <RFC 7231 date>`` headers.
    - string[]
    - object
  - `task_type` string, nullable — **Deprecated.** Legacy task hint (``extract_entities`` / ``classify_text`` / ``extract_json`` / ``ner`` / ``schema``). The unified schema disambiguates the task automatically so this field is no longer required. Submitting it emits ``Deprecation: true`` and ``Sunset: <RFC 7231 date>`` headers on the response.
  - `include_confidence` boolean
  - `include_spans` boolean
  - `effort` 'low' | 'medium' | 'high' | 'xhigh' | 'max' — Per-request routing-effort tier, ascending in cost and quality. A router-agnostic label the caller sends as the ``effort`` param (or as a ``model`` suffix). Each router type maps these tiers to its own concrete policy via its :class:`RouterProfile`.
  - `models` string[], nullable — Per-request candidate-model subset the router may select between. Overrides the router's stored candidate set for this request only; ignored for non-router models.

## Response `200`

Chat completion. Returns ``application/json`` (``ChatCompletionResponse``) by default, or ``text/event-stream`` of ``ChatCompletionStreamChunk`` events terminated by ``data: [DONE]`` when ``stream=true``.

- ChatCompletionResponse — OpenAI-compatible chat completion response.
  - `id` string
  - `object` string
  - `created` integer
  - `model` string, required
  - `choices` ChatCompletionChoice[], required
    - `index` integer
    - `message` object
    - `finish_reason` string, nullable
  - `usage` ChatCompletionUsage, required — Token usage statistics. ``prompt_tokens`` follows the upstream wire contract — *includes* every input class (non-cached, cache read, and cache write). The breakdown is exposed under ``prompt_tokens_details`` so consumers can attribute the cached-read and cache-write subsets. Cache-aware billing on the brain side reads the canonical ``InferenceUsage`` fields directly, not this wire payload.
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
    - `prompt_tokens_details` PromptTokensDetails — Per-input-class breakdown for OpenAI-shape usage payloads. Mirrors OpenAI's ``prompt_tokens_details`` block and OpenRouter's cache-creation extension so clients reading ``usage.prompt_tokens_details.cached_tokens`` / ``cache_write_tokens`` keep working when Pioneer relays a cache-aware upstream response. Both counts are subsets of ``prompt_tokens`` on the wire — that's the upstream contract Pioneer relays faithfully. Attributes: cached_tokens: Input tokens served from the upstream prompt cache (cache read). cache_write_tokens: Input tokens written into the upstream prompt cache (cache creation). ``0`` for upstreams that bill writes as plain input (OpenAI, Fireworks, vLLM).
      - `cached_tokens` integer
      - `cache_write_tokens` integer
  - `x_pioneer` PioneerExtension — Pioneer-specific extension fields appended to OpenAI-compatible responses. OpenAI's API contract reserves the unprefixed top-level keys (``id``, ``choices``, ``usage``, …); custom data must live under a clearly namespaced key. ``x_pioneer`` is that key. Attributes: inference_id: The Pioneer-side identifier of the persisted ``inferences`` row associated with this completion. Present when persistence is enabled (``extra_body.store == True``) and the row was successfully recorded; ``None`` for ad-hoc requests that opted out of persistence. The frontend uses this to poll ``GET /inferences/{id}`` for asynchronous judge results without coupling the inference response latency to the judge. routed_model: Backend catalog model selected by a router project (for example ``pioneer/auto``). ``None`` when the request was not routed or the routed model matches the requested id. savings: Routed-vs-frontier per-1M-token savings rate diff (same wire shape as the Anthropic ``pioneer_savings`` extension). The Codex routing-savings hook multiplies these rates by per-turn token usage to surface cumulative money saved. ``None`` when the request was not routed below the frontier reference model.
    - `inference_id` string, nullable
    - `routed_model` string, nullable
    - `savings` object, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/pioneer/apis/brain-api.md) · [All operations](https://skmtc.net/pioneer/apis/brain-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pioneer/brain-api/revisions/31dfe831e079/schema)