Mixedbread

Create a Chat Completion

Create an OpenAI-compatible chat completion with optional client-executed function tools.

POST
/v1/chat/completions

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.

Authorization

ApiKeyAuth
headerAuthorizationBearer <token>

Api key to access Mixedbreads API

Request Body

application/json
  1. body

Completion parameters including messages and tools

messages*array<||||>

The conversation, or its new suffix when continuing a stored completion

Items1 <= items
model?Model

Public model ID. Defaults to toast-1

Default"toast-1"
tools?array<||||||||||>

Tools the model may call; the hosted tools are opt-in and run server-side for the completions that declare them

tool_choice?||||||||||
Default"auto"
response_format?|||

The shape of the answer: plain text, any JSON object, or JSON matching a schema. A JSON answer is grammar-constrained on the final generation; tool calls are unaffected

store?Store

Whether to persist this completion for later retrieval

Defaulttrue
previous_completion_id?|

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?array<||||>|Deprecated

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

terminal_tool_name?|Deprecated

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?Stream

Stream the completion as server-sent events

Defaultfalse
temperature?|null
top_p?|null
max_completion_tokens?|null
max_tokens?|

Deprecated alias of max_completion_tokens, honored when it is absent

max_tool_calls?|

Maximum number of server-handled tool calls (store tools and prune_context) executed for this completion; ignored when none are declared

context_management?|

Opt-in context editing (Mixedbread extension). Declaring the prune_context edit gives the model a tool to clear stale tool results as the conversation approaches the context window; accepted with any tool set, a no-op when nothing prunable accumulates

parallel_tool_calls?Parallel Tool Calls

Whether the model may call multiple tools in one turn; when false, at most one is honored

Defaulttrue
metadata?|null
include?array<string>|

Extra fields to include, e.g. search_corpus_call.results; unsupported values are ignored

Response Body

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

application/json
  1. response

A chat completion object, as returned by the API and persisted for retrieval.

id*Id
object?Object
Default"chat.completion"
created*Created
model*Model
choices*array<>
usage?|null
metadata?|null
title?|

Short display title of the conversation this completion belongs to (Mixedbread extension)

hosted_tool_calls?array<|||||||||>

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

context_management?|

Context edits applied while serving this request (Mixedbread extension); null when the context was never edited

tool_tickets?array<>

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.

transcript?array<||||>|

Complete stored conversation transcript when requested through include

Example Request
from openai import OpenAI

client = OpenAI(
    base_url="https://api.mixedbread.com/v1",
    api_key="YOUR_API_KEY",
)

completion = client.chat.completions.create(
    model="toast-1",
    messages=[
        {
            "role": "user",
            "content": "What is a search agent?",
        }
    ],
)

print(completion.choices[0].message.content)
Example Response
{
  "id": "chatcmpl_abc123",
  "object": "chat.completion",
  "created": 1786622400,
  "model": "toast-1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A search agent plans queries, gathers evidence with tools, and synthesizes an answer.",
        "tool_calls": null,
        "reasoning_content": null
      },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 19,
    "total_tokens": 34
  },
  "metadata": null,
  "title": "What is a search agent?"
}