Create a Response

POST/v1/responses

Authorization

Authorizationstringrequired

Your Mixedbread API key as a bearer token. Format: `Bearer YOUR_API_KEY`.

Request Body

modelstringdefault: toast-1

Public model ID.

instructionsstring | null

System-level instructions for this response. New instructions replace instructions from a previous response.

tool_choicestring | objectdefault: auto

Controls tool selection. Use `auto`, `none`, `required`, or force a function with `{ type: 'function', name: '...' }` or a hosted tool with its type. With hosted tools it applies to the first model turn; later turns of the server loop use `auto`.

max_tool_callsinteger | nulldefault: 16

Maximum server-executed tool calls (hosted tools and `prune_context`) for this response. Ignored when none are declared.

Constraints

•Minimum: 1

includearray | null

Extra fields to include on hosted call items, e.g. `search_corpus_call.results`. Unsupported values are ignored.

storebooleandefault: true

Persist the response so it can be retrieved and continued later. Set to `false` to prevent response content from being stored for later retrieval.

previous_response_idstring | null

ID of a stored response to continue. Send only the new input for the next turn.

streambooleandefault: false

Return semantic server-sent events such as `response.output_text.delta` and a terminal `response.completed` event.

temperaturenumber | null

top_pnumber | null

max_output_tokensinteger | null

Maximum tokens to generate for the response.

Constraints

•Minimum: 16

parallel_tool_callsbooleandefault: true

Allow the model to request multiple function calls in one response.

metadataobject | null

Up to 16 string key-value pairs. Keys may contain up to 64 characters and values up to 512 characters.

Response Body

idstringrequired

Unique response ID, prefixed with `resp_`.

objectstringrequireddefault: response

created_atnumberrequired

Unix timestamp when the response was created.

completed_atnumber | null

Unix timestamp when generation completed.

statusenumrequired

errorobject | null

Error code and message when the response failed.

incomplete_detailsobject | null

Why the response is incomplete: `max_output_tokens`, or for hosted runs that ended without a plain-text answer, `max_tool_calls` or `context_window`.

modelstringrequired

The stable public model ID, `toast-1`.

parallel_tool_callsboolean

Whether parallel function calls were allowed.

tool_choicestring | object

Function selection mode used for the response.

toolsarray

Tool definitions configured for the response.

hosted_tool_callsarray

Server-executed tool calls of a hosted run, in execution order. Each item carries its call `type` (e.g. `search_corpus_call`), `id`, `status`, an `error` when it failed, and the call's arguments echoed as fields named for the tool (`queries` for a search, `pattern` for a grep); chunk `results` ride along only for requested `include` keys.

max_output_tokensinteger | null

previous_response_idstring | null

The previous response continued by this response.

usageobject | null

Input, output, cached, reasoning, and total token counts. `output_tokens_details.reasoning_tokens` reports the tokens spent on model reasoning; `0` for `toast-1`.

metadataobject | null

Metadata copied from the request.

titlestring | null

Short display title for the stored conversation.

Request

POST/v1/responses

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)

Response

JSON

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1786622400,
  "status": "completed",
  "completed_at": 1786622401,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "model": "toast-1",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "text": "A search agent plans queries, gathers evidence with tools, and synthesizes an answer.",
          "logprobs": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "temperature": null,
  "tool_choice": "auto",
  "tools": [],
  "top_p": null,
  "background": false,
  "max_output_tokens": null,
  "previous_response_id": null,
  "reasoning": null,
  "service_tier": "default",
  "text": null,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 15,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 19,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 34
  },
  "metadata": null,
  "safety_identifier": null,
  "prompt_cache_key": null,
  "user": null,
  "title": "What is a search agent?"
}

Stored response lifecycle

Responses created with store: true can also use the OpenAI-compatible retrieve, delete, and input-items endpoints. These operations use the same REST paths and OpenAI SDK method names. Use the Mixedbread base URL and API key shown in the examples above.

Operation	REST endpoint	Python	TypeScript	Supported query parameters
Retrieve a response	`GET /v1/responses/{response_id}`	`client.responses.retrieve(response_id)`	`client.responses.retrieve(responseId)`	`stream`, `starting_after`
Delete a response	`DELETE /v1/responses/{response_id}`	`client.responses.delete(response_id)`	`client.responses.delete(responseId)`	None
List input items	`GET /v1/responses/{response_id}/input_items`	`client.responses.input_items.list(response_id)`	`client.responses.inputItems.list(responseId)`	`limit`, `order`, `after`

Mixedbread supports the OpenAI lifecycle shape for text messages and client-executed function items. OpenAI options or item types not documented on this page are not supported. Deleting a stored response also deletes its persisted conversation chain.