---
title: "Responses"
method: POST
path: "/responses"
tags: ["openai-compat"]
---

# Responses

`POST /responses`

OpenAI-compatible Responses API endpoint.

Thin shell over :func:`services.inference.adapters.openai_responses.run_responses`.
The adapter handles input-item to chat-message translation,
LLM-passthrough vs Pioneer-task dispatch, SSE rendering,
tool-call serialisation, persistence, and error mapping. The
router keeps only HTTP-shaped concerns: route declaration, auth,
rate limiting.

Args:
    body: Validated :class:`ResponsesRequest`.
    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:
    JSON response payload or :class:`StreamingResponse` SSE stream
    in Responses API format.

## Request body

- ResponsesRequest — OpenAI-compatible Responses API request. ``input`` accepts either a plain string (convenience shorthand used by the OpenAI SDK for simple text prompts) or a list of input items.
  - `model` string, required
  - `instructions` string
  - `input` union
    - string
    - object[]
  - `tools` object[]
  - `tool_choice` union
    - string
    - object
  - `parallel_tool_calls` boolean
  - `reasoning` ResponsesReasoningRequest — Opt-in reasoning controls in OpenAI Responses format.
    - `effort` string, nullable — Optional reasoning effort hint, such as 'low', 'medium', or 'high'.
    - `summary` string, nullable — Optional Responses-style reasoning summary mode.
    - `enabled` boolean, nullable — OpenRouter-style switch for enabling reasoning on capable models.
    - `exclude` boolean, nullable — When supported by the upstream provider, exclude reasoning text from the response while still allowing the model to use reasoning.
  - `store` boolean — Whether to store response state for turn-to-turn continuation. When true, Pioneer preserves the response for previous_response_id replay, including available tool-call and reasoning context.
  - `stream` boolean
  - `previous_response_id` string, nullable — Pioneer inference ID or stored Responses wire ID to continue from. When present, Pioneer reconstructs the prior turn from inference history and prepends it to the new input.
  - `include` string[]
  - `service_tier` string, nullable
  - `prompt_cache_key` string, nullable
  - `text` ResponsesTextRequest — Responses text controls.
    - `verbosity` string, nullable
    - `format` ResponsesTextFormatRequest — Structured-output controls for Responses text formatting.
      - `type` string, nullable
      - `strict` boolean, nullable
      - `schema` object, nullable
      - `name` string, nullable
  - `max_output_tokens` integer, nullable
  - `temperature` number, nullable
  - `top_p` number, nullable
  - `metadata` object, nullable
  - `extra_headers` object, nullable
  - `extra_body` object, nullable
  - `task_type` string, nullable — **Deprecated.** Legacy task hint (``extract_entities`` / ``classify_text`` / ``extract_json`` / ``ner`` / ``schema``). The unified schema on ``text.format.schema`` disambiguates the task automatically. Submitting this field emits ``Deprecation: true`` and ``Sunset: <RFC 7231 date>`` headers on the response.
  - `include_confidence` boolean, nullable
  - `include_spans` boolean, nullable
  - `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`

Successful Response

- unknown

## 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)