---
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`. 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.
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 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 — 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
      - StoreSearchTool — 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
          - 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.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call
          - 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.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call
          - 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.
        - `store_identifiers` union[], nullable — IDs or names of the stores the tool runs against; omit to let the model pick a store per call
          - 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. 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.
          - `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
    - `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
  - `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
  - `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

## 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/e5ddc69af941/schema)