Responses API

The Mixedbread Responses API is an OpenAI Responses-compatible endpoint for Mixedbread specialized models and agentic workflows. It provides a simpler input and output model than Chat Completions, supports stored multi-turn conversations, and works with client-executed function tools.

You can use the OpenAI SDK by changing base_url and api_key, then selecting a model from the supported models. For message-based integrations, see the Chat Completions API.

PrerequisiteLink to section

Get a Mixedbread API key from the API Keys page. You can install the OpenAI SDK or use cURL directly.

pip install openai

Make your first requestLink to section

Point base_url to Mixedbread, use your Mixedbread API key, and select one supported model. Pass a string or a list of input items to input.

Create a response

from openai import OpenAI

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

response = client.responses.create(
    model="toast-1",
    input="What is a search agent?",
)

print(response.output_text)

The Python and TypeScript SDKs expose the generated text through response.output_text. On the wire, generated messages, reasoning narration, and function calls are separate items in output.

OpenAI compatibilityLink to section

Mixedbread accepts the OpenAI Responses shape for supported fields. The tables below cover important request and response behavior.

Request fieldsLink to section

Field or value	Behavior
`previous_response_id`	Continues a stored response without resending its earlier input items. The new response must also use `store: true` to continue the chain later.
Function definitions in `tools`	Gives the model client-executed functions it can call. Responses function definitions use a flat shape with `name`, `description`, `parameters`, and `strict`.
`tool_choice`	Lets the model choose automatically, prevents tool calls, requires a tool call, or forces a named function.
`store`	Defaults to `true`. Set it to `false` to enable zero data retention. Response content is not retained, and no retrievable response is created. Operational model and token metadata is still recorded.

Response fieldsLink to section

Field	Behavior
`output`	Contains generated messages, reasoning narration, and client function calls in emission order.
`output_text`	SDK convenience property that joins the generated text from message output items.
`title`	Returns the generated title of a stored conversation.

Mixedbread currently supports text input and output, client-executed function tools, and streaming. Background responses, automatic context compaction or truncation, structured text formats, and multimodal input are not supported. Unsupported options return a validation error instead of being ignored.

See the advertised request and response fields in the API reference.

Continue a conversationLink to section

Responses are stored by default. Pass the previous response ID with only the new input to continue the conversation. Replace resp_123 with the id returned by the previous request.

Continue a response

response = client.responses.create(
    model="toast-1",
    input="When should I use one?",
    previous_response_id="resp_123",
)

print(response.output_text)

Set store=False when you do not need retrieval or continuation. Stored responses can be retrieved with client.responses.retrieve(response.id), and their input items can be listed with client.responses.input_items.list(response.id).

Connect your own toolsLink to section

Function tools let Toast 1 request data or actions from your application. The model returns a function_call output item with JSON-encoded arguments. Execute the function in your application, then send a function_call_output item with the same call_id to receive the final answer.

Connect a search function

import json

from openai import OpenAI


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


def search_documents(query: str) -> list[dict[str, str]]:
    return [
        {
            "title": "Search agents",
            "text": f'Search agents plan queries like "{query}", inspect evidence, and synthesize an answer.',
        }
    ]


tools = [
    {
        "type": "function",
        "name": "search_documents",
        "description": "Search the application's documents for relevant passages.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "The search query.",
                }
            },
            "required": ["query"],
        },
        "strict": False,
    }
]

response = client.responses.create(
    model="toast-1",
    input="What is a search agent? Use search_documents.",
    tools=tools,
    tool_choice={"type": "function", "name": "search_documents"},
    parallel_tool_calls=False,
)

tool_call = next(item for item in response.output if item.type == "function_call")
result = search_documents(**json.loads(tool_call.arguments))

final_response = client.responses.create(
    model="toast-1",
    previous_response_id=response.id,
    input=[
        {
            "type": "function_call_output",
            "call_id": tool_call.call_id,
            "output": json.dumps(result),
        }
    ],
    tools=tools,
    tool_choice="none",
)

print(final_response.output_text)

The example forces one call for a deterministic first turn, executes the application-owned search function, and sets tool_choice="none" on the second turn so Toast 1 produces the answer from the returned results. In production, the function can call any search engine, database, or internal API.