---
title: "Create a chat completion"
method: POST
path: "/v1/chat/completions"
tags: ["chat"]
---

# Create a chat completion

`POST /v1/chat/completions`

Create a chat completion, optionally grounded in the caller's stores.

Supports the OpenAI Chat Completions API subset: a message list, function
tools, streaming via server-sent events, and persistence via `store`. A
request without hosted tools is one generation over exactly what was sent:
no instructions, tools, or turns are added. The `previous_completion_id`
groups stored turns into a conversation and restores the full model
context; callers normally send only the new suffix. (`previous_messages`
and `terminal_tool_name` are deprecated: resend the full edited history in
`messages` instead.)
Retrieval is opt-in: declare the hosted store tools (`store_search`,
`store_grep`, `store_list_chunks`, `store_metadata_facets`, `list_stores`)
in `tools` to let the model search, grep, filter, and read the caller's
stores server-side, scoped by each declaration. Those executions are
reported in the `hosted_tool_calls` extension field (and as extra streaming
chunks), with chunk results included only for the requested `include` keys.
A model call to a caller-declared function tool ends the completion with
`tool_calls` on the choice message (finish_reason `tool_calls`); execute the
functions and continue the conversation by appending the assistant message
and the matching `tool` messages to the next request.

## Request body

- CompletionCreateParams — Request body for POST /v1/chat/completions.
  - `messages` union[], required — The conversation, or its new suffix when continuing a stored completion
    - union
      - SystemMessage
        - `role` 'system', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
      - DeveloperMessage — Alias of the system role; forwarded to the provider as system instructions.
        - `role` 'developer', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
      - UserMessage
        - `role` 'user', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
      - AssistantMessageInput
        - `role` 'assistant', required
        - `content` union
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
        - `tool_calls` MessageToolCall[]
          - `id` string, required
          - `type` 'function'
          - `function` ToolCallFunction, required
            - `name` string, required
            - `arguments` string, required
        - `reasoning_content` string, nullable
        - `annotations` FileCitation[]
          - `type` 'file_citation'
          - `file_id` string, required
          - `filename` string, required
          - `index` integer, required
          - `chunk_id` string, required
          - `store_id` string, required
      - ToolMessage — Result of a function tool call, sent back by the caller.
        - `role` 'tool', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
        - `tool_call_id` string, required
  - `model` string — Public model ID. Defaults to toast-1
  - `tools` union[] — Tools the model may call; the hosted tools are opt-in and run server-side for the completions that declare them
    - 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 — Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks
      - 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 — Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks
      - 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 — Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks
      - 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 — Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks
      - 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 — Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks
      - 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 — Have the model cite its evidence inline; the answer ships with the markers removed and an annotations list of file_citation entries pointing at the cited chunks
      - 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
      - FunctionTool — Client-executed function tool, as in the OpenAI Chat Completions API.
        - `type` 'function'
        - `function` FunctionDefinition, required — Definition of a client-executed function tool, as in the OpenAI Chat Completions API. Any name is usable; hosted tool names are only reserved against the requests that declare that hosted tool (checked at the params level).
          - `name` string, required
          - `description` string, nullable
          - `parameters` object, nullable
          - `strict` boolean, nullable
  - `tool_choice` union
    - 'auto' | 'none' | 'required'
    - ToolChoiceFunction — Force a call to a specific function tool, as in the OpenAI Chat Completions API.
      - `type` 'function'
      - `function` ToolChoiceFunctionName, required
        - `name` string, required
    - 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'
    - ToolChoiceListStores — Force a call to the hosted list stores tool (Mixedbread extension).
      - `type` 'list_stores'
    - 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'
  - `store` boolean — Whether to persist this completion for later retrieval
  - `previous_completion_id` string, nullable — ID of a stored completion this one continues (Mixedbread extension). Groups turns into a conversation for listing and deletion, and always restores the previous completion's full model context, including hosted tool calls and results
  - `previous_messages` union[], nullable — Deprecated. Replacement for the previous completion's stored model context after client-side pruning. Send the full edited history in `messages` without `previous_completion_id` instead; the request is honored exactly as sent
    - union
      - SystemMessage
        - `role` 'system', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
      - DeveloperMessage — Alias of the system role; forwarded to the provider as system instructions.
        - `role` 'developer', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
      - UserMessage
        - `role` 'user', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
      - AssistantMessageInput
        - `role` 'assistant', required
        - `content` union
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
        - `tool_calls` MessageToolCall[]
          - `id` string, required
          - `type` 'function'
          - `function` ToolCallFunction, required
            - `name` string, required
            - `arguments` string, required
        - `reasoning_content` string, nullable
        - `annotations` FileCitation[]
          - `type` 'file_citation'
          - `file_id` string, required
          - `filename` string, required
          - `index` integer, required
          - `chunk_id` string, required
          - `store_id` string, required
      - ToolMessage — Result of a function tool call, sent back by the caller.
        - `role` 'tool', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
        - `tool_call_id` string, required
  - `terminal_tool_name` string, nullable — Deprecated and ignored. The stored transcript is never rewritten around a terminal tool call; the completion ends with the model's plain-text answer
  - `stream` boolean — Stream the completion as server-sent events
  - `temperature` number, nullable
  - `top_p` number, nullable
  - `max_completion_tokens` integer, nullable
  - `max_tokens` integer, nullable — Deprecated alias of max_completion_tokens, honored when it is absent
  - `max_tool_calls` integer, nullable — Maximum number of server-handled tool calls (store tools and prune_context) executed for this completion; ignored when none are declared
  - `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'
  - `parallel_tool_calls` boolean — Whether the model may call multiple tools in one turn; when false, at most one is honored
  - `metadata` object, nullable
  - `include` string[], nullable — Extra fields to include, e.g. search_corpus_call.results; unsupported values are ignored

## Response `200`

The generated chat completion, or a server-sent event stream of completion chunks

- ChatCompletion — A chat completion object, as returned by the API and persisted for retrieval.
  - `id` string, required
  - `object` 'chat.completion'
  - `created` integer, required
  - `model` string, required
  - `choices` ChatCompletionChoice[], required
    - `index` integer
    - `message` ChatCompletionMessage, required — The assistant message of one completion choice.
      - `role` 'assistant'
      - `content` string, nullable
      - `tool_calls` MessageToolCall[], nullable
        - `id` string, required
        - `type` 'function'
        - `function` ToolCallFunction, required
          - `name` string, required
          - `arguments` string, required
      - `reasoning_content` string, nullable
      - `annotations` FileCitation[], nullable
        - `type` 'file_citation'
        - `file_id` string, required
        - `filename` string, required
        - `index` integer, required
        - `chunk_id` string, required
        - `store_id` string, required
    - `finish_reason` 'stop' | 'tool_calls' | 'length'
    - `logprobs` unknown
  - `usage` CompletionUsage
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
    - `prompt_tokens_details` PromptTokensDetails — Breakdown of the prompt tokens, as in the OpenAI usage object.
      - `cached_tokens` integer — Prompt tokens served from the cache; part of prompt_tokens, not extra
    - `completion_tokens_details` CompletionTokensDetails — Breakdown of the completion tokens, as in the OpenAI usage object.
      - `reasoning_tokens` integer — Tokens of the hosted loop's narration; part of completion_tokens, not extra
  - `metadata` object, nullable
  - `title` string, nullable — Short display title of the conversation this completion belongs to (Mixedbread extension)
  - `hosted_tool_calls` union[] — Server-side hosted tool executions of this completion (Mixedbread extension); chunk results ride along only for requested include keys, e.g. search_corpus_call.results
    - 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
  - `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
  - `tool_tickets` ToolTicket[] — One short-lived ticket per client-executed tool call (Mixedbread extension). Send the matching ticket as the X-Mxbai-Tool-Ticket header on the store search or grep you run for that call, and it bills at the discounted agent rate. Each ticket redeems once.
    - `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
  - `transcript` union[], nullable — Complete stored conversation transcript when requested through include
    - union
      - SystemMessage
        - `role` 'system', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
      - DeveloperMessage — Alias of the system role; forwarded to the provider as system instructions.
        - `role` 'developer', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
      - UserMessage
        - `role` 'user', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
      - AssistantMessageOutput
        - `role` 'assistant', required
        - `content` union
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
        - `tool_calls` MessageToolCall[]
          - `id` string, required
          - `type` 'function'
          - `function` ToolCallFunction, required
            - `name` string, required
            - `arguments` string, required
        - `reasoning_content` string, nullable
        - `annotations` FileCitation[]
          - `type` 'file_citation'
          - `file_id` string, required
          - `filename` string, required
          - `index` integer, required
          - `chunk_id` string, required
          - `store_id` string, required
      - ToolMessage — Result of a function tool call, sent back by the caller.
        - `role` 'tool', required
        - `content` union, required
          - string
          - TextPart[]
            - `type` 'text'
            - `text` string, required
        - `tool_call_id` string, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-11** `ce3609b10ef1` — 4 info
  - added the new optional request property `messages/items/oneOf[subschema #4: AssistantMessage]/annotations`
  - added the new optional request property `previous_messages/anyOf[subschema #1]/items/oneOf[subschema #4: AssistantMessage]/annotations`
  - added the optional property `choices/items/message/annotations` to the response with the `200` status
  - added the optional property `transcript/anyOf[subschema #1]/items/oneOf[subschema #4: AssistantMessage]/annotations` to the response with the `200` status
- **2026-09-10** `adde8ecfa74f` — 8 warning
  - removed the request property `tools/items/oneOf[subschema #1: SearchCorpusTool]/max_num_results`
  - removed the request property `tools/items/oneOf[subschema #2: GrepTool]/max_num_results`
  - removed the request property `tools/items/oneOf[subschema #3: FilterChunksTool]/max_num_results`
  - removed the request property `tools/items/oneOf[subschema #4: InspectMetadataTool]/max_values_per_field`
  - …4 more
- …earlier changes not shown

[Full history](https://skmtc.dev/mixedbread/apis/mxbai-omni/changes/v1/chat/completions/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/ce3609b10ef1?raw)