---
title: "Messages"
method: POST
path: "/v1/messages"
tags: ["anthropic-compat"]
---

# Messages

`POST /v1/messages`

Anthropic-compatible messages endpoint.

Thin shell over :func:`services.inference.adapters.anthropic_messages.run_messages`.
The adapter handles content-block translation, LLM-passthrough vs
Pioneer-task dispatch, SSE rendering, persistence, and error
mapping. The router keeps only HTTP-shaped concerns: route
declaration, auth, rate limiting.

Args:
    body: Validated :class:`AnthropicMessagesRequest`.
    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:`AnthropicMessagesResponse` for non-streaming, or a
    :class:`StreamingResponse` of Anthropic SSE events when
    ``body.stream`` is true.

## Request body

- AnthropicMessagesRequest — Anthropic Messages API request format.
  - `model` string, required
  - `messages` AnthropicMessage[], required
    - `role` string, required
    - `content` union, required
      - string
      - union[]
        - union
          - ContentBlock — A content block in Anthropic format. Supports ``text``, ``tool_use``, and ``tool_result`` block types so that tool-calling round-trips work with Anthropic SDK clients.
            - `type` string
            - `text` string, nullable
            - `id` string, nullable
            - `name` string, nullable
            - `input` object, nullable
            - `tool_use_id` string, nullable
            - `content` union
              - …
          - ImageContentBlock — Anthropic image content block.
            - `type` 'image'
            - `source` ImageSource, required — Anthropic image source (base64 or HTTPS URL).
              - …
          - object
  - `max_tokens` integer
  - `temperature` number, nullable
  - `top_p` number, nullable
  - `top_k` integer, nullable
  - `stream` boolean
  - `store` boolean
  - `system` union
    - string
    - SystemContentBlock[]
      - `type` string
      - `text` string
      - `cache_control` object, nullable
  - `cache_control` object, nullable
  - `tools` object[], nullable
  - `tool_choice` object, nullable
  - `stop_sequences` string[], nullable
  - `output_config` AnthropicOutputConfig — Anthropic output configuration passed through supported providers.
    - `effort` string, nullable
    - `task_budget` object, nullable
    - `format` object, nullable
  - `speed` 'standard' | 'fast', nullable — Anthropic inference speed mode. ``"fast"`` opts into high output-tokens-per-second inference on supported models (e.g. the latest Opus). Pioneer forwards this only to the native Anthropic upstream (with the required ``fast-mode`` beta header); Bedrock and gateway routes ignore it.
  - `thinking` object, nullable — Opt-in Anthropic-style extended-thinking controls. Pioneer does not enable thinking by default; send the Anthropic-native object: {'type': 'enabled', 'budget_tokens': N, 'display'?: 'summarized'|'omitted'} for manual mode, {'type': 'adaptive', 'effort'?: tier, 'display'?: ...} for adaptive mode (required on Opus 4.7+ / Mythos, recommended on Opus 4.6 / Sonnet 4.6), or {'type': 'disabled'} to turn thinking off on models that have it on by default. Pioneer canonicalizes this into InferenceRequest.reasoning at the adapter boundary so the request routes correctly whether the upstream is Anthropic native, Bedrock, or a gateway advertising the normalized ``reasoning`` field rather than ``thinking``. On models that require adaptive mode, Pioneer auto-upgrades manual configs (mapping ``budget_tokens`` to the nearest ``effort`` tier) rather than letting the upstream return a 400.
  - `schema` union — Schema for the Pioneer encoder. **Deprecated when supplied as a flat list** of entity labels; use the unified dict shape instead. Deprecated submissions emit ``Deprecation: true`` and ``Sunset: <RFC 7231 date>`` headers.
    - string[]
    - object
  - `task_type` string, nullable — **Deprecated.** Legacy task hint. The unified schema disambiguates the task automatically. Submitting this field emits ``Deprecation: true`` and ``Sunset: <RFC 7231 date>`` headers.
  - `include_confidence` boolean
  - `include_spans` boolean
  - `effort` 'low' | 'medium' | 'high' | 'xhigh' | 'max' — Per-request routing-effort tier, ascending in cost and quality. Sent by the caller as the ``effort`` param or as a ``model`` suffix. The per-router policy each tier used to map to is gone with the routers; the tier itself remains a request-level knob.
  - `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`

Non-streaming Anthropic Messages response. When the request sets ``stream=true`` the server emits an Anthropic-shaped SSE event stream over ``text/event-stream`` instead; that stream shape is documented in the Anthropic Messages API reference.

- AnthropicMessagesResponse — Anthropic Messages API response format. ``pioneer_inference_id`` is a Pioneer-only extension: the ``inferences.id`` of the persisted row backing this completion. It mirrors the ``x_pioneer.inference_id`` field on the OpenAI-compatible chat completion response so frontend playground clients can use the same poll-``GET /inferences/{id}``-for-judge-results round-trip on either surface. ``None`` when persistence didn't run (e.g. ``store=false``). ``pioneer_routed_model`` is the backend catalog model selected when the request used a router alias such as ``pioneer/auto``. ``None`` when no routing occurred or the routed model matches the requested id. ``pioneer_savings`` carries the per-1M-token savings rate diff of the routed model vs a fixed frontier reference (``baseline_model`` plus ``rate_diff_per_mtok`` with ``input``/``output``/``cache_read``/ ``cache_write`` keys). The Claude Code cost hook multiplies it by per-turn token usage to show money saved. ``None`` when not routed to a cheaper model.
  - `id` string, required
  - `type` string
  - `role` string
  - `content` object[], required
  - `model` string, required
  - `stop_reason` string, nullable
  - `stop_sequence` string, nullable
  - `usage` AnthropicUsage, required — Usage statistics in Anthropic format. ``input_tokens`` is Anthropic's non-cached input contract — cached reads / writes live in the separate ``cache_read_input_tokens`` / ``cache_creation_input_tokens`` fields. Pioneer mirrors the same shape on the ``/v1/messages`` wire so SDK consumers reading the fields directly stay correct.
    - `input_tokens` integer
    - `output_tokens` integer
    - `cache_read_input_tokens` integer
    - `cache_creation_input_tokens` integer
    - `thinking_tokens` integer, nullable
    - `server_tool_use` object, nullable
    - `service_tier` string, nullable
    - `speed` string, nullable
  - `pioneer_inference_id` string, nullable
  - `pioneer_routed_model` string, nullable
  - `pioneer_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/b92f75fd3b61/schema)