---
title: "Post Responses Endpoint"
method: POST
path: "/v1/responses"
tags: ["Responses"]
---

# Post Responses Endpoint

`POST /v1/responses`

## Request

- Base URL: `https://api.pharia.example.com`
- URL: `https://api.pharia.example.com/v1/responses`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/aleph-alpha/apis/stateful-responses/docs/v1/responses/post.ts> (a function with typed inputs; its response is checked against the schema)

Handle POST /v1/responses - with history reconstruction and storage.

If previous_response_id is provided, reconstructs the conversation history
and includes it in the request to the backend. Stores the request-response
pair for future history reconstruction.

Instructions resolution priority:
1. prompt.id (render template with variables)
2. explicit instructions field
3. inherited from previous_response_id
4. default_system_prompt from config

Supports both streaming (stream=true) and non-streaming modes.
Supports background mode (background=true) returning 202.

## Request body

- ResponseRequest: Request for Open Responses API. Supports MCP hosted tools (server-executed).
  - `model` string, required: The model to use for this request.
  - `input` union, required: Context for the model. May be a string or an array of input items.
    - string
    - union[]
      - union: Input item type, used to determine the input item schema
        - InputItemMessage: Input item for structured input. Per Open Responses spec, supports: - message type: role + content - function_call type: call_id + name + arguments (for history) - function_call_output type: call_id + output (tool results) Fields: - id: unique identifier (optional on input, populated on output) - status: in_progress, completed, incomplete (optional on input)
          - `type` 'message', required
          - `id` string, nullable: Unique identifier for messages
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
          - `role` string, nullable
          - `content` union
            - string
            - string[]
            - ContentItem[]
              - …
            - union[]
              - …
        - InputItemReasoning: Input item for reasoning type messages.
          - `type` 'reasoning', required
          - `id` string, required: Unique identifier for reasoning messages
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
          - `role` string, nullable
          - `content` union
            - string
            - string[]
            - ContentItem[]
              - …
            - union[]
              - …
          - `summary` ReasoningSummaryItem[]: Reasoning summary items returned by the downstream service.
            - `type` 'summary_text', required
            - `text` string, required
        - InputItemFunctionCall: Input item for function call (history reconstruction).
          - `type` 'function_call', required
          - `id` string, required: Unique identifier for the function call
          - `call_id` string, required
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
          - `name` string, nullable
          - `arguments` string, nullable
        - InputItemFunctionCallOutput: Input item for function call (history reconstruction).
          - `type` 'function_call_output', required
          - `call_id` string, required
          - `id` string, nullable: Unique identifier for the function call output
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
          - `output` string, nullable
        - InputItemShellCall: Input item for shell tool call (history reconstruction).
          - `type` 'shell_call', required
          - `id` string, required: Unique identifier for the shell call
          - `call_id` string, required
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
          - `name` string, nullable
          - `arguments` string, nullable
        - InputItemShellCallOutput: Input item for shell tool call output (history reconstruction).
          - `type` 'shell_call_output', required
          - `call_id` string, required
          - `id` string, nullable: Unique identifier for the shell call output
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
          - `output` string, nullable
        - InputItemMcpApprovalRequest
          - `type` 'mcp_approval_request', required
          - `id` string, required: Unique identifier for the approval request
          - `name` string, nullable
          - `server_label` string, nullable
          - `arguments` string, nullable
        - InputItemMcpApprovalResponses
          - `type` 'mcp_approval_response', required
          - `id` string, required: Unique identifier for the approval response
          - `approval_request_id` string, required
          - `approve` boolean, required
          - `reason` string, nullable: Why the call was not approved. Filled in by the service when the user sent a new message instead of answering.
          - `name` string, nullable
          - `arguments` string, nullable
        - InputItemMcpListTools
          - `type` 'mcp_list_tools', required
          - `id` string, required: Unique identifier for the MCP list tools
          - `server_label` string, nullable
          - `tools` union
            - object
            - unknown[]
              - …
          - `error` string, nullable
        - InputItemMcpCall
          - `type` 'mcp_call', required
          - `id` string, required: Unique identifier for the MCP call
          - `name` string, required
          - `arguments` string, nullable
          - `server_label` string, nullable
          - `output` string, nullable
          - `error` McpToolExecutionError: The tool's own error, in the shape the OpenAI SDK's mcp_call uses.
            - `type` 'mcp_tool_execution_error'
            - `content` string, required
        - InputItemFileSearchCall: Hosted file-search call/result output item. Mirrors OpenAI/OpenResponses ``file_search_call`` enough for upstream PydanticAI clients to map it as a native tool call while allowing Sherlock result extensions in ``results``.
          - `type` 'file_search_call', required
          - `id` string: Unique identifier for the file search call
          - `status` 'in_progress' | 'searching' | 'completed' | 'incomplete' | 'failed', required
          - `queries` string[]
          - `results` object[], nullable
        - InputItemWebSearchCall: Hosted web-search call/result output item. Mirrors OpenAI/OpenResponses ``web_search_call`` enough for upstream clients to map it as a native tool call while embedding the LinkUp results directly in ``results``.
          - `type` 'web_search_call', required
          - `id` string: Unique identifier for the web search call
          - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required
          - `action` object, nullable: How the model invoked the tool, e.g. {"type": "search", "query": ...}
          - `results` object[], nullable
        - InputItemCompaction: Compaction item — opaque summary blob, mirrors OpenAI's `/v1/responses/compact` shape.
          - `type` 'compaction', required
          - `id` string, nullable: Identifier of the compaction item.
          - `encrypted_content` string, required: The (potentially encrypted) content of the compaction summary.
  - `instructions` string, nullable: Additional instructions to guide the model for this request.
  - `previous_response_id` string, nullable: The ID of the response to use as the prior turn.
  - `prompt` PromptConfig: Prompt template configuration.
    - `id` string, required
    - `variables` object
  - `temperature` number, nullable: Sampling temperature between 0 and 2.
  - `top_p` number, nullable: Nucleus sampling parameter, between 0 and 1.
  - `max_output_tokens` integer, nullable: The maximum number of tokens the model may generate.
  - `stream` boolean: Whether to stream response events as server-sent events.
  - `stop` string[], nullable
  - `modify_request` boolean
  - `conversation` ConversationRef: Minimal conversation reference embedded in response objects.
    - `id` string, required
  - `tools` union[], nullable: A list of tools that the model may call while generating the response.
    - union: Tool type, used to determine the tool schema
      - Function: Function tool definition (client-executed).
        - `type` 'function', required: Tool type, must be 'function'
        - `name` string, required: Name of the function tool
        - `parameters` object, nullable
        - `strict` boolean
        - `description` string, nullable
      - MCPTool: MCP hosted tool definition (server-executed).
        - `type` 'mcp', required: Tool type, must be 'mcp'
        - `server_url` string, required: URL for the server to call when executing the tool
        - `require_approval` 'always' | 'never': Whether the server requires approval before calling the tool. 'always' means approval is required, 'never' means no approval needed.
        - `server_label` string, required: Label for the tool to be used by the server
        - `allowed_tools` union: Optional dict or array of allowed tools that the server can call, keyed by tool name. This can be used to specify which tools the server is allowed to call, and can include additional configuration for each tool.
          - object
          - string[]
        - `authorization` string, nullable: Optional authorization information for the server to use when calling the tool. This can include API keys, tokens, or other credentials needed to access the tool.
        - `headers` object, nullable: Optional headers to include when the server calls the tool. This can be used to provide additional context or information needed for the tool execution.
        - `server_description` string, nullable: Optional description for the server to understand the tool's purpose
        - `on_unavailable` 'fail' | 'skip': What to do when the server's tools cannot be listed. 'fail' fails the response. 'skip' records the error on the mcp_list_tools item and answers without this server's tools. Not part of the OpenAI API.
      - FileSearchTool: Aleph/OpenResponses hosted file-search tool definition. A single hosted tool can scope search/read to either uploaded documents (``attachments``) and/or whole knowledge-base stores (``search_store_ids``).
        - `type` 'file_search', required: Tool type, must be 'file_search'
        - `attachments` FileSearchAttachment[]
          - `searchStoreId` string, required
          - `fileId` string, required
          - `documentId` string, required
          - `fileName` string, required
        - `citations` boolean
        - `search_store_ids` string[]
      - ShellTool: Shell tool definition (server-executed in a containerized environment).
        - `type` 'shell', required: Tool type, must be 'shell'
        - `environment` ShellEnvironment, required: Environment configuration for a shell tool.
          - `type` string, required: Environment type (e.g. 'container_auto')
          - `skills` SkillReference[]: Skills available in the shell environment
            - `type` 'skill_reference', required: Type, must be 'skill_reference'
            - `skill_id` string, required: Identifier of the skill
            - `version` integer, nullable: Optional version of the skill to use
      - WebSearchTool: Hosted web-search tool definition (LinkUp-backed, server-executed). Exposes agentic ``web_search`` and ``fetch_url`` function tools to the model; both are executed server-side against the LinkUp API. ``depth`` maps directly onto LinkUp's search depth — no translation layer.
        - `type` 'web_search', required: Tool type, must be 'web_search'
        - `depth` 'fast' | 'standard' | 'deep': LinkUp search depth: 'fast', 'standard' or 'deep'
        - `filters` WebSearchFilters: Domain filters for hosted web search.
          - `allowed_domains` string[]: Restrict the search to these domains
          - `blocked_domains` string[]: Exclude these domains from the search
  - `tool_choice` union: Controls which tool the model should use, if any.
    - 'auto' | 'required' | 'none'
    - object
  - `parallel_tool_calls` boolean: Whether the model may call multiple tools in parallel.
  - `include` string[], nullable
  - `store` boolean: Whether to store the response so it can be retrieved later.
  - `metadata` object, nullable: Key-value pairs for storing additional information about the object.
  - `truncation` string, nullable: Controls how the service truncates input exceeding the context window.
  - `text` object, nullable: Configuration options for text output.
  - `presence_penalty` number, nullable: Penalizes new tokens based on whether they appear in the text so far.
  - `frequency_penalty` number, nullable: Penalizes new tokens based on their frequency in the text so far.
  - `top_logprobs` integer, nullable: Number of most likely tokens to return at each position.
  - `max_tool_calls` integer, nullable: The maximum number of tool calls the model may make.
  - `service_tier` string, nullable: The service tier to use for this request.
  - `background` boolean: Whether to run the request in the background and return immediately.
  - `reasoning` object, nullable: Configuration options for reasoning behavior.

## Response `200`

When `stream=false` (default), returns a JSON response. When `stream=true`, returns Server-Sent Events.

- ResponseResponse: Response from Open Responses API. All fields marked as required in the OpenResponses spec are present here. Nullable fields default to None and are serialized as null (not omitted).
  - `id` string, required: The unique ID of the response.
  - `object` string: The object type.
  - `created_at` integer, required: The Unix timestamp (in seconds) for when the response was created.
  - `completed_at` integer, nullable: The Unix timestamp (in seconds) for when the response was completed.
  - `status` string: The status of the response.
  - `incomplete_details` object, nullable: Details about why the response was incomplete, if applicable.
  - `model` string, required: The model that generated this response.
  - `previous_response_id` string, nullable: The ID of the previous response in the conversation chain, if any.
  - `instructions` string, nullable: Additional instructions used to guide the model for this response.
  - `output` union[], required: The output items generated by the model.
    - union: Input item type, used to determine the input item schema
      - InputItemMessage: Input item for structured input. Per Open Responses spec, supports: - message type: role + content - function_call type: call_id + name + arguments (for history) - function_call_output type: call_id + output (tool results) Fields: - id: unique identifier (optional on input, populated on output) - status: in_progress, completed, incomplete (optional on input)
        - `type` 'message', required
        - `id` string, nullable: Unique identifier for messages
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - `role` string, nullable
        - `content` union
          - string
          - string[]
          - ContentItem[]
            - `type` string
            - `text` string, required
            - `annotations` object[]
              - …
          - union[]
            - union: A typed input content part (input_text/input_image).
              - …
      - InputItemReasoning: Input item for reasoning type messages.
        - `type` 'reasoning', required
        - `id` string, required: Unique identifier for reasoning messages
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - `role` string, nullable
        - `content` union
          - string
          - string[]
          - ContentItem[]
            - `type` string
            - `text` string, required
            - `annotations` object[]
              - …
          - union[]
            - union: A typed input content part (input_text/input_image).
              - …
        - `summary` ReasoningSummaryItem[]: Reasoning summary items returned by the downstream service.
          - `type` 'summary_text', required
          - `text` string, required
      - InputItemFunctionCall: Input item for function call (history reconstruction).
        - `type` 'function_call', required
        - `id` string, required: Unique identifier for the function call
        - `call_id` string, required
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - `name` string, nullable
        - `arguments` string, nullable
      - InputItemFunctionCallOutput: Input item for function call (history reconstruction).
        - `type` 'function_call_output', required
        - `call_id` string, required
        - `id` string, nullable: Unique identifier for the function call output
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - `output` string, nullable
      - InputItemShellCall: Input item for shell tool call (history reconstruction).
        - `type` 'shell_call', required
        - `id` string, required: Unique identifier for the shell call
        - `call_id` string, required
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - `name` string, nullable
        - `arguments` string, nullable
      - InputItemShellCallOutput: Input item for shell tool call output (history reconstruction).
        - `type` 'shell_call_output', required
        - `call_id` string, required
        - `id` string, nullable: Unique identifier for the shell call output
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - `output` string, nullable
      - InputItemMcpApprovalRequest
        - `type` 'mcp_approval_request', required
        - `id` string, required: Unique identifier for the approval request
        - `name` string, nullable
        - `server_label` string, nullable
        - `arguments` string, nullable
      - InputItemMcpApprovalResponses
        - `type` 'mcp_approval_response', required
        - `id` string, required: Unique identifier for the approval response
        - `approval_request_id` string, required
        - `approve` boolean, required
        - `reason` string, nullable: Why the call was not approved. Filled in by the service when the user sent a new message instead of answering.
        - `name` string, nullable
        - `arguments` string, nullable
      - InputItemMcpListTools
        - `type` 'mcp_list_tools', required
        - `id` string, required: Unique identifier for the MCP list tools
        - `server_label` string, nullable
        - `tools` union
          - object
          - unknown[]
            - unknown
        - `error` string, nullable
      - InputItemMcpCall
        - `type` 'mcp_call', required
        - `id` string, required: Unique identifier for the MCP call
        - `name` string, required
        - `arguments` string, nullable
        - `server_label` string, nullable
        - `output` string, nullable
        - `error` McpToolExecutionError: The tool's own error, in the shape the OpenAI SDK's mcp_call uses.
          - `type` 'mcp_tool_execution_error'
          - `content` string, required
      - InputItemFileSearchCall: Hosted file-search call/result output item. Mirrors OpenAI/OpenResponses ``file_search_call`` enough for upstream PydanticAI clients to map it as a native tool call while allowing Sherlock result extensions in ``results``.
        - `type` 'file_search_call', required
        - `id` string: Unique identifier for the file search call
        - `status` 'in_progress' | 'searching' | 'completed' | 'incomplete' | 'failed', required
        - `queries` string[]
        - `results` object[], nullable
      - InputItemWebSearchCall: Hosted web-search call/result output item. Mirrors OpenAI/OpenResponses ``web_search_call`` enough for upstream clients to map it as a native tool call while embedding the LinkUp results directly in ``results``.
        - `type` 'web_search_call', required
        - `id` string: Unique identifier for the web search call
        - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required
        - `action` object, nullable: How the model invoked the tool, e.g. {"type": "search", "query": ...}
        - `results` object[], nullable
      - InputItemCompaction: Compaction item — opaque summary blob, mirrors OpenAI's `/v1/responses/compact` shape.
        - `type` 'compaction', required
        - `id` string, nullable: Identifier of the compaction item.
        - `encrypted_content` string, required: The (potentially encrypted) content of the compaction summary.
  - `error` object, nullable: The error that occurred, if the response failed.
  - `tools` union[]: The tools available to the model during response generation.
    - union: Tool type, used to determine the tool schema
      - Function: Function tool definition (client-executed).
        - `type` 'function', required: Tool type, must be 'function'
        - `name` string, required: Name of the function tool
        - `parameters` object, nullable
        - `strict` boolean
        - `description` string, nullable
      - MCPTool: MCP hosted tool definition (server-executed).
        - `type` 'mcp', required: Tool type, must be 'mcp'
        - `server_url` string, required: URL for the server to call when executing the tool
        - `require_approval` 'always' | 'never': Whether the server requires approval before calling the tool. 'always' means approval is required, 'never' means no approval needed.
        - `server_label` string, required: Label for the tool to be used by the server
        - `allowed_tools` union: Optional dict or array of allowed tools that the server can call, keyed by tool name. This can be used to specify which tools the server is allowed to call, and can include additional configuration for each tool.
          - object
          - string[]
        - `authorization` string, nullable: Optional authorization information for the server to use when calling the tool. This can include API keys, tokens, or other credentials needed to access the tool.
        - `headers` object, nullable: Optional headers to include when the server calls the tool. This can be used to provide additional context or information needed for the tool execution.
        - `server_description` string, nullable: Optional description for the server to understand the tool's purpose
        - `on_unavailable` 'fail' | 'skip': What to do when the server's tools cannot be listed. 'fail' fails the response. 'skip' records the error on the mcp_list_tools item and answers without this server's tools. Not part of the OpenAI API.
      - FileSearchTool: Aleph/OpenResponses hosted file-search tool definition. A single hosted tool can scope search/read to either uploaded documents (``attachments``) and/or whole knowledge-base stores (``search_store_ids``).
        - `type` 'file_search', required: Tool type, must be 'file_search'
        - `attachments` FileSearchAttachment[]
          - `searchStoreId` string, required
          - `fileId` string, required
          - `documentId` string, required
          - `fileName` string, required
        - `citations` boolean
        - `search_store_ids` string[]
      - ShellTool: Shell tool definition (server-executed in a containerized environment).
        - `type` 'shell', required: Tool type, must be 'shell'
        - `environment` ShellEnvironment, required: Environment configuration for a shell tool.
          - `type` string, required: Environment type (e.g. 'container_auto')
          - `skills` SkillReference[]: Skills available in the shell environment
            - `type` 'skill_reference', required: Type, must be 'skill_reference'
            - `skill_id` string, required: Identifier of the skill
            - `version` integer, nullable: Optional version of the skill to use
      - WebSearchTool: Hosted web-search tool definition (LinkUp-backed, server-executed). Exposes agentic ``web_search`` and ``fetch_url`` function tools to the model; both are executed server-side against the LinkUp API. ``depth`` maps directly onto LinkUp's search depth — no translation layer.
        - `type` 'web_search', required: Tool type, must be 'web_search'
        - `depth` 'fast' | 'standard' | 'deep': LinkUp search depth: 'fast', 'standard' or 'deep'
        - `filters` WebSearchFilters: Domain filters for hosted web search.
          - `allowed_domains` string[]: Restrict the search to these domains
          - `blocked_domains` string[]: Exclude these domains from the search
  - `tool_choice` union: Controls which tool the model should use, if any.
    - 'auto' | 'required' | 'none'
    - object
  - `truncation` string, nullable: How the input was truncated when it exceeded the model context window.
  - `parallel_tool_calls` boolean: Whether the model was allowed to call multiple tools in parallel.
  - `text` object, nullable: Configuration options for text output.
  - `top_p` number, nullable: The nucleus sampling parameter used for this response.
  - `temperature` number, nullable: The sampling temperature used for this response.
  - `presence_penalty` number, nullable: Penalizes new tokens based on whether they appear in the text so far.
  - `frequency_penalty` number, nullable: Penalizes new tokens based on their frequency in the text so far.
  - `top_logprobs` integer, nullable: Number of most likely tokens returned at each position.
  - `reasoning` object, nullable: Reasoning configuration and outputs produced for this response.
  - `usage` UsageInfo: Token usage information.
    - `input_tokens` integer, required
    - `output_tokens` integer, required
    - `total_tokens` integer, required
  - `max_output_tokens` integer, nullable: The maximum number of tokens the model was allowed to generate.
  - `max_tool_calls` integer, nullable: The maximum number of tool calls the model was allowed to make.
  - `store` boolean: Whether this response was stored for later retrieval.
  - `background` boolean: Whether this request was run in the background.
  - `service_tier` string, nullable: The service tier used for this response.
  - `metadata` object, nullable: Key-value pairs for storing additional information about the response.
  - `prompt_cache_key` string, nullable: A key used to read from or write to the prompt cache.
  - `conversation` ConversationRef: Minimal conversation reference embedded in response objects.
    - `id` string, required
  - `safety_identifier` string, nullable: A stable identifier used for safety monitoring and abuse detection.
  - `trace_id` string, nullable: 32-character lowercase hex OpenTelemetry trace ID for the generation request. Server-populated from the active span when the generated response is completed. Null on incomplete, failed, cancelled, in-progress, synthetic, historical, and tracing-disabled responses.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `413`: Content Too Large
- `422`: Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically.
- `425`: Too Early
- `500`: Internal Server Error
- `501`: Not Implemented
- `502`: Bad Gateway
- `504`: Gateway Timeout

---

[API](https://skmtc.dev/aleph-alpha/apis/stateful-responses.md) - [All operations](https://skmtc.dev/aleph-alpha/apis/stateful-responses/llms.txt) - [OpenAPI document](https://skmtc.dev/aleph-alpha/apis/stateful-responses/revisions/2747297acb54?raw)