---
title: "Create a response"
method: POST
path: "/v1/responses"
tags: ["responses"]
---

# Create a response

`POST /v1/responses`

Create a text response with function and Mixedbread hosted-store tools.

## Request body

- ResponseCreateParams — Request body for POST /v1/responses.
  - `model` string
  - `input` union, required
    - string
    - union[]
      - union
        - ResponseMessageInput — An easy input message or a previously returned output message.
          - `type` 'message'
          - `role` 'user' | 'assistant' | 'system' | 'developer', required
          - `content` union, required
            - string
            - union[]
              - …
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
          - `id` string, nullable
          - `phase` 'commentary' | 'final_answer', nullable
        - ResponseFunctionCallInput — A previously returned client function call passed back as input.
          - `type` 'function_call'
          - `call_id` string, required
          - `name` string, required
          - `arguments` string, required
          - `id` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ResponseFunctionCallOutputInput — The caller-provided output of a function call.
          - `type` 'function_call_output'
          - `call_id` string, required
          - `output` union, required
            - string
            - ResponseInputTextPart[]
              - …
          - `id` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ResponseReasoningInput — A reasoning item accepted when callers manually replay prior output.
          - `type` 'reasoning'
          - `id` string, required
          - `summary` ResponseReasoningSummaryInput[]
            - `type` 'summary_text'
            - `text` string, required
          - `content` ResponseReasoningTextInput[], nullable
            - `type` 'reasoning_text'
            - `text` string, required
          - `encrypted_content` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ResponseAgentMessageInput — A Codex multi-agent message replayed as Responses input.
          - `type` 'agent_message'
          - `author` string, required
          - `recipient` string, required
          - `content` union[], required
            - union
              - …
          - `id` string, nullable
          - `internal_chat_message_metadata_passthrough` object, nullable
        - ResponseMcpApprovalResponseInput — The caller's answer to an `mcp_approval_request` of the previous response.
          - `type` 'mcp_approval_response'
          - `approval_request_id` string, required
          - `approve` boolean, required
          - `reason` string, nullable
          - `id` string, nullable
        - ResponseMcpApprovalRequestInput — A prior approval request replayed as input by a caller that holds no previous_response_id.
          - `type` 'mcp_approval_request'
          - `id` string, required
          - `server_label` string, required
          - `name` string, required
          - `arguments` string, required
        - ResponseMcpCallInput — A prior MCP call replayed as input; its output becomes the tool result the model saw.
          - `type` 'mcp_call'
          - `id` string, required
          - `server_label` string, required
          - `name` string, required
          - `arguments` string, required
          - `output` string, nullable
          - `error` string, nullable
          - `approval_request_id` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed', nullable
        - ResponseMcpListToolsInput — A prior tool listing replayed as input; it stands in for asking the server again.
          - `type` 'mcp_list_tools'
          - `id` string, required
          - `server_label` string, required
          - `tools` McpListToolsTool[], required
            - `name` string, required
            - `description` string, nullable
            - `input_schema` object, required
            - `annotations` object, nullable
          - `error` string, nullable
  - `instructions` string, nullable
  - `tools` union[]
    - union
      - ResponseFunctionTool — A Responses API function tool, whose definition is flat rather than nested.
        - `name` string, required
        - `description` string, nullable
        - `parameters` object, nullable
        - `strict` boolean, nullable
        - `type` 'function'
      - ResponseNamespaceTool — A Codex tool namespace containing client-executed functions.
        - `type` 'namespace'
        - `name` string, required
        - `description` string, nullable
        - `tools` ResponseFunctionTool[], required
          - `name` string, required
          - `description` string, nullable
          - `parameters` object, nullable
          - `strict` boolean, nullable
          - `type` 'function'
      - McpTool — Hosted tool: the tools of a remote MCP server, executed server-side. Follows the OpenAI Responses API `mcp` tool: the server's tools are listed when the request starts and offered to the model; a call runs against the server unless it needs the caller's approval first, in which case the turn ends with an approval request the caller answers on the next request. `headers` and `authorization` are credentials: they are never stored nor echoed back, so a continuation must declare the server again.
        - `type` 'mcp'
        - `server_label` string, required — Label identifying this server in tool calls
        - `server_url` string, nullable — URL of the server's Streamable HTTP endpoint
        - `connector_id` string, nullable — OpenAI service connectors are not supported
        - `server_description` string, nullable — Shown to the model beside the server's tools
        - `headers` object, nullable — HTTP headers sent to the server
        - `authorization` string, nullable — OAuth access token sent as a bearer token
        - `require_approval` union — Which tools need the caller's approval before running; defaults to all of them
          - 'always' | 'never'
          - McpApprovalFilter — Which of an MCP server's tools need the caller's approval before they run.
            - `always` McpToolFilter — Selects tools of an MCP server by name and/or by their read-only annotation. Shared by `allowed_tools` and the `require_approval` filters, as in the OpenAI Responses API.
              - …
            - `never` McpToolFilter — Selects tools of an MCP server by name and/or by their read-only annotation. Shared by `allowed_tools` and the `require_approval` filters, as in the OpenAI Responses API.
              - …
        - `allowed_tools` union — Tool names or a filter restricting the offer
          - string[]
          - McpToolFilter — Selects tools of an MCP server by name and/or by their read-only annotation. Shared by `allowed_tools` and the `require_approval` filters, as in the OpenAI Responses API.
            - `tool_names` string[], nullable — Tool names the filter matches
            - `read_only` boolean, nullable — Match tools whose `readOnlyHint` annotation equals this value
      - SearchCorpusTool — Hosted tool: semantic search over the caller's stores, executed server-side.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'search_corpus'
        - `filters` union — Optional filter conditions applied to every search
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
        - `score_threshold` number — Minimum similarity score threshold
        - `citations` boolean — Cite sources in the answer as <cite i="..."/> tags referencing result index fields
      - GrepTool — Hosted tool: regular-expression match over stores' chunks, executed server-side. grep runs the pattern against the literal chunk text — no embeddings, no reranker. Each call searches all pinned stores, or the store selected by the model when no stores are pinned, with one global result limit.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'grep'
        - `filters` union — Optional filter conditions applied to every grep
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
        - `citations` boolean — Cite sources in the answer as <cite i="..."/> tags referencing result index fields
      - FilterChunksTool — Hosted tool: metadata-driven listing of stores' chunks, executed server-side. No embeddings and no reranker: chunks are selected by metadata filters and optionally ordered globally by a numeric metadata field. Each call covers all pinned stores, or the store selected by the model when no stores are pinned.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'filter_chunks'
        - `filters` union — Optional filter conditions applied to every listing
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
        - `citations` boolean — Cite sources in the answer as <cite i="..."/> tags referencing result index fields
      - InspectMetadataTool — Hosted tool: metadata field/value overview of the caller's stores, executed server-side. Facets tell the model which metadata keys exist and what their values look like, so it can filter (`grep`, `filter_chunks`) and phrase queries against real values instead of guessing.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'inspect_metadata'
        - `filters` union — Optional filter conditions restricting the files the facets are computed over
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
      - GetChunksTool — Hosted tool: re-fetch of already-seen chunks by their `file_id:chunk_index` ids. The recovery half of the per-chunk payload clip: a chunk a search returned truncated can be re-read at a much larger budget. Configuration is the shared store scope only; the per-call id bound is the tool schema's own `maxItems`.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'get_chunks'
      - StoreSearchTool — Deprecated alias of `search_corpus`; parses to the same tool, echoed as sent.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'store_search'
        - `filters` union — Optional filter conditions applied to every search
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
        - `score_threshold` number — Minimum similarity score threshold
        - `citations` boolean — Cite sources in the answer as <cite i="..."/> tags referencing result index fields
      - StoreGrepTool — Deprecated alias of `grep`; parses to the same tool, echoed as sent.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'store_grep'
        - `filters` union — Optional filter conditions applied to every grep
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
        - `citations` boolean — Cite sources in the answer as <cite i="..."/> tags referencing result index fields
      - StoreListChunksTool — Deprecated alias of `filter_chunks`; parses to the same tool, echoed as sent.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'store_list_chunks'
        - `filters` union — Optional filter conditions applied to every listing
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
        - `citations` boolean — Cite sources in the answer as <cite i="..."/> tags referencing result index fields
      - MetadataFacetsTool — Deprecated alias of `inspect_metadata`; parses to the same tool, echoed as sent.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'store_metadata_facets'
        - `filters` union — Optional filter conditions restricting the files the facets are computed over
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
      - ListStoresTool — Hosted tool: paginated listing of the caller's stores, executed server-side. Pair it with the store-scoped tools that are left unpinned, so the model can discover which stores it may name.
        - `type` 'list_stores'
        - `limit` integer — Number of stores returned per listing call
  - `tool_choice` union
    - 'none' | 'auto' | 'required'
    - ResponseToolChoiceFunction — Force a Responses API function tool by name.
      - `type` 'function'
      - `name` string, required
    - ToolChoiceMcp — Force a call to one MCP server's tools, or to one named tool of it.
      - `type` 'mcp'
      - `server_label` string, required
      - `name` string, nullable
    - ToolChoiceSearchCorpus — Force a call to the hosted search tool (Mixedbread extension).
      - `type` 'search_corpus'
    - ToolChoiceGrep — Force a call to the hosted grep tool (Mixedbread extension).
      - `type` 'grep'
    - ToolChoiceFilterChunks — Force a call to the hosted chunk-listing tool (Mixedbread extension).
      - `type` 'filter_chunks'
    - ToolChoiceInspectMetadata — Force a call to the hosted metadata-overview tool (Mixedbread extension).
      - `type` 'inspect_metadata'
    - ToolChoiceStoreSearch — Deprecated alias of the `search_corpus` tool choice.
      - `type` 'store_search'
    - ToolChoiceStoreGrep — Deprecated alias of the `grep` tool choice.
      - `type` 'store_grep'
    - ToolChoiceStoreListChunks — Deprecated alias of the `filter_chunks` tool choice.
      - `type` 'store_list_chunks'
    - ToolChoiceMetadataFacets — Deprecated alias of the `inspect_metadata` tool choice.
      - `type` 'store_metadata_facets'
    - ToolChoiceListStores — Force a call to the hosted list stores tool (Mixedbread extension).
      - `type` 'list_stores'
  - `store` boolean
  - `previous_response_id` string, nullable
  - `context_management` ContextManagementConfig — Opt-in context editing for one completion (Mixedbread extension).
    - `edits` ContextManagementEdit[], required — The context edits enabled for this completion
      - `type` 'prune_context'
  - `stream` boolean
  - `stream_options` ResponseStreamOptions
    - `include_obfuscation` boolean
  - `temperature` number, nullable
  - `top_p` number, nullable
  - `max_output_tokens` integer, nullable
  - `max_tool_calls` integer, nullable
  - `parallel_tool_calls` boolean
  - `metadata` object, nullable
  - `include` string[], nullable
  - `text` ResponseTextConfig
    - `format` union
      - ResponseTextFormatText
        - `type` 'text'
      - ResponseTextFormatJSONObject
        - `type` 'json_object'
      - ResponseTextFormatJSONSchema
        - `type` 'json_schema'
        - `name` string, required
        - `schema` object, required
        - `description` string, nullable
        - `strict` boolean, nullable
    - `verbosity` 'low' | 'medium' | 'high', nullable
  - `background` boolean
  - `truncation` 'auto' | 'disabled'
  - `reasoning` ResponseReasoningConfig
    - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable
    - `summary` 'auto' | 'concise' | 'detailed', nullable
    - `generate_summary` 'auto' | 'concise' | 'detailed', nullable
  - `service_tier` 'auto' | 'default' | 'flex' | 'scale' | 'priority', nullable
  - `safety_identifier` string, nullable
  - `prompt_cache_key` string, nullable
  - `user` string, nullable
  - `client_metadata` object, nullable

## Response `200`

The generated response, or a semantic server-sent event stream

- Response — A completed or in-progress OpenAI-compatible Response object.
  - `id` string, required
  - `object` 'response'
  - `created_at` number, required
  - `status` 'completed' | 'failed' | 'in_progress' | 'cancelled' | 'queued' | 'incomplete', required
  - `completed_at` number, nullable
  - `error` ResponseError
    - `code` string, required
    - `message` string, required
  - `incomplete_details` ResponseIncompleteDetails
    - `reason` 'max_output_tokens' | 'content_filter' | 'max_tool_calls' | 'context_window', nullable
  - `instructions` string, nullable
  - `model` string
  - `output` union[]
    - union
      - ResponseOutputMessage
        - `type` 'message'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'incomplete', required
        - `role` 'assistant'
        - `content` ResponseOutputText[], required
          - `type` 'output_text'
          - `annotations` object[]
          - `text` string, required
          - `logprobs` object[]
      - ResponseFunctionToolCall
        - `type` 'function_call'
        - `id` string, required
        - `call_id` string, required
        - `name` string, required
        - `namespace` string, nullable
        - `arguments` string, required
        - `status` 'in_progress' | 'completed' | 'incomplete'
      - ResponseReasoningItem
        - `type` 'reasoning'
        - `id` string, required
        - `summary` ResponseReasoningSummaryInput[]
          - `type` 'summary_text'
          - `text` string, required
        - `content` ResponseReasoningText[], nullable
          - `type` 'reasoning_text'
          - `text` string, required
        - `status` 'in_progress' | 'completed' | 'incomplete'
      - ResponseMcpListTools — The tools one MCP server offered this response.
        - `type` 'mcp_list_tools'
        - `id` string, required
        - `server_label` string, required
        - `tools` McpListToolsTool[]
          - `name` string, required
          - `description` string, nullable
          - `input_schema` object, required
          - `annotations` object, nullable
        - `error` string, nullable
      - ResponseMcpCall — One tool call run against an MCP server.
        - `type` 'mcp_call'
        - `id` string, required
        - `server_label` string, required
        - `name` string, required
        - `arguments` string, required
        - `output` string, nullable
        - `error` string, nullable
        - `approval_request_id` string, nullable
        - `status` 'in_progress' | 'completed' | 'failed'
      - ResponseMcpApprovalRequest — A tool call waiting for the caller's `mcp_approval_response` on the next request.
        - `type` 'mcp_approval_request'
        - `id` string, required
        - `server_label` string, required
        - `name` string, required
        - `arguments` string, required
  - `parallel_tool_calls` boolean
  - `temperature` number, nullable
  - `tool_choice` union
    - 'none' | 'auto' | 'required'
    - ResponseToolChoiceFunction — Force a Responses API function tool by name.
      - `type` 'function'
      - `name` string, required
    - ToolChoiceMcp — Force a call to one MCP server's tools, or to one named tool of it.
      - `type` 'mcp'
      - `server_label` string, required
      - `name` string, nullable
  - `tools` union[]
    - union
      - ResponseFunctionTool — A Responses API function tool, whose definition is flat rather than nested.
        - `name` string, required
        - `description` string, nullable
        - `parameters` object, nullable
        - `strict` boolean, nullable
        - `type` 'function'
      - ResponseNamespaceTool — A Codex tool namespace containing client-executed functions.
        - `type` 'namespace'
        - `name` string, required
        - `description` string, nullable
        - `tools` ResponseFunctionTool[], required
          - `name` string, required
          - `description` string, nullable
          - `parameters` object, nullable
          - `strict` boolean, nullable
          - `type` 'function'
      - McpTool — Hosted tool: the tools of a remote MCP server, executed server-side. Follows the OpenAI Responses API `mcp` tool: the server's tools are listed when the request starts and offered to the model; a call runs against the server unless it needs the caller's approval first, in which case the turn ends with an approval request the caller answers on the next request. `headers` and `authorization` are credentials: they are never stored nor echoed back, so a continuation must declare the server again.
        - `type` 'mcp'
        - `server_label` string, required — Label identifying this server in tool calls
        - `server_url` string, nullable — URL of the server's Streamable HTTP endpoint
        - `connector_id` string, nullable — OpenAI service connectors are not supported
        - `server_description` string, nullable — Shown to the model beside the server's tools
        - `headers` object, nullable — HTTP headers sent to the server
        - `authorization` string, nullable — OAuth access token sent as a bearer token
        - `require_approval` union — Which tools need the caller's approval before running; defaults to all of them
          - 'always' | 'never'
          - McpApprovalFilter — Which of an MCP server's tools need the caller's approval before they run.
            - `always` McpToolFilter — Selects tools of an MCP server by name and/or by their read-only annotation. Shared by `allowed_tools` and the `require_approval` filters, as in the OpenAI Responses API.
              - …
            - `never` McpToolFilter — Selects tools of an MCP server by name and/or by their read-only annotation. Shared by `allowed_tools` and the `require_approval` filters, as in the OpenAI Responses API.
              - …
        - `allowed_tools` union — Tool names or a filter restricting the offer
          - string[]
          - McpToolFilter — Selects tools of an MCP server by name and/or by their read-only annotation. Shared by `allowed_tools` and the `require_approval` filters, as in the OpenAI Responses API.
            - `tool_names` string[], nullable — Tool names the filter matches
            - `read_only` boolean, nullable — Match tools whose `readOnlyHint` annotation equals this value
  - `top_p` number, nullable
  - `background` boolean
  - `max_output_tokens` integer, nullable
  - `max_tool_calls` integer, nullable
  - `previous_response_id` string, nullable
  - `reasoning` ResponseReasoningConfig
    - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable
    - `summary` 'auto' | 'concise' | 'detailed', nullable
    - `generate_summary` 'auto' | 'concise' | 'detailed', nullable
  - `service_tier` 'auto' | 'default' | 'flex' | 'scale' | 'priority'
  - `text` ResponseTextConfig
    - `format` union
      - ResponseTextFormatText
        - `type` 'text'
      - ResponseTextFormatJSONObject
        - `type` 'json_object'
      - ResponseTextFormatJSONSchema
        - `type` 'json_schema'
        - `name` string, required
        - `schema` object, required
        - `description` string, nullable
        - `strict` boolean, nullable
    - `verbosity` 'low' | 'medium' | 'high', nullable
  - `truncation` 'auto' | 'disabled'
  - `usage` ResponseUsage
    - `input_tokens` integer
    - `input_tokens_details` ResponseInputTokensDetails
      - `cached_tokens` integer
    - `output_tokens` integer
    - `output_tokens_details` ResponseOutputTokensDetails
      - `reasoning_tokens` integer
    - `total_tokens` integer
  - `metadata` object, nullable
  - `safety_identifier` string, nullable
  - `prompt_cache_key` string, nullable
  - `user` string, nullable
  - `hosted_tool_calls` union[]
    - union
      - SearchCorpusCallItem — Record of one server-side search execution.
        - `type` 'search_corpus_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `queries` string[]
        - `metadata_filters` MetadataFilter[], nullable
          - `key` string, required — Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - `value` union, required — Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any'
        - `store` string, nullable
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - GrepCallItem — Record of one server-side grep execution.
        - `type` 'grep_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `pattern` string, nullable
        - `targets` StoreChunkGrepTarget[], nullable
        - `case_sensitive` boolean
        - `metadata_filters` MetadataFilter[], nullable
          - `key` string, required — Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - `value` union, required — Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any'
        - `store` string, nullable
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - FilterChunksCallItem — Record of one server-side metadata-driven chunk listing.
        - `type` 'filter_chunks_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `metadata_filters` MetadataFilter[], nullable
          - `key` string, required — Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - `value` union, required — Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any'
        - `rank_by` string, nullable
        - `direction` 'asc' | 'desc'
        - `store` string, nullable
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - InspectMetadataCallItem — Record of one server-side metadata facets lookup.
        - `type` 'inspect_metadata_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `store` string, nullable
        - `facets` object, nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - GetChunksCallItem — Record of one server-side re-fetch of already-seen chunks.
        - `type` 'get_chunks_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `chunk_ids` string[]
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - StoreSearchCallItem — Deprecated `store_search_call` form, emitted for requests that declared the alias.
        - `type` 'store_search_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `queries` string[]
        - `metadata_filters` MetadataFilter[], nullable
          - `key` string, required — Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - `value` union, required — Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any'
        - `store` string, nullable
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - StoreGrepCallItem — Deprecated `store_grep_call` form, emitted for requests that declared the alias.
        - `type` 'store_grep_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `pattern` string, nullable
        - `targets` StoreChunkGrepTarget[], nullable
        - `case_sensitive` boolean
        - `metadata_filters` MetadataFilter[], nullable
          - `key` string, required — Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - `value` union, required — Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any'
        - `store` string, nullable
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - StoreListChunksCallItem — Deprecated `store_list_chunks_call` form, emitted for requests that declared the alias.
        - `type` 'store_list_chunks_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `metadata_filters` MetadataFilter[], nullable
          - `key` string, required — Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - `value` union, required — Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any'
        - `rank_by` string, nullable
        - `direction` 'asc' | 'desc'
        - `store` string, nullable
        - `results` object[], nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - MetadataFacetsCallItem — Deprecated `store_metadata_facets_call` form, emitted for requests that declared the alias.
        - `type` 'store_metadata_facets_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `store` string, nullable
        - `facets` object, nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
      - ListStoresCallItem — Record of one server-side store listing execution.
        - `type` 'list_stores_call'
        - `id` string, required
        - `status` 'in_progress' | 'completed' | 'failed'
        - `cursor` string, nullable
        - `stores` ListStoresResult[], nullable
          - `name` string, required
          - `description` string, nullable
          - `connectors` string[] — Providers of the connectors ingesting into this store, e.g. slack or notion
        - `has_more` boolean
        - `next_cursor` string, nullable
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
  - `hosted_tools` union[]
    - union
      - SearchCorpusTool — Hosted tool: semantic search over the caller's stores, executed server-side.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'search_corpus'
        - `filters` union — Optional filter conditions applied to every search
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
        - `score_threshold` number — Minimum similarity score threshold
        - `citations` boolean — Cite sources in the answer as <cite i="..."/> tags referencing result index fields
      - GrepTool — Hosted tool: regular-expression match over stores' chunks, executed server-side. grep runs the pattern against the literal chunk text — no embeddings, no reranker. Each call searches all pinned stores, or the store selected by the model when no stores are pinned, with one global result limit.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'grep'
        - `filters` union — Optional filter conditions applied to every grep
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
        - `citations` boolean — Cite sources in the answer as <cite i="..."/> tags referencing result index fields
      - FilterChunksTool — Hosted tool: metadata-driven listing of stores' chunks, executed server-side. No embeddings and no reranker: chunks are selected by metadata filters and optionally ordered globally by a numeric metadata field. Each call covers all pinned stores, or the store selected by the model when no stores are pinned.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'filter_chunks'
        - `filters` union — Optional filter conditions applied to every listing
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
        - `citations` boolean — Cite sources in the answer as <cite i="..."/> tags referencing result index fields
      - InspectMetadataTool — Hosted tool: metadata field/value overview of the caller's stores, executed server-side. Facets tell the model which metadata keys exist and what their values look like, so it can filter (`grep`, `filter_chunks`) and phrase queries against real values instead of guessing.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'inspect_metadata'
        - `filters` union — Optional filter conditions restricting the files the facets are computed over
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
      - GetChunksTool — Hosted tool: re-fetch of already-seen chunks by their `file_id:chunk_index` ids. The recovery half of the per-chunk payload clip: a chunk a search returned truncated can be re-read at a much larger budget. Configuration is the shared store scope only; the per-call id bound is the tool schema's own `maxItems`.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'get_chunks'
      - StoreSearchTool — Deprecated alias of `search_corpus`; parses to the same tool, echoed as sent.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'store_search'
        - `filters` union — Optional filter conditions applied to every search
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
        - `score_threshold` number — Minimum similarity score threshold
        - `citations` boolean — Cite sources in the answer as <cite i="..."/> tags referencing result index fields
      - StoreGrepTool — Deprecated alias of `grep`; parses to the same tool, echoed as sent.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'store_grep'
        - `filters` union — Optional filter conditions applied to every grep
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
        - `citations` boolean — Cite sources in the answer as <cite i="..."/> tags referencing result index fields
      - StoreListChunksTool — Deprecated alias of `filter_chunks`; parses to the same tool, echoed as sent.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'store_list_chunks'
        - `filters` union — Optional filter conditions applied to every listing
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
        - `citations` boolean — Cite sources in the answer as <cite i="..."/> tags referencing result index fields
      - MetadataFacetsTool — Deprecated alias of `inspect_metadata`; parses to the same tool, echoed as sent.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call (requires the list_stores tool)
          - union
            - string
            - string, uuid
        - `type` 'store_metadata_facets'
        - `filters` union — Optional filter conditions restricting the files the facets are computed over
          - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
            - `all` union[], nullable — List of conditions or filters to be ANDed together
              - …
            - `any` union[], nullable — List of conditions or filters to be ORed together
              - …
            - `none` union[], nullable — List of conditions or filters to be NOTed
              - …
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
          - union[]
            - union
              - …
      - ListStoresTool — Hosted tool: paginated listing of the caller's stores, executed server-side. Pair it with the store-scoped tools that are left unpinned, so the model can discover which stores it may name.
        - `type` 'list_stores'
        - `limit` integer — Number of stores returned per listing call
  - `tool_tickets` ToolTicket[]
    - `tool_call_id` string, required — ID of the tool call in `choices[].message.tool_calls` this covers
    - `ticket` string, required — Opaque token to send as the X-Mxbai-Tool-Ticket header
    - `expires_at` integer, required — Unix timestamp after which the ticket no longer redeems
  - `context_management` ContextManagementResult — Context edits applied while serving one request (Mixedbread extension). Only ever emitted non-empty: a request whose context was never edited carries no `context_management` object at all.
    - `applied_edits` union[], required
      - union
        - AppliedPruneContextEdit — Aggregate of the model's prune_context calls in one request.
          - `type` 'prune_context'
          - `calls` integer, required — Number of prune_context calls the model made in this request
          - `cleared_input_tokens` integer, required — Input tokens cleared from the model's context
        - AppliedTruncateToolResultEdit — One caller tool result shortened by the server's context-overflow recovery.
          - `type` 'truncate_tool_result'
          - `tool_call_id` string, required — ID of the tool call whose result was shortened
          - `cleared_input_tokens` integer, required — Input tokens cleared from the model's context
  - `title` string, nullable

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-10** `adde8ecfa74f` — 16 warning
  - removed the request property `tools/items/oneOf[subschema #10: StoreGrepTool]/max_num_results`
  - removed the request property `tools/items/oneOf[subschema #11: StoreListChunksTool]/max_num_results`
  - removed the request property `tools/items/oneOf[subschema #12: MetadataFacetsTool]/max_values_per_field`
  - removed the request property `tools/items/oneOf[subschema #4: SearchCorpusTool]/max_num_results`
  - …12 more
- **2026-09-05** `ea8d85b8caca` — 1 breaking, 10 warning, 8 info
  - added `#/components/schemas/ResponseMcpListTools, #/components/schemas/ResponseMcpCall, #/components/schemas/ResponseMcpApprovalRequest` to the `output/items/` response property `oneOf` list for the response status `200`
  - removed the optional property `hosted_tool_calls/items/oneOf[subschema #10: ListStoresCallItem]/reasoning_offset` from the response with the `200` status
  - removed the optional property `hosted_tool_calls/items/oneOf[subschema #1: SearchCorpusCallItem]/reasoning_offset` from the response with the `200` status
  - removed the optional property `hosted_tool_calls/items/oneOf[subschema #2: GrepCallItem]/reasoning_offset` from the response with the `200` status
  - …15 more
- …earlier changes not shown

[Full history](https://skmtc.dev/mixedbread/apis/mxbai-omni/changes/v1/responses/post.md)

---

[API](https://skmtc.dev/mixedbread/apis/mxbai-omni.md) · [All operations](https://skmtc.dev/mixedbread/apis/mxbai-omni/llms.txt) · [OpenAPI document](https://skmtc.dev/mixedbread/apis/mxbai-omni/revisions/adde8ecfa74f?raw)