---
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 over 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`. The
caller sends the full conversation on every call; `previous_completion_id`
groups stored turns into a conversation and restores the full model
context — when the request's messages extend the stored conversation
unchanged, the model also sees the previous turns' hosted tool calls and
results, while an edited history is honored exactly as sent. Server-side,
the model may search, grep, filter, and read the caller's stores as
needed; 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.
Retrieval is active by default and scoped by the store-tool configurations;
disable a tool by declaring it with `enabled: false`. 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 so far; the caller carries the full history every call
    - 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
      - 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, nullable — Accepted for OpenAI SDK compatibility and ignored; the platform selects the model
  - `tools` union[] — Tools the model may call; hosted tools without required configuration are active by default and can be disabled by declaring them with enabled=false
    - union
      - StoreSearchTool — Hosted tool: semantic search over the caller's stores, executed server-side.
        - `enabled` boolean — Set to false to disable the tool for this completion
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call, an empty list disables the tool
          - union
            - string
            - string, uuid
        - `type` 'store_search'
        - `max_num_results` integer — Number of chunks returned per search call
        - `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 — Hosted tool: regular-expression match over a store's chunks, executed server-side. grep runs the pattern against the literal chunk text — no embeddings, no reranker. It covers exactly one store per call, so with several pinned stores the model picks which of them to grep.
        - `enabled` boolean — Set to false to disable the tool for this completion
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call, an empty list disables the tool
          - union
            - string
            - string, uuid
        - `type` 'store_grep'
        - `max_num_results` integer — Number of chunks returned per grep call
        - `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 — Hosted tool: metadata-driven listing of a store's chunks, executed server-side. No embeddings and no reranker: chunks are selected by metadata filters and optionally ordered by a numeric metadata field. It covers a single store per call, so with several pinned stores the model picks which one to list.
        - `enabled` boolean — Set to false to disable the tool for this completion
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call, an empty list disables the tool
          - union
            - string
            - string, uuid
        - `type` 'store_list_chunks'
        - `max_num_results` integer — Number of chunks returned per listing call
        - `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 — 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 (`store_grep`, `store_list_chunks`) and phrase queries against real values instead of guessing.
        - `enabled` boolean — Set to false to disable the tool for this completion
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call, an empty list disables the 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
              - …
        - `max_values_per_field` integer — Number of representative values reported per metadata field
      - ListStoresTool — Hosted tool: paginated listing of the caller's stores, executed server-side. Active by default; declare it with enabled=false to turn it off.
        - `type` 'list_stores'
        - `enabled` boolean — Set to false to disable the tool for this completion
        - `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.
          - `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
    - ToolChoiceStoreSearch — Force a call to the hosted store search tool (Mixedbread extension).
      - `type` 'store_search'
    - ToolChoiceListStores — Force a call to the hosted list stores tool (Mixedbread extension).
      - `type` 'list_stores'
    - ToolChoiceStoreGrep — Force a call to the hosted store grep tool (Mixedbread extension).
      - `type` 'store_grep'
    - ToolChoiceStoreListChunks — Force a call to the hosted list chunks tool (Mixedbread extension).
      - `type` 'store_list_chunks'
    - ToolChoiceMetadataFacets — Force a call to the hosted metadata facets tool (Mixedbread extension).
      - `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 restores the full model context: when messages extend the stored conversation unchanged, the model also sees the previous turns' hosted tool calls and results, not just the text. An edited history is honored exactly as sent
  - `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 hosted retrieval calls executed for this completion
  - `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. store_search_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
    - `finish_reason` 'stop' | 'tool_calls' | 'length'
    - `logprobs` unknown
  - `usage` CompletionUsage
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
  - `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. store_search_call.results
    - union
      - StoreSearchCallItem — Record of one server-side store search execution.
        - `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` StoreSearchResult[], nullable
          - `index` integer, nullable
          - `store_id` string, required
          - `file_id` string, required
          - `chunk_index` integer, required
          - `filename` string, nullable
          - `mime_type` string, nullable
          - `score` number, required
          - `text` string, nullable
          - `ocr_text` string, nullable
          - `transcription` string, nullable
          - `summary` string, nullable
          - `metadata` unknown
          - `generated_metadata` unknown
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
        - `reasoning_offset` integer, nullable
      - StoreGrepCallItem — Record of one server-side grep execution.
        - `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` StoreSearchResult[], nullable
          - `index` integer, nullable
          - `store_id` string, required
          - `file_id` string, required
          - `chunk_index` integer, required
          - `filename` string, nullable
          - `mime_type` string, nullable
          - `score` number, required
          - `text` string, nullable
          - `ocr_text` string, nullable
          - `transcription` string, nullable
          - `summary` string, nullable
          - `metadata` unknown
          - `generated_metadata` unknown
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
        - `reasoning_offset` integer, nullable
      - StoreListChunksCallItem — Record of one server-side metadata-driven chunk listing.
        - `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` StoreSearchResult[], nullable
          - `index` integer, nullable
          - `store_id` string, required
          - `file_id` string, required
          - `chunk_index` integer, required
          - `filename` string, nullable
          - `mime_type` string, nullable
          - `score` number, required
          - `text` string, nullable
          - `ocr_text` string, nullable
          - `transcription` string, nullable
          - `summary` string, nullable
          - `metadata` unknown
          - `generated_metadata` unknown
        - `error` ToolCallError — Machine-readable reason a hosted tool call failed (Mixedbread extension).
          - `code` 'permission_denied' | 'invalid_arguments' | 'server_error', required
          - `message` string, required
        - `reasoning_offset` integer, nullable
      - MetadataFacetsCallItem — Record of one server-side metadata facets lookup.
        - `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
        - `reasoning_offset` integer, nullable
      - 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
        - `reasoning_offset` integer, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/mixedbread/apis/mxbai-omni.md) · [All operations](https://skmtc.net/mixedbread/apis/mxbai-omni/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixedbread/mxbai-omni/revisions/d47e1d852549/schema)