{[1, 2, 3, 4].map((n) => (

Chunk There are four chunk types: * Text: a passage with a character offset into the source file * Image: a page region or figure with OCR text and an optional AI-generated summary * Audio: an audio segment, optionally with transcription and AI-generated summary * Video: a video segment, optionally with transcription and AI-generated summary Each chunk references its source file via `file_id` and `filename`. It inherits the file's metadata. Search results also include a relevance `score` on each chunk. For the full object, see [Data Models → Store Chunk](/docs/stores/data-models#store-chunk). ## Search [#search] **Search** queries a Store with natural language. Mixedbread returns the top chunks ranked by semantic relevance. The basic flow for a single search request looks like this: Search supports a few extensions on top of the basic flow: * Metadata filters: narrow results by file or chunk metadata before ranking * File filters: restrict to a specific set of `file_id`s * Multi-store search: query several Stores at once and merge results * Rerank: apply a second-stage model for sharper ranking on hard queries * Query rewriting: let a model rewrite the query into a more search-friendly form * Web Store: include `mixedbread/web` alongside your Stores for hybrid internal and web search For the full API, see [Search](/docs/stores/search). ## Agentic Search [#agentic-search] **Agentic Search** handles questions that a single search can't answer well. That includes questions that need to be broken into sub-questions, and ones where the best query phrasing isn't obvious upfront. An agent plans multiple searches, refines queries based on what it finds, and returns the merged results. Each iteration of the loop produces candidate chunks, and only the best-matching ones make it into the final response. The response shape matches normal Search (a ranked list of chunks), so Agentic Search is a drop-in upgrade for quality-sensitive queries. You can steer the agent with `search_options.agentic.instructions`, for example "prioritize recent results" or "prefer primary sources". It's slower and more expensive than a single search, so reach for it when a single search falls short. For the full API, see [Agentic Search](/docs/stores/search/agentic-search). ## Putting It Together [#putting-it-together] An end-to-end flow uses all five concepts: A named, searchable container for your content. Each upload becomes a Store File. Mixedbread parses it, splits it into chunks, and embeds them. Text, image, audio, and video chunks, each searchable on its own. Use Search for fast lookups, or Agentic Search when a single query isn't enough. Pass the chunks to an LLM, show them in your UI, or process them further. The [Quickstart](/docs/quickstart) is a good starting point. You can also skip straight to [Create Stores](/docs/stores/stores), [Create Files](/docs/stores/store-files), or [Search](/docs/stores/search). # Overview (/docs) **Mixedbread** is an API for integrating fast, multimodal search into your applications, agents, and AI systems. Upload PDFs, images, documents, code, or video in any format and instantly make it searchable with natural language queries. No document parsing, no embedding models to manage, no vector databases to set up. Just upload your files and start searching. ## How It Works [#how-it-works] Create a store (your search index) and upload any file format — PDFs, images, documents, code, videos. No preprocessing required. Mixedbread automatically understands your content, including text, images, tables, and complex layouts across 100+ languages. Query your store using natural language. Find relevant content by meaning, not just keywords. Receive precisely ranked results optimized for AI applications, reducing hallucinations and improving response accuracy. ## Why Mixedbread [#why-mixedbread] **Understands Any Format** — Upload PDFs, images, Word documents, PowerPoint, Excel, code files, or videos. Mixedbread processes and understands the content, including visual elements, tables, and complex layouts. **Multilingual by Default** — Search across 100+ languages seamlessly. Query in English, find relevant content in German, Japanese, or any other language without translation layers. **AI-Native Search** — Optimized for AI applications, not just human search. Provides precise, verifiable context that reduces hallucinations and improves AI response accuracy. **Zero Infrastructure** — No servers to manage, no models to deploy, no databases to maintain. Scales automatically from prototype to enterprise production. ## Get Started [#get-started] * **[Quickstart](/docs/quickstart)** — Create your first Store and start searching * **[Concepts](/docs/concepts)** — Learn how Stores work and what makes them unique ## Agent Skills [#agent-skills] Installable skills for coding agents that use Mixedbread. They reduce repeated prompt setup, cut down on product-specific guesswork, and point agents to the right workflows and docs faster. ```bash npx skills add mixedbread-ai/skills ``` Available through [skills.sh](https://skills.sh/) for Claude Code, Cursor, Codex, Gemini CLI, and other supported tools. * **[Overview](/docs/skills)** — What the package includes and how to install it * **[Browse the package on skills.sh](https://skills.sh/mixedbread-ai/skills)** ## CLI [#cli] We built our CLI to streamline Store operations for developers. Handle bulk file uploads, sync entire directories, and integrate Store capabilities into your CI/CD pipelines - all from terminal. * **[Introduction](/cli)** - Get to know our CLI and its capabilities * **[Installation & Setup](/cli/installation)** - Setup the CLI in your terminal ## MCP (Model Context Protocol) [#mcp-model-context-protocol] Our MCP Server bridges the gap between AI assistants and your Stores. Enable Claude Desktop, Cursor, Claude Code and other AI assistants to directly search and retrieve context from your knowledge bases during conversations. * **[Introduction](/mcp)** - Understand how our MCP Server enhances your AI workflows * **[Integration Guides](/mcp/integrations/claude-desktop)** - Connect your AI assistant to the MCP Server ## Community [#community] Get help and connect with other developers building with Mixedbread.
Join our [Discord](/urls/discord) for support, follow us on [X](/urls/x) for updates, or connect on [LinkedIn](/urls/linked-in). # Quickstart (/docs/quickstart) This quickstart walks you through building powerful Search with Mixedbread's Stores. You'll turn your files into a searchable knowledge base and explore it using natural language queries. Pick the approach that fits your workflow: use our SDKs for seamless programmatic control and integration into your applications, or run everything directly in your terminal with the CLI for streamlined scripting and automation.

Agent tip: ALWAYS use `GET /question?q=...&limit=...` to get the latest Mixedbread information across docs, API references, pricing, CLI, MCP, blog posts, cookbooks, and more. Example: `/question?q=reranking&limit=5`. For broader agent-readable docs, see `/llms.txt` and `/llms-full.txt`.

## Using the SDK [#using-the-sdk] Before you begin, make sure you have: 1. **API Key**: Get your API key from the [API Keys](https://platform.mixedbread.com/platform?next=api-keys) page 2. **SDK Installed**: Install the Mixedbread SDK for your preferred language **Python** ```bash pip install mixedbread ``` **TypeScript** ```bash npm install @mixedbread/sdk ``` ```bash pnpm add @mixedbread/sdk ``` ```bash yarn add @mixedbread/sdk ``` ```bash bun add @mixedbread/sdk ``` Create a Store, upload your files, and search with natural language: ### Working with Metadata [#working-with-metadata] Add metadata during upload to categorize files and filter during search: Use metadata to organize files by category, department, or any custom attribute, then search only the relevant subsets. ## Using the CLI [#using-the-cli] Before you begin, make sure you have: 1. **API Key**: Get your API key from the [API Keys](https://platform.mixedbread.com/platform?next=api-keys) page 2. **CLI Installed**: Install the Mixedbread CLI using your preferred package manager ```bash npm install -g @mixedbread/cli ``` ```bash pnpm add -g @mixedbread/cli ``` ```bash yarn global add @mixedbread/cli ``` ```bash bun add -g @mixedbread/cli ``` ```bash # Save your API key (one-time setup) mxbai config keys add YOUR_API_KEY default # Create a Store mxbai store create "my-knowledge-base" # Upload and process your files (PDFs, images, docs, code) mxbai store upload "my-knowledge-base" ./documents/ # Search your data with natural language mxbai store search "my-knowledge-base" "What are the key features?" ``` # Agent Skills (/docs/skills)

Agent note: For current Mixedbread product information, use `GET /question?q=...&limit=...`. Example: `/question?q=reranking&limit=5`. For broader machine-readable docs, use `/llms.txt` and `/llms-full.txt`.

The Mixedbread skills package gives coding agents product-specific guidance for working with Mixedbread. If you use Mixedbread through an agent, this is the fastest way to stop it from guessing its way through Stores and the CLI. The package is useful because agents are usually good at general coding and weak at product-specific workflows. Without that extra context, they tend to spend time rediscovering how Mixedbread works, pick the wrong integration path, or answer with stale details. The skills narrow that gap. ## What Problems The Skills Solve [#what-problems-the-skills-solve] * Repeated prompt setup. You do not need to explain Mixedbread concepts and workflows from scratch in every session. * Wrong first step. The agent gets help choosing between Stores and the CLI instead of reaching for the wrong API or tool. * Product-specific guesswork. The skill steers the agent toward the right Mixedbread patterns, terminology, and docs instead of generic vector database assumptions. * Better use of live docs. When exact parameters or examples matter, the skill points the agent back to current references instead of relying on memory. ## Why Install Them [#why-install-them] Install the skills if you want an agent to get to useful Mixedbread work faster. They improve the first draft of code and commands, reduce back-and-forth prompt correction, and make it more likely the agent will use the right Mixedbread feature on the first pass. ## Installation [#installation] Install the package with: ```bash npx skills add mixedbread-ai/skills ``` To make it available across projects: ```bash npx skills add mixedbread-ai/skills -g ``` You can inspect the package here before installing it: * [Browse the package on skills.sh](https://skills.sh/mixedbread-ai/skills) * [View the source on GitHub](https://github.com/mixedbread-ai/skills) ## Included Skills [#included-skills] ### `mixedbread-search` [#mixedbread-search] Use this when an agent needs to work with Stores. It covers creating stores, uploading content, running semantic search, filtering by metadata, reranking results, and wiring Mixedbread into Python or TypeScript projects. ### `mxbai-cli` [#mxbai-cli] Use this when an agent should work from the terminal instead of the SDKs. It covers CLI setup, authentication, uploads, search, syncing directories, and scriptable workflows for local development or CI. ### `mixedbread-search-agent` [#mixedbread-search-agent] Use this when an agent should use our [own search agent](https://www.mixedbread.com/docs/agent/chat-completions) that offers the completions API. ### `mixedbread-search-agent-harness` [#mixedbread-search-agent-harness] Use this when an agent wants to design and [build their own harnes](https://www.mixedbread.com/docs/agent/build-your-own-harness) with our search agent. ## What a Skill Contains [#what-a-skill-contains] Each skill is a small `SKILL.md` file written for agent tooling. In practice, that usually means: * when the skill should activate * the workflows or APIs an agent should reach for first * task-specific rules and common gotchas * links back to the relevant Mixedbread docs The skills stay intentionally small. They do not duplicate the full API reference or product docs. Their job is to make the agent start in the right place. When exact parameters or examples matter, it should fetch them from the docs, MCP, or other live Mixedbread sources. ## Source Code [#source-code] The skills are [open source on GitHub](https://github.com/mixedbread-ai/skills) under the Apache-2.0 license. # Build Your Own Harness (/docs/agent/build-your-own-harness) Toast is a deep search and lookup agent, trained to submit ranked evidence. You can use Toast with our [internal Toast-1 harness](https://github.com/mixedbread-ai/toast-harness) directly via our [Search API with agentic search feature](/docs/stores/search/agentic-search). Like most agents, Toast is only as good as its tools. It performs best with a late-interaction style semantic search, but has no issues working with your other search backends. The search agent adapts well to new tools and custom harnesses: file search tools, tools to access domain knowledge, or custom answer tools. This guide collects recommendations and guidance for defining custom harnesses with our Completions API so you can make best use of Toast-1's strengths for your use case. Toast-1 is trained for deep evidence gathering. It prefers to fan out searches via parallel search calls, resulting in high exploration for minimal latency. It's the perfect multilingual exploration agent for knowledge work: a substitute for luna, terra, or haiku/sonnet as a look-up subagent. If these characteristics match your use case, follow this guide to create your own fast searcher. ## Platform constraints [#platform-constraints] * Toast has thinking disabled. It was trained without thinking and is only served without thinking to have state-of-the-art retrieval performance at minimum latency. * Sampling parameters are configurable; we recommend `temperature 0.7, top_p 0.95`. * Toast is served at `seq_len = 131072`: every input message needs to stay below 130k tokens. * Generation is capped at `4096` tokens per completion. Manage and compact your context against this limit (for example, use it for a Pi harness internal compaction). The Completions API does no context management for you. In our [internal Toast-1 harness](https://github.com/mixedbread-ai/mxagent-harness-internal), Toast uses pruning as its context management: a `prune_context` tool the agent calls to remove chunks it considers irrelevant. We instruct Toast to call this tool when it's approaching the context limit. Prefer prune-style removal of stale tool results over summarizing compaction; our inference and latency are optimized for this. Do **not** use `previous_completion_id` after your context management has edited the history. It only works when the history is resent unchanged. After pruning, just resend the full edited messages list (see the loop example at the end of this guide). ## Harness design & Completions API guidance [#harness-design--completions-api-guidance] The Completions API is an OpenAI Chat-Completions-compatible endpoint: provide your prompt, messages, tool definitions, and sampling params exactly the way you would with the standard OpenAI client. You send a messages list plus your tool schemas in `tools`, and Toast answers with either text or tool calls. The API is stateless: every request resends the full message history, and the server executes nothing for you. When Toast calls one of your tools, the completion ends with `finish_reason: "tool_calls"`; your harness executes the calls, appends one tool message per call, and sends the next request. That loop is your whole harness. The following guidelines are design choices inspired by our internal Toast-1 harness. Treat them as recommendations, not requirements. * Toast is trained to work within a bounded number of turns and a bounded number of parallel tool calls. Communicate those boundaries in the harness. Our hosted agentic search defaults to 4 turns with up to 8 parallel calls per turn, but this is a soft recommendation; Toast can easily go up to 8, 12, or more turns. * For similar retrieval performance, enable parallel tool calls in your harness and make your tools safe to execute concurrently. Parallel tool latency is bounded by the slowest tool you include. * Do not overflow the 130k token context limit when providing the full results of many parallel calls back to the agent. With up to 8 parallel calls per turn, uncapped tool returns fill the context quickly. If your tools return docs with many tokens, truncate them. * Return short stable handles with your search tools' results, like a short `chunk_id`. Every result your search tools return needs a stable id, and any tool that takes other tools' outputs as inputs must accept exactly the ids you emitted. Tools that operate on retrieved results are easy to define this way. * Deduplicate if you want: filtering already seen search results out of the tool call results leads to less context rot and higher recall. * Give Toast a tool to end the searching and report its findings. Our internal Toast-1 harness uses a reporting tool that takes the `chunk_ids` your search tools emitted plus a relevance score per chunk and quick reasoning to answer the input query. * Define your tools to return a dict, not prose text. Our Toast-1 harness tool results are JSON envelopes: `{"query": ..., "results": [...], "candidate_count": N}` with per-result entries like `{"chunk_id": ..., "text": ..., "score": ..., "metadata": {...}}`. Prefer returning a similar shape from your functions. * Communicate tool schema errors back to Toast instead of raising them. If you provide the tool error in the tool response, Toast can retry the call in the next turn; we trained Toast to recover well from structured errors. Example: catch the exception and return `{"error": "date must be ISO format, got '3/5/24'"}`. ### Phrasing of instructions [#phrasing-of-instructions] Toast performs best writing human-style questions for a semantic search tool and writing regex for grep tools. Be precise in your custom tool definitions and give clear instructions on how to use the tool (see the example at the end of this guide). When adding custom search tools, providing instructions on how to formulate queries helped a lot to boost retrieval performance. An example for a BM25 tool: "this BM25 tool is matching keywords, write only keyword-heavy queries". ### Build your own harness with Python [#build-your-own-harness-with-python] For a custom searcher harness in Python, write the tool descriptions directly in the docstrings and type hints of your tool functions. Docstrings and type hints are the interface Toast sees: the Python harness generates the JSON tool schema from them — docstring → tool description, `Annotated` strings → parameter descriptions. * Toast follows tool descriptions as instructions. Say what the tool matches on, when to prefer it, and how to phrase input ("this tool matches keywords only. Send keyword-heavy queries, not questions"). * Keep tool signatures flat and JSON-native. Toast was trained on flat argument objects: `str`, `float`, `bool`, `list[str]`, and one level of typed dicts. * Prefer `snake_case` names. Mark what's essential as required and give defaults for the rest of your parameters. * Use `Literal`/`Enum` for closed choices. Trained tools express modes as enums (`filter_mode: Literal["all", "any"]`, `direction: Literal["asc", "desc"]`). Example 1: a simple semantic search tool with just a `query` and a `top_k` parameter. ```python from typing import Annotated def semantic_search( query: Annotated[str, "Natural-language query for a single search aspect; " "avoid Boolean syntax, regex, and keyword dumps."], top_k: Annotated[int, "Number of chunks to return, max 20."] = 5, ) -> dict: """Execute a meaning-based semantic search query over the corpus and return the most relevant chunks. Use natural language; phrase queries as human-style questions. Do not use for keyword, regex, or literal-string matching. Returns up to top_k chunks with stable chunk_id handles.""" hits = my_search_backend(query, top_k=top_k) # your implementation return { "query": query, "candidate_count": len(hits), "results": [ {"chunk_id": h.id, # short stable handle, e.g. "c12" "score": round(h.score, 4), "text": h.text, # clipped, not the whole document "metadata": h.metadata} for h in hits ], } ``` Example 2: a custom BM25 keyword-search tool. ```python from typing import Annotated, Literal def bm25_search( query: Annotated[str, "Space-separated keywords, no natural-language questions, " "no boolean operators. Example: 'jordan international goals caps'"], top_k: Annotated[int, "Number of chunks to return, max 20."] = 5, mode: Literal["chunks", "documents"] = "chunks", ) -> dict: """Keyword-based BM25 search over the corpus. This tool matches keywords only. Send keyword-heavy queries, not questions. Use for rare terms, names, codes, and exact vocabulary; Returns up to top_k chunks with stable chunk_id handles.""" hits = bm25_index.search(query, k=top_k, mode=mode) # your implementation return { "query": query, "candidate_count": len(hits), "results": [ {"chunk_id": h.id, # short stable handle, e.g. "c12" "score": round(h.score, 4), "text": h.text, # clipped, not the whole document "metadata": h.metadata} for h in hits ], } ``` Note how the description tells Toast what the tool is for, how to phrase input, when not to use it (and which tool to use instead), and how many results to expect — and the return value is a JSON envelope with short stable handles and a score. ### Build your own harness with Pi [#build-your-own-harness-with-pi] If you use [Pi](https://github.com/earendil-works/pi) as your agent framework, the harness loop already exists: Pi runs the tool-call loop, executes your tools, and manages the context for you. You only need to connect Toast and register your tools. * Point Pi at the Completions API by adding Toast as a custom model in `~/.pi/agent/models.json`: an `openai-completions` provider with `baseUrl` `https://api.mixedbread.com`, your `MXBAI_API_KEY`, a context window of `131072`, and max output tokens of `4096`. Set the recommended sampling parameters (`temperature 0.7, top_p 0.95`) and leave thinking off. * Define your search tools as a Pi extension: `pi.registerTool({name, description, parameters, execute})`, where `parameters` is the JSON schema for the arguments. All the guidelines from the Python section apply unchanged: the description is the instruction Toast follows, keep parameters flat and JSON-native, return the JSON envelope with stable `chunk_id` handles, and return errors as data instead of throwing. * Pi's built-in compaction summarizes the history. That works, but budget it against the 130k input limit, and prefer prune-style removal of stale tool results where you can. ### Example: the tool-call loop over the Completions API [#example-the-tool-call-loop-over-the-completions-api] A minimal harness loop wiring a custom tool (the `bm25_search` above) to Toast over the Completions API. The tool schema is exactly what a harness would generate from the function's docstring and Annotated hints (see the Python section above) — the raw API always takes the explicit JSON schema. Hosted store tools run server-side; only your own tools come back to you, with `finish_reason: "tool_calls"`: ```python import json from openai import OpenAI client = OpenAI(base_url="https://api.mixedbread.com", api_key=MXBAI_API_KEY) tools = [ { "type": "function", "function": { "name": "bm25_search", "description": "Keyword-based BM25 search over the corpus. This tool matches " "keywords only — send keyword-heavy queries, not questions. " "Use for rare terms, names, codes, and exact vocabulary; use " "the semantic search tool for meaning-based queries. Returns " "up to top_k chunks with stable chunk_id handles.", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "Space-separated keywords, no natural-language " "questions, no boolean operators. Example: " "'jordan international goals caps'", }, "top_k": { "type": "integer", "description": "Number of chunks to return, max 20.", "default": 5, }, "mode": { "type": "string", "enum": ["chunks", "documents"], "default": "chunks", }, }, "required": ["query"], }, }, }, # bringing your own search backend? disable all five hosted store tools: {"type": "store_search", "enabled": False}, {"type": "store_grep", "enabled": False}, {"type": "store_list_chunks", "enabled": False}, {"type": "store_metadata_facets", "enabled": False}, {"type": "list_stores", "enabled": False}, ] messages = [{"role": "user", "content": "Which suppliers had recalls in 2023?"}] completion = client.chat.completions.create( model="toast-1", messages=messages, tools=tools, parallel_tool_calls=True, temperature=0.7, top_p=0.95, ) choice = completion.choices[0] while choice.finish_reason == "tool_calls": messages.append(choice.message) # the assistant turn carrying the tool calls for call in choice.message.tool_calls: # may be several — execute all of them result = bm25_search(**json.loads(call.function.arguments)) messages.append({ "role": "tool", "tool_call_id": call.id, "content": json.dumps(result), # errors go here as data too }) completion = client.chat.completions.create( model="toast-1", messages=messages, tools=tools, parallel_tool_calls=True, temperature=0.7, top_p=0.95, ) choice = completion.choices[0] print(choice.message.content) # the final answer ``` Two properties of the loop to keep in mind: * The API is stateless: every request resends the full message history, and each turn appends the assistant tool-call message plus one tool message per call. * One turn can carry several parallel calls: answer every `tool_call_id`, then send the next request. # Chat Completions (/docs/agent/chat-completions) The Mixedbread Chat Completions API is an OpenAI Chat Completions-compatible endpoint for Mixedbread specialized models and agentic workflows. When integrated with Mixedbread Search, the model can plan searches, inspect the returned evidence, and produce a grounded answer in a single API request. You can use the OpenAI SDK by changing `base_url` and `api_key`, then selecting a `model` from the [supported models](/docs/agent/models). ## Prerequisite [#prerequisite] Get a Mixedbread API key from the [API Keys](https://platform.mixedbread.com/platform?next=api-keys) page. You can install the OpenAI SDK or use cURL directly. ```bash export MXBAI_API_KEY=YOUR_API_KEY ``` ```bash pip install openai ``` ```bash npm install openai ``` ## Make your first request [#make-your-first-request] Point `base_url` to Mixedbread, use your Mixedbread API key, and select one [supported model](/docs/agent/models). Read the generated message from `choices[0].message`. ## OpenAI compatibility [#openai-compatibility] Mixedbread accepts the OpenAI Chat Completions shape for supported fields. The tables below cover Mixedbread-specific extensions and behavior: ### Request fields [#request-fields] | Field or value | Behavior | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `previous_completion_id` | Continues a stored completion and restores prior hosted-tool context when the supplied messages extend its history unchanged. | | `max_tool_calls` | Limits the number of hosted retrieval calls for the completion. | | `include` | Returns selected hosted-tool result payloads. | | Hosted values in `tools` and `tool_choice` | Configures or requires Mixedbread-hosted Store tools. | | `store` | Set to `false` to enable zero data retention. Completion content is not retained, and no retrievable completion is created. Operational model and token metadata is still recorded. | ### Response fields [#response-fields] | Field | Behavior | | ------------------------------------- | ------------------------------------------------------------------ | | `hosted_tool_calls` | Records server-side Store operations and optionally their results. | | `title` | Returns the generated title of a stored conversation. | | `choices[].message.reasoning_content` | Returns planning narration produced between hosted tool calls. | See every request and response field in the [API reference](/api-reference/endpoints/chat/create-chat-completion). ## Integrate with Mixedbread Search [#integrate-with-mixedbread-search] Mixedbread Search tools let Toast 1 plan and execute Store retrieval inside one completion request, then return a grounded answer without a client-side tool loop. Mixedbread Search tools are opt-in: declare a tool in `tools` to turn it on for that completion, and scope its Store operations with `store_identifiers`. A completion that declares none runs no Store retrieval. | Search tool | Use it for | | ----------------------- | ----------------------------------------------------- | | `store_search` | Semantic search across one or more Stores | | `store_grep` | Exact text and regular expression matching | | `store_list_chunks` | Metadata filtering, sorting, and chunk inspection | | `store_metadata_facets` | Discovering metadata fields and representative values | | `list_stores` | Discovering the Stores available to the API key | Use `tool_choice` to require a particular Mixedbread Search tool. `max_tool_calls` limits Mixedbread Search calls. Add a matching `include` value when your application needs retrieved chunk payloads in `hosted_tool_calls`. # Models (/docs/agent/models) Choose a Mixedbread specialized model for knowledge tasks based on your needs. ## Available models [#available-models] The context window includes input messages, tool definitions, tool results, and generated output. `max_completion_tokens` limits generated output. Chat Completions defaults to `toast-1` when `model` is omitted. # Gmail Connector (/docs/connectors/gmail) The Gmail connector imports messages that match selected Gmail labels. Use it to build a searchable Store from focused mailboxes such as support, partnerships, customer feedback, or project correspondence. ## Before you begin [#before-you-begin] You need a Google account with access to the Gmail mailbox and a Mixedbread organization with access to Data sources. ## Connect Gmail [#connect-gmail] In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Gmail**. Enter an optional Store name and review the Store configuration. Leave the name blank to use `gmail-{your - account}`. Select **Connect Gmail**, choose the Google account that owns the mailbox, and approve the requested access. Back in Mixedbread, select the system or custom labels whose matching messages should be synchronized. Saving the label selection starts the initial message import. Mixedbread keeps messages matching the selected labels up to date. ## Choose labels [#choose-labels] The connector shows useful system labels, including **Inbox**, **Important**, **Sent**, and **Starred**, alongside your custom labels. Select only the labels needed for the Store to avoid importing unrelated mail. ## Manage the connector [#manage-the-connector] Open the Gmail data source to: * search available labels; * synchronize or exclude labels; * compare total and unread message counts; * run **Sync now** to re-check selected labels; or * disconnect Gmail. Excluding a label stops future synchronization for that selection. Disconnecting removes the saved Gmail credentials. Previously imported Store files remain available. ## Troubleshooting [#troubleshooting] ### Gmail needs to be reconnected [#gmail-needs-to-be-reconnected] Google credentials can expire or be revoked. Select **Reconnect Gmail** and authorize the same Google account to resume synchronization into the existing Store. ### A label is missing [#a-label-is-missing] Confirm that the label still exists in Gmail, then reload the connector page. Some Gmail category and state labels are intentionally hidden because they are not useful connector selections. ### Messages have not appeared [#messages-have-not-appeared] Verify that they match at least one selected label, then run **Sync now**. # Google Drive Connector (/docs/connectors/google-drive) The Google Drive connector imports selected files and folders into a Store. Selecting a folder includes its files and subfolders, while individual file selection lets you keep the import narrowly scoped. ## Before you begin [#before-you-begin] You need a Google account that can access the Drive content you want to import and a Mixedbread organization with access to Data sources. ## Connect Google Drive [#connect-google-drive] In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Google Drive**. Enter an optional Store name. Leave it blank to use `google-drive- {your - account}`. Google Drive uses metadata contextualization with fast ingestion by default. Expand **Store configuration** only if you need different behavior. Select **Connect Google Drive**, choose a Google account, and approve the requested access. Browse Drive from the connector page. Select the files and folders to synchronize, then confirm the selection. The first selection queues an import. Mixedbread keeps selected files and folders up to date as their contents change. Selecting a folder synchronizes all files and subfolders inside it. Exclude a child item separately when it should not inherit the parent folder's synchronization state. ## Manage the connector [#manage-the-connector] Open the Google Drive data source to browse folders, search the current folder, and review each item's status. * Select **Sync** to import an excluded file or folder. * Select **Unsync** to stop future updates for an item. * Use **Sync now** to re-check selected files and folders for new or changed content. * Use **Disconnect** to remove the saved Google credentials and stop receiving Drive changes. Unsyncing or disconnecting does not delete previously imported Store files. ## Troubleshooting [#troubleshooting] ### A file or folder is missing [#a-file-or-folder-is-missing] Confirm that the connected Google account can open it. Shared Drive and shared folder content only appears when the account has access. ### A nested item has the wrong status [#a-nested-item-has-the-wrong-status] Check whether it inherits synchronization from a selected parent folder. You can explicitly exclude or reselect the child item. ### Changes have not appeared [#changes-have-not-appeared] Run **Sync now** to re-check all selected files and folders. Review the item status for unsupported content or access errors. # Granola Connector (/docs/connectors/granola) The Granola connector imports selected meeting notes and folders into a Store. It authenticates with a Granola Personal API key and supports manual or scheduled synchronization. ## Before you begin [#before-you-begin] You need: * a Granola account with access to the notes you want to import; * permission to create a Personal API key; and * a Mixedbread organization with access to Data sources. ## Create a Granola API key [#create-a-granola-api-key] In Granola, open **Settings → Connectors**. Under **API**, select **Personal API keys**. Create a new key and grant the access scopes required for the folders and notes you intend to synchronize. Copy the key when Granola displays it. Store it securely because it grants access to the selected Granola data. Granola Settings Connectors page showing Personal API keys under API

Granola Settings Connectors page showing Personal API keys under API

## Connect Granola [#connect-granola] In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Granola**. Paste the Granola Personal API key, which begins with `grn_`. Select **Manual**, **Every 10 minutes**, **Hourly**, **Daily**, or **Weekly**. Enter an optional Store name and review the Store configuration. Leave the name blank to use `granola-notes-{key - id}`. Select **Connect Granola** . Browse the Granola catalog and select the folders and individual notes to import. ## Manage synchronization [#manage-synchronization] Open the Granola data source to: * browse and search folders and notes; * synchronize or exclude selected items; * refresh the Granola catalog; * change the synchronization schedule; * run **Sync now**; or * disconnect the account. Turning off periodic synchronization leaves **Sync now** available. Excluding an item or disconnecting Granola does not delete notes already imported into the Store. ## Troubleshooting [#troubleshooting] ### No folders or notes appear [#no-folders-or-notes-appear] Confirm that the Personal API key has the required access scopes. Refresh the catalog after changing scopes or making new notes available. ### The API key no longer works [#the-api-key-no-longer-works] Create a new Personal API key in Granola and reconnect the data source. Treat the key as a secret and revoke keys that are no longer used. ### Scheduled updates are not running [#scheduled-updates-are-not-running] Open the connector and verify that the schedule is not set to **Manual**. Run **Sync now** to test access immediately. # Connectors (/docs/connectors) Connectors import content from the tools your team already uses into a [Store](/docs/stores/stores). After the initial import, each connector can keep the selected content up to date without requiring repeated uploads. ## Available connectors [#available-connectors] | Connector | Imported content | Authentication | | --------------------------------------------- | ------------------------------------------------------ | -------------------------------------- | | [Slack](/docs/connectors/slack) | Selected channels, threads, and supported shared files | OAuth or a customer-provided Slack app | | [Google Drive](/docs/connectors/google-drive) | Selected files and folders | Google OAuth | | [Gmail](/docs/connectors/gmail) | Messages matching selected labels | Google OAuth | | [Granola](/docs/connectors/granola) | Selected folders and notes | Personal API key | | [Linear](/docs/connectors/linear) | Issues from selected teams | Linear OAuth | | [Notion](/docs/connectors/notion) | Shared pages and databases | OAuth or an integration token | | [Salesforce](/docs/connectors/salesforce) | Records from selected object types | External Client App credentials | ## Connect a data source [#connect-a-data-source] Sign in to the [Mixedbread Platform](https://platform.mixedbread.com), select your organization, and open **Data sources**. Select **Create**, then choose the provider you want to connect. Enter an optional Store name. Leave it blank to use the connector's default naming scheme. Keep the recommended configuration or expand **Store configuration** to change contextualization and ingestion settings. Salesforce does not expose these settings during connection. Complete the provider-specific authorization steps. Mixedbread redirects you to the connector page after a successful connection. Choose the channels, files, folders, labels, teams, pages, notes, or object types that should feed the Store. Saving the selection starts the initial import. ## Store configuration [#store-configuration] New connector Stores use settings intended to produce useful search results without additional configuration: * **Metadata contextualization** adds source details such as titles and authors to chunks before embedding. * **File contextualization** situates chunks within their full document. * **Ingestion mode** controls the balance between processing speed and retrieval quality. Most connectors default to metadata and file contextualization with high-quality ingestion. Google Drive defaults to metadata contextualization with fast ingestion and no file contextualization. If the Store name already exists, the connector adds imported data to that Store. The existing Store keeps its configuration; only the selected ingestion mode applies to newly imported files. A connector can only import content that the connected account or app is allowed to access. Grant the minimum provider permissions needed for the content you intend to synchronize. ## Manage synchronized content [#manage-synchronized-content] Open a connected data source to review its selected resources and import status. From the connector page, you can: * add or remove resources from synchronization; * run a manual sync; * retry supported import failures; * open the destination Store; or * disconnect the provider. Removing a resource from synchronization stops future updates but does not delete data that was already imported. Disconnecting also leaves imported Store files in place. Delete those files separately if you no longer want them in the Store. After the import finishes, use [Search](/docs/stores/search) or [Question Answering](/docs/stores/search/question-answering) with the destination Store. # Linear Connector (/docs/connectors/linear) The Linear connector imports issues from selected teams into a Store. Use it to search project decisions, issue descriptions, and the work tracked across your Linear workspace. ## Before you begin [#before-you-begin] You need access to the Linear workspace and teams you want to import, plus a Mixedbread organization with access to Data sources. ## Connect Linear [#connect-linear] In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Linear**. Enter an optional Store name and review the Store configuration. Leave the name blank to use `linear-{your - workspace}`. Select **Connect Linear**, choose the target workspace, and approve the requested access. Back in Mixedbread, choose the Linear teams whose issues should be synchronized. Saving the selection starts the initial issue import. Mixedbread keeps issues from selected teams up to date as they change. ## Manage the connector [#manage-the-connector] Open the Linear data source to: * search, filter, and sort workspace teams; * synchronize or exclude teams; * monitor issue import status; * use **Sync now** to re-check all selected teams for new or changed issues; or * disconnect the Linear workspace. Excluding a team stops future synchronization for its issues. Disconnecting removes the saved Linear credentials and stops receiving Linear events. Previously imported Store files remain available. ## Troubleshooting [#troubleshooting] ### A team is missing [#a-team-is-missing] Verify that the connected Linear account can access the team, then reload the connector page. ### Issues are not updating [#issues-are-not-updating] Confirm that the team is marked **Syncing** and run **Sync now**. If access was revoked, reconnect Linear with an account that can access the selected teams. ### An import failed [#an-import-failed] Review the team's import status and error. Resolve any provider access issue, then retry with **Sync now**. # Notion Connector (/docs/connectors/notion) The Notion connector imports pages and databases shared with Mixedbread into a Store. OAuth is the recommended setup because it provides Notion's page picker and a simpler authorization flow. ## Before you begin [#before-you-begin] You need permission to add a connection to the Notion pages you want to import and a Mixedbread organization with access to Data sources. ## Connect with OAuth [#connect-with-oauth] In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Notion**. Select **OAuth (recommended)** . Enter an optional Store name and review the Store configuration. Leave the name blank to use `notion-{your - workspace}`. Select **Connect Notion**, choose the workspace, and use Notion's page picker to grant access to the pages and databases you want to import. Return to Mixedbread. The connector imports the content shared through the page picker. Use **Manage access** from the connector page to reopen Notion's page picker. Newly shared pages are imported, while pages removed from the connection stop appearing in future synchronization. ## Connect with an integration token [#connect-with-an-integration-token] Open [Notion integrations](https://www.notion.so/my-integrations), create an integration of type **Access token**, and copy its access token. Under **Capabilities**, enable **Read content** and **Read user information including email addresses**. **Read comments** is optional. Notion connection Configuration tab showing the access token and capabilities

Notion connection Configuration tab showing the access token and capabilities

Open the connection's **Content access** tab, select **Edit access**, and choose the pages and databases to import. Mixedbread only imports content shared with the integration. Notion connection Content access tab with the Edit access button

Notion connection Content access tab with the Edit access button

In Mixedbread, choose **Notion → Integration token** and paste the token, which begins with `ntn_`. Enter an optional Store name, review the Store configuration, and select **Connect Notion**. ## Enable real-time updates for token setup [#enable-real-time-updates-for-token-setup] After connecting with an integration token, open the Notion data source in Mixedbread. Copy its workspace-specific webhook URL and verification token, then add them on the integration's **Webhooks** tab in Notion. The webhook values are only available after Mixedbread has connected the workspace. Without the optional webhook, use the connector's manual synchronization action to import changes. ## Manage the connector [#manage-the-connector] Open the Notion data source to review imported resources, search them by name or path, monitor the latest import, manage OAuth page access, or disconnect the workspace. Disconnecting stops Notion events and removes the saved credentials. Previously imported Store files remain available. ## Troubleshooting [#troubleshooting] ### A page or database is missing [#a-page-or-database-is-missing] Confirm that it was shared through the OAuth page picker or the integration's **Content access** settings. ### Token setup is not receiving updates [#token-setup-is-not-receiving-updates] Verify the webhook URL and verification token in Notion. If no webhook is configured, run a manual synchronization after content changes. ### The last import failed [#the-last-import-failed] Check that the connection still has access to all selected content, then retry the import. # Salesforce Connector (/docs/connectors/salesforce) The Salesforce connector imports records from selected object types into a Store. It uses Salesforce's Client Credentials Flow and accesses data as a configured **Run As** user. ## Before you begin [#before-you-begin] You need: * access to Salesforce Setup and External Client App Manager; * permission to create and configure an External Client App; * a Salesforce user whose record access matches the data you want to import; and * a Mixedbread organization with access to Data sources. ## Create the Salesforce External Client App [#create-the-salesforce-external-client-app] In Salesforce, open **Setup**. From Quick Settings, select **Open Advanced Setup**, then open **External Client App Manager**. Salesforce Quick Settings menu showing Open Advanced Setup

Salesforce Quick Settings menu showing Open Advanced Setup

Salesforce Setup sidebar showing External Client App Manager

Create an app, provide its name and contact email, and continue to the API settings. Under **API**, enable **OAuth Settings** and enter this callback URL: `https://api.mixedbread.com/v1/integrations/salesforce/oauth/callback` Add the **Manage user data via APIs (`api`)** scope. Salesforce External Client App OAuth settings with callback URL and API scope selected

Salesforce External Client App OAuth settings with callback URL and API scope selected

Under **Flow Enablement**, turn on **Client Credentials Flow**, then create the app. Salesforce OAuth Flow Enablement setting for Client Credentials Flow

Salesforce OAuth Flow Enablement setting for Client Credentials Flow

In External Client App Manager, open the app's **Policies** tab and edit its policies. Enable Client Credentials Flow, then choose the **Run As** username. Salesforce External Client App policies showing Client Credentials Flow and Run As user

Salesforce External Client App policies showing Client Credentials Flow and Run As user

Open the app's **Settings** tab. Under **OAuth Settings**, select **Consumer Key and Secret**, then copy the Consumer Key and Consumer Secret. Salesforce External Client App Settings tab showing the Consumer Key and Secret button

Salesforce External Client App Settings tab showing the Consumer Key and Secret button

Mixedbread can only access records available to the Salesforce Run As user. Use a dedicated user with the minimum permissions required for the selected object types. ## Connect Salesforce [#connect-salesforce] In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Salesforce**. Paste the Consumer Key and Consumer Secret from the External Client App. Enter your organization's My Domain login URL, for example `https://yourcompany.my.salesforce.com`. Select **Manual**, **Every 10 minutes**, **Hourly**, **Daily**, or **Weekly**. Enter an optional Store name. Leave it blank to use `salesforce-{your - org} `. Select **Connect Salesforce** . Choose the Salesforce object types whose records should be imported. ## Manage synchronization [#manage-synchronization] Open the Salesforce data source to: * search and filter available object types; * synchronize or exclude object types; * change the synchronization schedule; * use **Sync now** to check selected object types for new, changed, and deleted records; or * disconnect the Salesforce organization. Turning off periodic synchronization leaves manual synchronization available. Excluding an object type or disconnecting Salesforce does not delete records already imported into the Store. ## Troubleshooting [#troubleshooting] ### Authentication fails [#authentication-fails] Check the Consumer Key, Consumer Secret, and My Domain URL. Confirm that Client Credentials Flow is enabled both in the app settings and its policies. ### No object types or records appear [#no-object-types-or-records-appear] Verify the Run As user and its object- and record-level permissions. Mixedbread cannot import data that user cannot access. ### Changes are not appearing [#changes-are-not-appearing] Confirm that a periodic schedule is enabled or run **Sync now**. The manual sync checks selected object types for created, updated, and deleted records. # Slack Connector (/docs/connectors/slack) The Slack connector imports selected channel history, threads, and supported shared files into a Store. It keeps selected channels current as messages are posted, edited, or deleted. Once Slack content is imported, workspace members can ask questions by mentioning the Mixedbread app, sending it a direct message, or running `/mixedbread ask `. Answers include links to relevant Slack messages. ## Before you begin [#before-you-begin] You need: * a Mixedbread organization with access to Data sources; * permission to install apps in the Slack workspace; and * access to the channels you want to import. OAuth is the recommended installation method. Use manual setup when your organization requires a customer-managed Slack app. ## Connect with OAuth [#connect-with-oauth]

In the Mixedbread Platform, open **Data sources**, select **Create**, and choose **Slack**. Select **OAuth (recommended)** . Enter an optional Store name and review the Store configuration. Leave the name blank to use `slack-{your - workspace}`. Select **Connect Slack**, choose the workspace, review the requested permissions, and approve the installation. Back in Mixedbread, select the channels to synchronize. The Slack bot joins selected public channels so it can read new messages. Saving the selection queues a historical import and enables updates for new messages. Use **Sync now** to re-check every selected channel. ## Connect with a customer-managed Slack app [#connect-with-a-customer-managed-slack-app] Choose **Slack**, then select **Manual setup**. Mixedbread generates a deployment-specific Slack app manifest in JSON and YAML. Open [Slack's app creation page](https://api.slack.com/apps?new_app=1), choose **From an app manifest**, select the workspace, and paste the manifest from Mixedbread. In the Slack app settings, open **Basic Information**. Under **App Credentials**, copy the **Signing Secret** into Mixedbread. Slack Basic Information page with the Signing Secret field highlighted

Slack Basic Information page with the Signing Secret field highlighted

Open **OAuth & Permissions**, select **Install to Workspace**, and approve the installation. Copy the **Bot User OAuth Token**, which begins with `xoxb-`, into Mixedbread. Slack OAuth and Permissions page with the Bot User OAuth Token highlighted

Slack OAuth and Permissions page with the Bot User OAuth Token highlighted

Choose an optional Store name and configuration, then select **Connect Slack**. Choose the channels to import. Saving the selection starts the historical import. Keep the generated manifest unchanged. Its event URLs and permissions are configured for the current Mixedbread deployment. ## Ask questions in Slack [#ask-questions-in-slack] After at least one selected channel has finished importing, workspace members can use any of these entry points: * mention `@Mixedbread` followed by a question; * send the Mixedbread app a direct message; or * run `/mixedbread ask ` in a channel. Mixedbread searches the Slack Store, returns a generated answer, and links back to source messages when available. Answers are filtered using the requester's workspace identity and the source content's access controls. Mixedbread uses generative AI to create answers. Responses may be inaccurate or incomplete. Verify important information using the linked Slack sources. ## Manage the connector [#manage-the-connector] Open the Slack data source to: * search, filter, and sort available channels; * synchronize or exclude channels; * refresh the channel catalog; * run a manual sync; * retry channel or item-level failures; or * disconnect the workspace. Excluding a channel stops future imports. Disconnecting removes the saved Slack credentials and stops event delivery. Previously imported Store files remain available until you delete them. ## Troubleshooting [#troubleshooting] ### A channel is missing [#a-channel-is-missing] Select **Refresh channels**. If the channel still does not appear, verify that the connected app can access it and that the channel is not archived. ### A channel is not receiving updates [#a-channel-is-not-receiving-updates] Confirm that it is marked **Syncing** and that the Mixedbread app is a channel member. Run **Sync now** to re-check the channel. ### An import completed with warnings [#an-import-completed-with-warnings] Open the warning details to view the affected Slack items. Use **Retry** for recoverable failures. # Account (/docs/platform/account) ## Overview [#overview] A Mixedbread account represents an individual user and provides access to the platform's services. Each account includes a display name, profile picture, and email address, with the email serving as the unique identifier. Account details can be updated at any time. Accounts can be associated with multiple organizations or none at all. By default, each account is automatically assigned to its own organization. Organizations handle resource management including billing, Stores, and other platform features, rather than individual accounts. See [organizations](/docs/platform/organization). # Billing (/docs/platform/billing) ## Overview [#overview] Mixedbread offers a free tier with monthly allocations for ingestion, queries, and parsing. Scale plan users pay-as-you-go for usage beyond the subscription fee. For detailed pricing information, visit our [pricing page](/pricing). ## Payment Methods [#payment-methods] We accept major credit cards including Visa and American Express for all transactions. To add a payment method, go to the **Billing Settings / Overview** page and click **Add Payment Method**. ## Credits [#credits] You can view your current credit balance on the **Billing Settings / Overview** page. To add credits to your account, you can do so through the billing settings. This way you can top up your account with more credits to use or set an auto top up amount. ### Adding Credits Manually [#adding-credits-manually] Navigate to the **Billing Settings** page Click **+** on the Pay-as-you-go plan page Enter the amount of credits you want to add and press continue ### Adding Credits Automatically [#adding-credits-automatically] To use this method you have to have a default payment method set up. Navigate to the **Billing Settings** page Click **Enable Auto Top-Up** Enable auto top-up and enter the amount of credits you want to top up and the threshold at which you want to top up. Click **Save Settings** ## Billing Information [#billing-information] You can configure a dedicated email address to receive billing statements and invoices. Additionally, billing information must be provided for the person or company responsible for payment. You can do this under the **Billing Settings / Usage & Invoices** page. ## Usage Overview [#usage-overview] You can view your usage and billing history on the **Billing Settings / Usage & Invoices** page. The usage metrics may be delayed by up to 10 minutes to ensure accurate tracking. The system allows for small overdrafts to prevent service interruptions during usage spikes. The Usage & Invoices page also displays a cost breakdown of your usage based on the services you are using. ## Vercel Integration Billing [#vercel-integration-billing] If your Mixedbread organization is managed through the Vercel integration, all usage is billed through your Vercel account instead of directly through Mixedbread. For Vercel-managed organizations: * Billing and payments are handled entirely through Vercel * Usage metrics are available in both the Vercel dashboard and Mixedbread dashboard * Cost tracking and invoices are managed in the Vercel billing dashboard For complete details on setting up and managing billing with the Vercel integration, see [Vercel Integration](/api-reference/integrations/vercel). # Limits (/docs/platform/limits) ## Overview [#overview] This page lists the current limits that apply across Mixedbread Stores and files. Unless noted otherwise, the values below reflect the default paid experience. None of these limits are hard walls. If you're bumping into one, or expect to, [contact us](/contact) — we routinely raise limits for teams with real workloads, and we'd rather hear from you early than have you design around a number on this page. ## Current Limits [#current-limits] ### Stores [#stores] | Metric | Current Limit | | ---------------------------- | -------------- | | Max stores per organization | Unlimited\* | | Max store name length | 60 characters | | Max store description length | 256 characters | ### Files [#files] | Metric | Current Limit | | --------------------------------- | -------------- | | Max files per store | Unlimited\* | | Max store file external ID length | 256 characters | ### Search [#search] | Metric | Current Limit | | ------------------------------------------ | ---------------- | | Max stores per search | 16 | | Max agentic search instructions length | 5,000 characters | | Max question answering instructions length | 8,000 characters | ### Metadata [#metadata] | Metric | Current Limit | | -------------------------- | ------------- | | Max metadata keys | 256 † | | Max metadata key size | 128 bytes † | | Max metadata value size | 8 KiB ‡ | | Max total metadata size | 128 KiB | | Max metadata nesting depth | 5 | \* Free/basic organizations may have lower plan-specific limits. † Counted against flattened leaf keys when metadata is nested. For example, `{ "a": { "b": 1, "c": 2 } }` counts as two keys (`a.b`, `a.c`), and the key size limit applies to the full flattened path. ‡ Applies to leaf values (strings, numbers, booleans, arrays, etc.). Objects are not leaves — their contents are. # Organization (/docs/platform/organization) ## Overview [#overview] Organizations in Mixedbread serve as the primary container for managing resources, billing, and team collaboration. Each organization represents a workspace where multiple users can collaborate on Stores, manage API keys, and share resources. Organizations are essential for team-based workflows and enterprise use cases. ## Creating an Organization [#creating-an-organization] When you first sign up for Mixedbread, an organization is automatically created for you. This default organization uses your account name as the organization name and serves as your personal workspace. Each organization is uniquely identified by an organization slug. ### Manual Organization Creation [#manual-organization-creation] To create additional organizations: Navigate to the **Organizations** section in your dashboard Click **Create Organization** to create a new organization Provide an organization name and organization slug Click **Create** to finalize ### Organization Naming [#organization-naming] Choose descriptive names that reflect your use case by using company names for business organizations, including project identifiers for specific initiatives, and considering environment suffixes such as "Production" or "Development" to clearly distinguish between different organizational contexts. ## Organization Structure [#organization-structure] ### Members and Roles [#members-and-roles] Organizations support multiple user roles with different permission levels: | Role | Manage Resources | Manage Members | Manage Settings | | ------ | --------------------------------- | ---------------------------------- | --------------------------------------------- | | Owner | ✅ Full control | ✅ Full control | ✅ Full control | | Admin | ✅ Create and manage all resources | ✅ Add/remove members, change roles | ❌ Cannot modify billing or transfer ownership | | Member | ✅ Create and manage own resources | ❌ No access | ❌ No access | ### Inviting Members [#inviting-members] To invite users to your organization: Go to **Organization Settings** > **Team** Click **Invite Member** Enter the email address of the person you want to invite Select their role in the organization Send the invitation Invited users will receive an email with a link to join the organization. They must accept the invitation to gain access. # Bring Your Own Bucket (/docs/production/bring-your-own-bucket) By default, your data lives in Mixedbread-managed object storage. Bring your own bucket (BYOB) lets [enterprise customers](/pricing) use object storage they own and control as the backend instead. With BYOB, your bucket holds all user content (documents, metadata) and derived artifacts (chunks, generated content, the search index). Mixedbread reads and writes it with ephemeral compute and retains nothing beyond memory: we keep only usage metering for billing. BYOB is enabled per organization. [Contact us](mailto:support@mixedbread.ai) and we'll turn it on for your account. ## Supported providers [#supported-providers] | Provider | Status | Authentication | | -------------------- | ----------- | ------------------------------------- | | AWS S3 | Available | IAM role (recommended) or access keys | | Google Cloud Storage | Coming soon | N/A | | Azure Blob Storage | Coming soon | N/A | Other S3-compatible services can work via access keys and a custom endpoint, but aren't officially supported yet. [Contact us](mailto:support@mixedbread.ai) if you need one, or a provider that isn't listed. ## Authentication [#authentication] For AWS S3, authenticate one of two ways: * **IAM role (recommended).** Mixedbread [assumes a cross-account role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage-assume.html) in your account via STS, scoped with a unique external ID. We do not store any long-lived secrets. Access can be granted or revoked entirely through the role's trust policy. * **Access keys.** An access key ID and secret. Keys are encrypted at rest, never returned by the API, and can be rotated at any time. Use this for S3-compatible endpoints. ## Encryption [#encryption] Data is encrypted in transit and at rest. If your bucket uses [SSE-KMS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html), provide the KMS key ARN and grant the role or identity Mixedbread uses `kms:Encrypt`, `kms:Decrypt`, and `kms:GenerateDataKey` on that key. Mixedbread encrypts writes with your key, so you hold the encryption material and can revoke it at any time. Omit the key to use the bucket's default encryption. The KMS key is fixed when you connect the bucket and can't be changed afterward, because objects stay encrypted under the key they were written with. To switch keys, recreate the connection. ## Setup [#setup] [Contact us](mailto:support@mixedbread.ai) to enable BYOB for your organization. We'll confirm once it's on. Create a dedicated S3 bucket in **us-east-1** (see [performance](#does-byob-affect-performance)). Optionally set a key prefix to namespace Mixedbread's objects, and configure SSE-KMS to use your own key. Create an IAM role Mixedbread can assume with the external ID we provide, or create access keys. If the bucket uses SSE-KMS, grant the same identity access to your KMS key. In the dashboard, add the bucket with its name, region, optional prefix, the role ARN or access keys, and the KMS key ARN if applicable. Mixedbread validates the bucket before storing anything, checking reachability and running a write/delete probe, so a misconfigured or unreachable bucket is rejected immediately. Once connected, new stores point to your bucket automatically. ## Does BYOB affect performance? [#does-byob-affect-performance] No. Keep your bucket in **us-east-1**, colocated with Mixedbread's compute, and indexing and search perform the same as without BYOB. Buckets in other regions work but add cross-region latency and data-transfer cost. ## What happens to my existing stores? [#what-happens-to-my-existing-stores] Connecting a bucket changes where *new* content lives; it does not move existing data. * **Stores created after setup** persist all content in your bucket. * **Stores created before setup** keep reading and writing from the Mixedbread-owned bucket; they are not migrated. To move existing data into your bucket today, recreate those stores after connecting it. Automated migration of existing stores is coming soon. ## What does it cost? [#what-does-it-cost] * **Mixedbread** charges for the compute cost of indexing and search. * **You** pay your cloud provider directly for the bucket's storage, requests, data transfer, and any encryption services you use (such as KMS). ## How do I revoke access? [#how-do-i-revoke-access] You control access from your own cloud and can revoke it at any time. How quickly Mixedbread loses access depends on how you revoke it: * **Access keys.** Once you deactivate or delete the key, Mixedbread loses access within a few minutes (AWS IAM is eventually consistent). * **IAM role.** Once you remove the trust policy, Mixedbread can no longer obtain new credentials. Because it uses short-lived STS sessions, any session it already holds expires shortly after; to cut access immediately, use IAM's *revoke active sessions*. After Mixedbread loses access, your stores and files are no longer reachable from our service. Content already loaded into the retrieval engine may stay in an ephemeral in-memory cache for a short period until it is evicted. # Security & Compliance (/docs/production/security) Security is foundational to how we build Mixedbread. We hold independent certifications, encrypt your data in transit and at rest, and never use your content to train models. Enterprise customers can also keep all content in [object storage they own and control](/docs/production/bring-your-own-bucket). ## Certifications & compliance [#certifications--compliance] | Standard | Status | | ---------------- | --------------------------------------------------------------------------------------------------------------------- | | **SOC 2 Type 2** | Certified for the Security trust services criterion. Report available on request. | | **ISO 27001** | Certified. Certificate available on request. | | **GDPR** | Compliant. A [Data Processing Addendum](/pages/dpa) with EU, UK, and Swiss Standard Contractual Clauses is available. | Need our SOC 2 Type 2 report, ISO 27001 certificate, or a completed security questionnaire? [Contact us](mailto:support@mixedbread.com) and we'll share them under NDA. ## Encryption [#encryption] Your data is encrypted at every stage. * **In transit.** All connections use TLS 1.2 or higher. * **At rest.** Stored data is encrypted with AES-256. With [Bring Your Own Bucket](/docs/production/bring-your-own-bucket) you can go further and supply your own SSE-KMS key, so you hold the encryption material and can revoke it at any time. ## Data residency [#data-residency] All processing and Mixedbread-managed storage currently happen in the United States. EU data residency is coming soon. [Contact us](mailto:support@mixedbread.com) if this is a requirement for your organization. With [Bring Your Own Bucket](/docs/production/bring-your-own-bucket), content at rest lives in the bucket you provide and control. ## How we handle your data [#how-we-handle-your-data] * **No training on your data.** Your content and usage are never used to train models, for any user on any plan. * **Access controls.** Access to customer data is restricted, authenticated, and monitored. * **You stay in control.** Delete a store or your account and the associated content is removed. With [Bring Your Own Bucket](/docs/production/bring-your-own-bucket), content lives in storage you own. Mixedbread reads and writes it with ephemeral compute and retains nothing beyond memory. ## Vulnerability disclosure [#vulnerability-disclosure] We welcome reports from security researchers and treat them as a priority. * **Report it.** Email [support@mixedbread.com](mailto:support@mixedbread.com) with steps to reproduce, affected endpoints, and any proof of concept. Please report privately and give us a reasonable window to remediate before public disclosure. * **What to expect.** We acknowledge reports promptly, keep you updated on our progress, and let you know when the issue is resolved. * **Safe harbor.** We won't pursue legal action for good-faith research that respects user privacy, avoids data destruction or service degradation, and stays within the scope of your own account or test data. ## Questions? [#questions] For security reviews, documentation requests, or anything else, [reach out to us](mailto:support@mixedbread.com). # Data Models (/docs/stores/data-models) Understanding the core data structures in Mixedbread Stores helps you work effectively with the API and understand how your content is organized and retrieved. ## Store [#store] A **Store** is the primary container for your searchable content. It holds your files, manages access permissions, and provides the foundation for semantic search operations. ### Store Properties [#store-properties] | Property | Type | Description | | ---------------- | ------- | -------------------------------------------------------- | | `id` | string | Unique identifier for the Store | | `name` | string | User-defined name that serves as an identifier | | `description` | string | Optional description of the Store's purpose | | `is_public` | boolean | Whether the Store is publicly accessible | | `metadata` | object | Additional metadata associated with the Store | | `file_counts` | object | Counts of files in different processing states | | `expires_after` | object | Expiration configuration based on activity | | `status` | enum | Current status: `expired`, `in_progress`, `completed` | | `created_at` | string | ISO timestamp when the Store was created | | `updated_at` | string | ISO timestamp when the Store was last updated | | `last_active_at` | string | ISO timestamp of the last activity | | `usage_bytes` | integer | Total storage space used by indexed content | | `expires_at` | string | Computed expiration timestamp (if expires\_after is set) | | `object` | string | Always "store" | ### File Counts Object [#file-counts-object] The `file_counts` object provides detailed breakdown of file processing states: | Property | Type | Description | | ------------- | ------- | ---------------------------------------------- | | `pending` | integer | Number of files waiting to be processed | | `in_progress` | integer | Number of files currently being processed | | `cancelled` | integer | Number of files whose processing was cancelled | | `completed` | integer | Number of successfully processed files | | `failed` | integer | Number of files that failed processing | | `total` | integer | Total number of files | For detailed configuration options including expiration policies and public access, see [Store Configuration](/docs/stores/stores#configuration-options). ### Store Example [#store-example] ```json { "id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "name": "product-documentation", "description": "Complete product documentation and API reference", "is_public": false, "metadata": { "category": "documentation", "language": "en" }, "file_counts": { "pending": 2, "in_progress": 1, "cancelled": 0, "completed": 10, "failed": 0, "total": 13 }, "expires_after": { "anchor": "last_active_at", "days": 30 }, "status": "in_progress", "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-20T14:30:00Z", "last_active_at": "2024-01-20T14:30:00Z", "usage_bytes": 1048576, "expires_at": "2024-02-19T14:30:00Z", "object": "store" } ``` ## Store File [#store-file] A **Store File** represents a complete file that you've uploaded to a Store. It tracks the file's processing status, metadata, and relationship to the searchable chunks created from its content. ### File Properties [#file-properties] | Property | Type | Description | | ------------- | ------- | -------------------------------------------------- | | `id` | string | Unique identifier for the file within the Store | | `filename` | string | Original name of the uploaded file | | `metadata` | object | Custom key-value pairs you've attached to the file | | `status` | enum | Current processing status of the file | | `last_error` | object | Details about any processing errors that occurred | | `store_id` | string | ID of the Store containing this file | | `created_at` | string | ISO timestamp when the file was added to the Store | | `version` | integer | Version number of the file within the Store | | `usage_bytes` | integer | Storage space used by the file's indexed data | | `object` | string | Always "store.file" | For detailed information on file processing lifecycle and status meanings, see [Store File Status](/docs/stores/store-files#store-file-status). For guidance on metadata structure and types, see [Metadata Types](/docs/stores/store-files/metadata-types). ### File Example [#file-example] ```json { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "filename": "product-documentation.pdf", "metadata": { "category": "documentation", "department": "product", "version": "2.1", "last_updated": "2024-01-15" }, "status": "completed", "last_error": null, "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "created_at": "2024-01-15T10:30:00Z", "version": 1, "usage_bytes": 245760, "object": "store.file" } ``` ## Store Chunk [#store-chunk] A **Store Chunk** represents a searchable segment of content created from a Store File. When you search, you get back chunks that contain the most relevant portions of your files. ### Chunk Properties [#chunk-properties] | Property | Type | Description | | -------------------- | ------- | -------------------------------------------------------------- | | `chunk_index` | integer | Position of this chunk within the source file | | `mime_type` | string | Content type of the chunk (text/plain, image/png, etc.) | | `model` | string | Model used to generate the chunk's vector | | `score` | number | Relevance score for this chunk (in search results) | | `file_id` | string | ID of the file this chunk came from | | `filename` | string | Name of the source file | | `store_id` | string | ID of the Store containing this chunk | | `external_id` | string | Optional external identifier for the source file | | `metadata` | object | User-defined metadata inherited from the source file | | `generated_metadata` | object | Ingestion-time structured metadata e.g. chunk size | | `type` | enum | Type of content: `text`, `image_url`, `audio_url`, `video_url` | ### Content-Specific Properties [#content-specific-properties] **Text Chunks** | Property | Type | Description | | --------- | ------- | ---------------------------------------------------------------- | | `text` | string | Text content of the chunk | | `summary` | string | AI-generated summary of the text chunk † | | `offset` | integer | Character offset of this chunk relative to the start of the file | **Image Chunks** | Property | Type | Description | | ----------- | ------ | ------------------------------------------- | | `image_url` | object | Image URL and format information | | `ocr_text` | string | Text extracted from images via OCR | | `summary` | string | AI-generated summary of the image content † | **Audio Chunks** | Property | Type | Description | | --------------- | ------- | ------------------------------------------- | | `audio_url` | object | Audio URL and format information | | `transcription` | string | Speech-to-text transcription of the audio † | | `summary` | string | AI-generated summary of the audio content † | | `sampling_rate` | integer | Audio sampling rate in Hz | **Video Chunks** | Property | Type | Description | | --------------- | ------ | ------------------------------------------- | | `video_url` | object | Video URL and format information | | `transcription` | string | Speech-to-text transcription of the video † | | `summary` | string | AI-generated summary of the video clip † | ^† The `summary`, `ocr_text` and `transcription` fields are only populated when the file was ingested with the `high_quality` [parsing strategy](/docs/stores/store-files#parsing-strategy). ### Chunk Types [#chunk-types] **Text Chunks** ```json { "type": "text", "text": "User authentication in our API requires a valid API key...", "summary": "API authentication requires a valid API key and uses request headers to identify callers.", "chunk_index": 2, "offset": 1024, "mime_type": "text/plain", "score": 0.89 } ``` **Image Chunks** ```json { "type": "image_url", "image_url": { "url": "https://signed-url-to-image.com/chunk_img_123", "format": "png" }, "ocr_text": "Figure 1: Authentication Flow Diagram", "summary": "A diagram showing the authentication flow process", "chunk_index": 5, "mime_type": "image/png", "score": 0.76 } ``` **Audio Chunks** ```json { "type": "audio_url", "audio_url": { "url": "https://signed-url-to-audio.com/chunk_audio_456" }, "transcription": "Welcome to our product overview. In this section, we'll cover...", "sampling_rate": 44100, "chunk_index": 3, "mime_type": "audio/mpeg", "score": 0.82 } ``` **Video Chunks** ```json { "type": "video_url", "video_url": { "url": "https://signed-url-to-video.com/chunk_video_789" }, "transcription": "Hello everyone, today we're going to demonstrate...", "chunk_index": 1, "mime_type": "video/mp4", "score": 0.88 } ``` ### Complete Chunk Example [#complete-chunk-example] ```json { "chunk_index": 3, "mime_type": "text/plain", "model": "mixedbread-ai/mxbai-omni-v1", "score": 0.92, "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "filename": "product-documentation.pdf", "store_id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "external_id": "doc-auth-guide-v2", "metadata": { "category": "documentation", "department": "product" }, "type": "text", "text": "To authenticate API requests, include your API key in the Authorization header: Authorization: Bearer YOUR_API_KEY. The API key identifies your account and provides access to your organization's resources.", "offset": 4096 } ``` # Metadata Filtering (/docs/stores/metadata-filtering) Metadata filtering provides a powerful way to narrow down results based on the metadata attached to your files. **Need to understand metadata types?** This page covers filtering syntax and operations. For supported metadata types and structure, see [Metadata Types](/docs/stores/store-files/metadata-types). ## Quick Example [#quick-example] Here's a simple example of filtering files by category: ## Filter Structure [#filter-structure] Filters can be structured in two ways depending on your needs: ### Single Field Filter (Direct Condition) [#single-field-filter-direct-condition] For simple single-field filtering, you can use a direct condition: ```json {"key": "metadata_key", "operator": "comparison", "value": "target_value"} ``` Example: ```json {"key": "category", "operator": "eq", "value": "documentation"} ``` ### Multiple Field Filter (Logical Operators) [#multiple-field-filter-logical-operators] For complex filtering with multiple conditions, use logical operators: ```json { "logical_operator": [ {"key": "metadata_key", "operator": "comparison", "value": "target_value"} ] } ``` Example filter structure: ```json { "all": [ {"key": "category", "operator": "eq", "value": "documentation"} ] } ``` ### Generated Metadata Fields [#generated-metadata-fields] You can target auto-generated chunk metadata by prefixing the key with `generated_metadata.`. This works the same way as regular metadata filters and is especially useful for filtering on values described in [Generated Metadata](/docs/stores/store-files/generated-metadata). ```json { "any": [ {"key": "generated_metadata.file_type", "operator": "eq", "value": "text/markdown"}, {"key": "generated_metadata.language", "operator": "eq", "value": "en"} ] } ``` Use dot notation to drill into nested structures, e.g. `generated_metadata.chunk_headings.level`. ### System Fields [#system-fields] In addition to file metadata and generated metadata, you can filter on a small set of indexed system fields by referencing them directly (without any prefix): * `file_id` — the file the chunk belongs to * `chunk_index` — the position of the chunk within its file ```json { "all": [ {"key": "file_id", "operator": "eq", "value": "f3c1..."}, {"key": "chunk_index", "operator": "lt", "value": 10} ] } ``` This is useful for restricting search to a specific file or to the leading chunks of each file (e.g. titles or introductions). ## Logical Operators [#logical-operators] Combine multiple conditions using logical operators to create sophisticated filters: ### All (AND Operation) [#all-and-operation] All conditions must be true: ```json { "all": [ {"key": "category", "operator": "eq", "value": "documentation"}, {"key": "language", "operator": "eq", "value": "python"}, {"key": "status", "operator": "eq", "value": "published"} ] } ``` ### Any (OR Operation) [#any-or-operation] At least one condition must be true: ```json { "any": [ {"key": "language", "operator": "eq", "value": "python"}, {"key": "language", "operator": "eq", "value": "javascript"}, {"key": "language", "operator": "eq", "value": "typescript"} ] } ``` ### None (NOT Operation) [#none-not-operation] None of the conditions should be true: ```json { "none": [ {"key": "status", "operator": "eq", "value": "deprecated"}, {"key": "status", "operator": "eq", "value": "draft"} ] } ``` ## Comparison Operators [#comparison-operators] ### Equality and Comparison Operators [#equality-and-comparison-operators] ```json // Equal to {"key": "status", "operator": "eq", "value": "published"} // Not equal to {"key": "status", "operator": "not_eq", "value": "draft"} // Greater than {"key": "priority", "operator": "gt", "value": 5} // Greater than or equal to {"key": "created_at", "operator": "gte", "value": "2024-01-01"} // Less than {"key": "rating", "operator": "lt", "value": 3.0} // Less than or equal to {"key": "rating", "operator": "lte", "value": 4.5} // Value in list {"key": "tags", "operator": "in", "value": ["tutorial", "guide"]} // Value not in list {"key": "language", "operator": "not_in", "value": ["deprecated", "legacy"]} // Contains: substring match on a text field (case-sensitive) {"key": "title", "operator": "contains", "value": "guide"} // Contains: membership in a list/array field (e.g. a "tags" array that includes "tutorial") {"key": "tags", "operator": "contains", "value": "tutorial"} // Regex matching (case-sensitive) {"key": "title", "operator": "regex", "value": "^red.*$"} // String starts with (case-sensitive) {"key": "category", "operator": "starts_with", "value": "/Users"} // String does not start with {"key": "path", "operator": "not_like", "value": "/tmp/*"} ``` **`contains` vs `in`:** `in` checks whether a field's value is one of the values you provide (`field ∈ [a, b, c]`). `contains` is the reverse — it checks whether the field itself contains the value you provide. On a **text** field it matches a substring; on a **list/array** field (such as `tags` or an `acl` array) it matches when the array includes that exact element. Both are case-sensitive. ## Data Type Filtering [#data-type-filtering] ### String Values [#string-values] Case-sensitive by default - ensure consistent casing in your metadata: ```json // String Values (case-sensitive) {"key": "category", "operator": "eq", "value": "Documentation"} // Won't match "documentation" // Use consistent casing in metadata { "category": "documentation", // lowercase "status": "published", // lowercase "team": "engineering" // lowercase } ``` ### Numeric Values [#numeric-values] Support integer and float comparisons: ```json // Numeric Values {"key": "priority", "operator": "gt", "value": 5} {"key": "score", "operator": "gte", "value": 0.8} ``` ### Boolean Values [#boolean-values] Support true/false conditions: ```json // Boolean Values {"key": "is_public", "operator": "eq", "value": true} {"key": "deprecated", "operator": "eq", "value": false} ``` ### Date Values [#date-values] Recommend ISO 8601 format: ```json // Date Values (ISO 8601 format recommended) {"key": "created_at", "operator": "gte", "value": "2024-01-01"} {"key": "last_updated", "operator": "lt", "value": "2024-12-31T23:59:59Z"} ``` ### Array/List Values [#arraylist-values] Support membership filtering: ```json // Array/List Values { "tags": ["tutorial", "python", "web"], "authors": ["alice", "bob"] } // Filter by array membership {"key": "tags", "operator": "in", "value": ["tutorial", "guide"]} ``` ## Combined Logical Operations [#combined-logical-operations] ### Nested Conditions [#nested-conditions] Complex multi-level filtering example: ```json { "all": [ {"key": "category", "operator": "eq", "value": "documentation"}, { "any": [ {"key": "language", "operator": "eq", "value": "python"}, {"key": "language", "operator": "eq", "value": "javascript"} ] } ], "none": [ {"key": "status", "operator": "eq", "value": "deprecated"} ] } ``` ### Advanced Filtering Example [#advanced-filtering-example] Here's a practical example demonstrating complex nested filters: # OpenCode (/docs/agent/integrations/opencode) Add [Toast 1](/docs/agent/models) as a subagent in OpenCode for fast, cheap, and accurate search. ## Prerequisites [#prerequisites] * [OpenCode](https://opencode.ai/docs/) installed * A Mixedbread API key from the [API Keys](https://platform.mixedbread.com/platform?next=api-keys) page ## Configure Mixedbread [#configure-mixedbread] Create or update `opencode.json` in your project root—the directory you open with OpenCode, typically alongside `.git`, `package.json`, or `pyproject.toml`: ```json { "$schema": "https://opencode.ai/config.json", "provider": { "mixedbread": { "npm": "@ai-sdk/openai-compatible", "name": "Mixedbread", "options": { "baseURL": "https://api.mixedbread.com/v1" }, "models": { "toast-1": { "name": "Toast 1", "limit": { "context": 131072, "output": 4096 } } } } } } ``` The provider ID is `mixedbread`, and the model ID is `toast-1`. Together, OpenCode refers to the model as `mixedbread/toast-1`. To make Mixedbread available in every project, put the same configuration in `~/.config/opencode/opencode.json` instead. A project-level `opencode.json` overrides the global configuration. Start OpenCode and enter: ```text /connect ``` Select **Other**, enter `mixedbread` as the provider ID, then paste your Mixedbread API key. The provider ID must exactly match the key in `opencode.json`. Enter `/models`, then select **Mixedbread → Toast 1**. To make Toast 1 the default for the project, add the top-level `model` field to `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "model": "mixedbread/toast-1" } ``` Merge this field into the provider configuration from the first step. ## Use Toast 1 as a subagent [#use-toast-1-as-a-subagent] You can keep another model as your primary OpenCode model and use Toast 1 for focused repository investigations. Merge this `agent` entry into your existing `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "agent": { "toast": { "description": "Investigates complex repository questions and returns concise, evidence-backed findings", "mode": "subagent", "model": "mixedbread/toast-1", "permission": { "edit": "deny", "bash": "deny" } } } } ``` Invoke the subagent directly with an `@` mention: ```text @toast Trace the authentication flow in this repository and summarize the key files. ``` OpenCode can also delegate to the subagent when its description matches the task. An explicit `@toast` mention is the most predictable way to select it. # Agentic Search with Toast-1 (/docs/stores/search/agentic-search) A single search returns the chunks closest to one query. That works for lookups, but breaks down on questions that need multiple sources, span several time periods, or hide their best phrasing from the user. Agentic Search wraps the search endpoint in a loop driven by [Toast-1](/docs/agent/models), our specialized search model: the agent runs parallel sub-queries, analyzes metadata facets, inspects retrieved results, and decides whether to search again before submitting a final ranked chunk list. The response shape is identical to a normal search (a ranked list of scored chunks), so Agentic Search is a drop-in upgrade for quality-sensitive queries. If you want to run Toast-1 against your own tools instead of the hosted loop, see [Build your own harness](/docs/agent/build-your-own-harness). ## When to use it [#when-to-use-it] Reach for Agentic Search when one search is not enough. Typical signals: * The question fans out across multiple entities, years, or sources (e.g. *"Compare revenue, headcount, and churn across 2020 to 2025"*). * The user phrasing is conversational and underspecified, but the underlying answer needs precise terminology. * A single top-k list keeps missing relevant chunks and/or includes irrelevant chunks because the right query isn't obvious upfront. It is slower than a single search because of the extra LLM calls and retrievals, so use plain [Search](/docs/stores/search) for narrow lookups and reach for Agentic Search when quality matters more than latency. ## Basic Usage [#basic-usage] Agentic Search is powered by [Toast 1](/docs/agent/models), our specialized search agent. Enable it by setting `search_options.agentic` to `true`: The output uses the same shape as the normal search response. When `agentic` is enabled, `rewrite_query` and `rerank` are ignored, since the agent handles query decomposition and ranking itself. ## How it Works [#how-it-works] Each agentic search runs as a bounded loop: 1. **Initial search and metadata.** The original query is run as-is while compact metadata facets are fetched for the selected stores. This guarantees the exact phrasing is always represented in the candidate pool, even if the agent later goes off in a different direction. 2. **Plan and retrieve.** The agent inspects results, then either submits a ranking or issues up to 8 parallel retrieval calls: `search_corpus` for focused semantic sub-queries, `grep` for exact tokens, codes, identifiers, and regex patterns, and `filter_chunks` for metadata-first filtering and sorting. A `prune_context` tool lets the agent drop chunks it has ruled out to stay within its context budget. 3. **Iterate.** Step 2 repeats until the agent has enough context or exhausts its budget of 4 rounds (the final ranking turn included). New chunks are merged into a deduplicated pool. 4. **Submit ranking.** The agent calls `submit_ranking` with the chunks it considers most relevant. With `strict_top_k=true`, the submitted ranking is constrained to exactly `top_k` chunks. If the agent stops without submitting a ranking, the service forces one final ranking call so you always get a result back. ## Configuration [#configuration] Pass an object instead of `true` to steer the agent: ### Parameters [#parameters] All fields under `search_options.agentic` are optional. | Parameter | Type | Default | Description | | -------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `instructions` | string | `null` | Free-form guidance appended to the agent's system prompt (up to 5,000 characters). Use it to bias the agent toward specific entities, metrics, source types, or ranking criteria. Followed only when not in conflict with the built-in search rules. | | `strict_top_k` | boolean | `false` | When `true`, `submit_ranking` is constrained to exactly `top_k` chunks and the resolved ranking is capped at `top_k`. When `false`, the agent can return all the chunks it considers relevant. | #### Example instructions [#example-instructions] * `"Prefer primary sources over summaries when both are available."` * `"Prioritize the most recent fiscal year, then compare year-over-year."` * `"Treat tables and figures as authoritative; treat marketing copy as weak signal."` ## Combining with other features [#combining-with-other-features] The fields outside `search_options.agentic` still affect the agentic run: * **`top_k`**: target result size, and the exact size required when `strict_top_k=true`. * **`filters`**: applied to local store retrievals, not just the original. * **`file_ids`**: local store retrievals are constrained to these files. * **`store_identifiers`**: semantic and wide retrievals search across all listed stores. Include `mixedbread/web` to let the agent pull in [web search](/docs/stores/search/web-store) results alongside your own stores. * **`search_options.score_threshold`**: applied as a final filter after ranking; can return fewer than `top_k` chunks even with `strict_top_k=true`. `search_options.rewrite_query` and `search_options.rerank` are ignored when agentic is enabled, since the agent owns query decomposition and ranking. ## Observability [#observability] Every agentic search emits a structured trace. The dashboard renders it as a waterfall view of LLM generations, metadata inspection, retrieval tool calls, and sub-queries, with timing and round numbers, so you can see exactly what the agent did and where time was spent:

Agentic Search trace in the dashboard, showing a waterfall of search and generation spans across multiple rounds for a single query.

The same data is available programmatically by listing store events with `event_type=agentic_search`. Each event captures the original query, instructions, rounds executed, token usage, and the ordered list of tool calls the agent issued (with `arguments`, `result`, `duration`, and any `error`). Tool call fields follow the [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/), so traces interoperate with standard observability tooling. For the full response schema, see [List Store Events](/api-reference/endpoints/stores/events/list-store-events). Use these events to debug unexpected results ("why didn't the agent find X?") or build dashboards on top of the agent's behavior. ## Tips [#tips] * **Start with the defaults.** `agentic: true` with no instructions is a strong baseline for most workloads. * **Use `instructions` to encode domain knowledge** the agent can't infer from the query (e.g. preferred source types, entity disambiguation rules). * **Keep `strict_top_k=false`** when you need high precision, as the agent will not include irrelevant chunks in its output. * **Combine with `mixedbread/web`** for hybrid runs that mix internal stores with the open web in a single ranked list. * **Inspect the trace when results surprise you.** The dashboard waterfall and the events feed show every round, sub-query, and tool call, so you can see which searches the agent ran and why a chunk was or wasn't found. # Metadata Facets (/docs/stores/search/facets) Metadata facets allow you to group search results by metadata values. This is useful for exploring your data based on metadata properties like category, language, or author. You can retrieve facets for a single Store or across multiple Stores. ## Basic Metadata Facets [#basic-metadata-facets] To get all metadata facets for one or more Stores, you can call: This returns the unnested metadata values with their respective counts: ```json { "facets": { "author": { "John Doe": 1, "Jane Doe": 2 }, "language": { "english": 2, "spanish": 1 } } } ``` If you want to get the facets for a specific field, you can pass the field name to the `facets` parameter. We recommend this if your metadata contains many unique values for a field. ## Nested Metadata Facets [#nested-metadata-facets] For complex metadata structures with nested objects, you can access specific nested fields by using dot notation (`.`) to separate the field hierarchy. This allows you to create facets for deeply nested properties without flattening your entire metadata structure. For example, if your documents have metadata like: This returns the nested metadata values with their respective counts: ```json { "facets": { "city.name": { "New York": 2, "London": 1 }, "city.country": { "United States": 2, "United Kingdom": 1 } } } ``` ## Multi-Store Facets [#multi-store-facets] You can retrieve facets across multiple Stores by providing an array of Store identifiers. This is useful when you want to explore metadata across different data sources or Store versions. ```python facets = client.stores.metadata_facets( store_identifiers=["docs-v1", "docs-v2", "blog-posts"], facets=["category", "language"] ) ``` The response will aggregate facet counts across all specified Stores, giving you a unified view of your metadata distribution. ## Filtering Search Results [#filtering-search-results] Metadata facets can be obtained for search results by using the same parameters as the search endpoint. For example, to get the facets for a specific query, you can call: # Search (/docs/stores/search) Search your Store using natural language to find exactly what you need. Stores understand the meaning behind your queries, not just keywords, making it perfect for conversational search and complex questions. ## Basic Search [#basic-search] Search for chunks of content across your Store: When you search, Stores understand your natural language query and find the most relevant content across all your files. Results are automatically ranked by relevance with confidence scores. For complete details on chunk object structure including all content types and properties, see [Data Models](/docs/stores/data-models#store-chunk). ## Search Options [#search-options] ### Top-k Results [#top-k-results] Control the number of results returned: **Optimization Tips:** * Start with `top_k=10` for most use cases * Increase for comprehensive searches * Decrease for faster response times ### Filter [#filter] Filter search results to narrow down your search scope. Store search supports two types of filtering: For complete metadata filtering capabilities and advanced patterns, see [Metadata Filtering](/docs/stores/metadata-filtering). ### Rerank [#rerank] Improve search result quality by reranking results with specialized models: Reranking applies a second-stage ranking model to improve relevance, especially useful for complex queries or when initial results need refinement. You can use simple boolean (`True`) or configure advanced options with model selection and metadata inclusion. Learn more about [Rerank](/docs/stores/search/rerank) for advanced reranking strategies and model options. ### Rewrite Query [#rewrite-query] Let a specialized AI model rewrite your query to ge the most optimal semantic search experience. It automatically applies best practices like adding more context and using full semantic qualifiers instead of keywords. You can get the rewritten query by calling the `/v1/stores/{store_identifier}/events` endpoint. **Considerations:** * The latency increases due to additional agent calls * Not every query needs to be rewritten ### Multi Store Search [#multi-store-search] Search across multiple Stores simultaneously: **Considerations:** * Results are merged and re-ranked together * May need higher top\_k for diverse results * Different Stores may have different metadata schemas ### Agentic Search [#agentic-search] For complex questions that need multiple sources, an agent can plan, run, and rank a series of searches for you in a single call: The response shape matches a normal search. See [Agentic Search](/docs/stores/search/agentic-search) for the full parameter reference, configuration examples, and how to inspect the agent's tool calls and token usage via the events endpoint. Additional options let you steer the agent and the result shape: * `strict_top_k` (default `false`): return only chunks the agent considers relevant. Set to `true` to always return exactly the `top_k` most relevant results the agent found. * `instructions`: free-form guidance for the agent, e.g. preferred source types or ranking criteria. ### Web Search [#web-search] Search the web using the same API by including `mixedbread/web` as a store identifier. You can use it standalone or combine it with your own stores for hybrid search that merges web results with your internal knowledge base. For detailed web search capabilities and response format, see [Web Store](/docs/stores/search/web-store). # Question Answering (/docs/stores/search/question-answering) Question Answering turns your store into an AI-powered knowledge base.
Instead of returning raw content like search, it generates complete answers based on the retrieved context. ## Basic Question Answering [#basic-question-answering] Ask questions and get augmented answers based on your Store content: Multimodal support enables: * **Image understanding**: Answers based on diagrams, charts, and visuals * **OCR text**: Extracted text from images contributes to answers Pass `instructions` when you want to control answer style, scope, or formatting. Typical uses include enforcing concise bullet points, prioritizing specific facts, or asking the model to cite only the strongest supporting passages. ## Defaults and configuration [#defaults-and-configuration] By default, Question Answering uses citations and multimodal context.
To change behavior, pass `qa_options` explicitly. ## Example Response [#example-response] * **Answer**: AI-generated answer. May include citation tags like ``. * **Sources**: Context used for the answer. Each entry includes: * `chunk_index`, `score`, `file_id`, `filename` * Content fields: `text`, `image_url`, with optional `ocr_text` * Use indices from `` to map to `sources[n]` # Reranking (/docs/stores/search/rerank) Reranking is an advanced feature that improves the quality and relevance of search results by using specialized models to re-evaluate and reorder the initial results. This second-pass approach significantly enhances result accuracy at the cost of slightly increased latency. ## Basic Configuration [#basic-configuration] The simplest way to enable reranking is to set `rerank=True` in your search request: This uses our default reranking model (`mixedbread-ai/mxbai-rerank-v3.1-listwise`) with standard settings to improve your search results. ## Advanced Configuration [#advanced-configuration] **Configuration Options:** * **Reranking Models**: Use any supported reranking model. Defaults to `"mixedbread-ai/mxbai-rerank-v3.1-listwise"` when not specified. See [Available Models](#available-models) below. * **Top-k Constraint**: The `top_k` value must be smaller than or equal to the first-stage retrieval count (your main `top_k` parameter). Defaults to `null`, which returns all results from the first stage (respects your main `top_k` parameter). * **Metadata Inclusion**: Defaults to `false`. Set to `true` to include all metadata, or provide a list of specific metadata keys to include. ## Available Models [#available-models] | Model | Type | Notes | | ------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mixedbread-ai/mxbai-rerank-v3.1-listwise` | Listwise | Default. Reads the candidate set as a whole and follows natural-language instructions. | | `mixedbread-ai/mxbai-rerank-v3-listwise` | Listwise | Reads the candidate set as a whole and follows natural-language instructions (e.g. prefer recent docs, primary sources over commentary). Available in preview; see the [announcement](/blog/listwise-rerank). | | `mixedbread-ai/mxbai-rerank-large-v2` | Pointwise | 1.5B-parameter model tuned for accuracy across 100+ languages. | # Web Store (/docs/stores/search/web-store) The Web Store lets you search the web using the same familiar Store API. Instead of searching your uploaded documents, it searches the internet and returns results in the same format as regular store searches. ## Basic Web Search [#basic-web-search] Search the web by using `mixedbread/web` as a store identifier: Each result includes the page title, the source URL (available in both the `filename` field and `metadata.url`), and relevant excerpts from the page content. ## Hybrid Search: Web + Your Data [#hybrid-search-web--your-data] Combine web results with your own stores for comprehensive search. This is useful when you want to augment your internal knowledge base with up-to-date information from the web. When combining web search with regular stores, results from all sources are merged together and reranked for consistent relevance scoring. The final response contains the top results based on combined relevance across all sources. ## Response Format [#response-format] Web search results follow the same structure as regular store search results: * `text`: Contains the page title followed by relevant excerpts * `filename`: The source URL * `metadata.url`: The source URL (same as filename) * `metadata.title`: The page title * `metadata.source`: Always `"web_search"` for web results * `store_id`: Fixed ID for the web store ## Considerations [#considerations] Web search results are always reranked for optimal relevance. Usage counts toward your API rate limits like any other store search. Note that metadata filters such as `file_ids` do not apply to web search results. Results reflect current web content at search time, providing fresh information for your queries. # Supported File Types (/docs/stores/store-files/file-types) Stores natively understand a wide range of file formats through multimodal AI. No extraction needed, the system directly understands text, images, and complex layouts for semantic search. ## Documents [#documents] | Format | Extensions | | --------------------- | ------------------------------------------ | | **PDF** | `.pdf` | | **Word** | `.doc`, `.docx`, `.dotx`, `.docm`, `.dotm` | | **OpenDocument Text** | `.odt` | | **Rich Text Format** | `.rtf` | | **Text** | `.txt` | | **Markdown** | `.md`, `.mdx` | | **Email** | `.eml` | ## Presentations [#presentations] | Format | Extensions | | ----------------------------- | ------------------------- | | **PowerPoint** | `.ppt`, `.pptx` | | **PowerPoint Slideshow** | `.ppsx` | | **PowerPoint Add-in** | `.ppam` | | **PowerPoint Macro-Enabled** | `.pptm`, `.potm`, `.ppsm` | | **OpenDocument Presentation** | `.odp` | ## Spreadsheets [#spreadsheets] | Format | Extensions | | -------------------------------- | ---------- | | **Excel Workbook** | `.xlsx` | | **Excel Macro-Enabled Workbook** | `.xlsm` | ## Code [#code] | Language | Extensions | | -------------- | ------------------------------------- | | **Python** | `.py` | | **JavaScript** | `.js` | | **TypeScript** | `.ts` | | **Java** | `.java` | | **C#** | `.cs` | | **C** | `.c`, `.h` | | **C++** | `.cpp`, `.cxx`, `.cc`, `.hpp`, `.hxx` | | **Go** | `.go` | | **HTML** | `.html`, `.htm` | | **Ruby** | `.rb` | | **Rust** | `.rs` | ## Images [#images] | Format | Extensions | | -------- | --------------- | | **JPEG** | `.jpg`, `.jpeg` | | **PNG** | `.png` | | **WebP** | `.webp` | | **AVIF** | `.avif` | ## Specialized Formats [#specialized-formats] | Format | Extensions | Notes | | -------------------- | ---------- | ------------------------------------------------------------- | | **Mixedbread JSON** | `.mxjson` | [Pre-chunked content format](/docs/stores/store-files/mxjson) | | **Mixedbread JSONL** | `.mxjsonl` | [Pre-chunked content format](/docs/stores/store-files/mxjson) | The [Mixedbread JSON format](/docs/stores/store-files/mxjson) allows direct ingestion of pre-chunked content. Use it when you have custom chunking logic, need to preserve specific chunk boundaries, or want to include pre-computed metadata like OCR text or transcriptions. ## Audio [#audio] | Format | Extensions | | -------------- | -------------- | | **MP3** | `.mp3` | | **WAV** | `.wav` | | **OGG** | `.ogg`, `.oga` | | **M4A** | `.m4a` | | **WebM Audio** | `.weba` | | **AAC** | `.aac` | | **FLAC** | `.flac` | Audio files require the `mixedbread-ai/mxbai-wholembed-v3` encoder. ## Video [#video] | Format | Extensions | | ------------- | ---------- | | **MP4** | `.mp4` | | **WebM** | `.webm` | | **QuickTime** | `.mov` | | **AVI** | `.avi` | | **OGG Video** | `.ogv` | Video files require the `mixedbread-ai/mxbai-wholembed-v3` encoder. # Generated Metadata (/docs/stores/store-files/generated-metadata) Mixedbread Stores automatically generate metadata for each file ingested. This generated metadata provides structured information about the content of the file, including language, size, headings, number of pages, and more. The generated metadata can be retrieved using the `generated_metadata` chunk field. ## Metadata Types [#metadata-types] The `generated_metadata` object is a typed structure discriminated by the `type` field. If `type` is not present, it is inferred from `file_type` (MIME); otherwise it defaults to `text`. Supported `type` values: `markdown`, `text`, `pdf`, `code`, `audio`, `video`, `image`. Every metadata object includes a `file_extension` field (e.g., `".mp3"`, `".pdf"`) reflecting the original file extension. For a full list of supported file formats, see [Supported File Types](/docs/stores/store-files/file-types). ## Markdown - Heading Extraction [#markdown---heading-extraction] When processing markdown files, the system automatically extracts and preserves heading structure to enhance search relevance and provide context. This feature works for all markdown formats (`.md`, `.markdown`, `.mdx`). ### What You Get [#what-you-get] Each markdown chunk’s `generated_metadata` includes: 1. `type`: Always `"markdown"`. 2. `file_type`: Always `"text/markdown"`. 3. `language`: Detected language of the text. 4. `word_count`: Word count for the chunk. 5. `file_size`: File size in bytes. 6. `chunk_headings`: Headings found within the current chunk (`[{ level: number, text: string }]`). 7. `heading_context`: The document structure context leading up to this chunk (`[{ level: number, text: string }]`). 8. `start_line`: Starting line number of the chunk in the source file. 9. `num_lines`: Number of lines in the chunk. ### Example Output [#example-output] Consider this markdown document: ````markdown # Getting Started ## Installation ### Prerequisites You need Python 3.8+ installed. ... ### Setup Run the following command: ```bash pip install package ``` ... ## Configuration ### Environment Variables Set these variables in your `.env` file. ### Database Setup Configure your database connection. ```` When processed, the chunks would have `generated_metadata` like this: **Chunk 1 (Prerequisites section):** ```json { "type": "markdown", "file_type": "text/markdown", "language": "en", "word_count": 6, "file_size": 1234, "chunk_headings": [ {"level": 1, "text": "Getting Started"}, {"level": 2, "text": "Installation"}, {"level": 3, "text": "Prerequisites"} ], "heading_context": [] } ``` **Chunk 2 (Setup section):** ```json { "type": "markdown", "file_type": "text/markdown", "language": "en", "word_count": 12, "file_size": 1234, "chunk_headings": [ {"level": 3, "text": "Setup"} ], "heading_context": [ {"level": 1, "text": "Getting Started"}, {"level": 2, "text": "Installation"}, {"level": 3, "text": "Prerequisites"} ] } ``` **Chunk 3 (Configuration section):** ```json { "type": "markdown", "file_type": "text/markdown", "language": "en", "word_count": 20, "file_size": 1234, "chunk_headings": [ {"level": 2, "text": "Configuration"}, {"level": 3, "text": "Environment Variables"}, {"level": 3, "text": "Database Setup"} ], "heading_context": [ {"level": 1, "text": "Getting Started"}, {"level": 2, "text": "Installation"}, {"level": 3, "text": "Setup"} ] } ``` ## Text - Common Fields [#text---common-fields] Plain text chunks include a simpler `generated_metadata` shape: * `type`: `"text"` * `file_type`: `"text/plain"` * `language`: Detected language of the text * `word_count`: Word count for the chunk * `file_size`: File size in bytes * `start_line`: Starting line number of the chunk in the source file * `num_lines`: Number of lines in the chunk ### Example [#example] ```json { "type": "text", "file_type": "text/plain", "language": "en", "word_count": 57, "file_size": 2048, "start_line": 0, "num_lines": 15 } ``` ## Code - Language and Size [#code---language-and-size] For supported source files (e.g., Python, TypeScript, Java, C#), `generated_metadata` includes: * `type`: `"code"` * `file_type`: One of `text/x-python`, `text/x-script.python`, `application/typescript`, `text/typescript`, `text/x-java-source`, `text/x-csharp`, or `application/javascript` * `language`: Detected programming language * `word_count`: Tokenized word count approximation for code * `file_size`: File size in bytes * `start_line`: Starting line number of the chunk in the source file * `num_lines`: Number of lines in the chunk ### Example [#example-1] ```json { "type": "code", "file_type": "text/x-python", "language": "python", "word_count": 120, "file_size": 8192, "start_line": 0, "num_lines": 42 } ``` ## PDF - Document Stats [#pdf---document-stats] PDF chunks have specialized document-level stats: * `type`: `"pdf"` * `file_type`: `"application/pdf"` * `total_pages`: Total number of pages in the document * `total_size`: Total size of the original file in bytes ### Example [#example-2] ```json { "type": "pdf", "file_type": "application/pdf", "total_pages": 42, "total_size": 1048576 } ``` ## Image - Dimensions [#image---dimensions] Image chunks include basic dimensional metadata: * `type`: `"image"` * `file_type`: String (MIME type, e.g., `image/jpeg`, `image/png`) * `file_size`: File size in bytes * `width`: Image width in pixels * `height`: Image height in pixels ### Example [#example-3] ```json { "type": "image", "file_type": "image/jpeg", "file_size": 204800, "width": 1920, "height": 1080 } ``` ## Audio - Media Information [#audio---media-information] Audio chunks include specialized media metadata: * `type`: `"audio"` * `file_type`: String (MIME type, e.g., `audio/mpeg`, `audio/wav`) * `file_size`: File size in bytes * `total_duration_seconds`: Total duration of the audio in seconds * `sample_rate`: Audio sample rate in Hz * `channels`: Number of audio channels * `audio_format`: Audio format code * `bpm`: Detected beats per minute (optional, only present when detected) * `start_time_seconds`: Start time of the chunk in seconds * `end_time_seconds`: End time of the chunk in seconds * `duration_seconds`: Duration of the chunk in seconds * `chunk_size_bytes`: Size of the chunk in bytes ### Example [#example-4] ```json { "type": "audio", "file_type": "audio/mpeg", "file_size": 5242880, "total_duration_seconds": 180.5, "sample_rate": 44100, "channels": 2, "audio_format": 1, "start_time_seconds": 0, "end_time_seconds": 38.93, "duration_seconds": 38.93, "chunk_size_bytes": 650736 } ``` ## Video - Media Information [#video---media-information] Video chunks include specialized media metadata: * `type`: `"video"` * `file_type`: String (MIME type, e.g., `video/mp4`, `video/webm`) * `file_size`: File size in bytes * `total_duration_seconds`: Total duration of the video in seconds * `fps`: Frames per second * `width`: Video width in pixels * `height`: Video height in pixels * `frame_count`: Total number of frames * `has_audio_stream`: Whether the video contains an audio track * `bpm`: Detected beats per minute (optional, only present when detected) * `start_time_seconds`: Start time of the chunk in seconds * `end_time_seconds`: End time of the chunk in seconds * `duration_seconds`: Duration of the chunk in seconds * `chunk_size_bytes`: Size of the chunk in bytes ### Example [#example-5] ```json { "type": "video", "file_type": "video/mp4", "file_size": 15728640, "total_duration_seconds": 120.0, "fps": 30.0, "width": 1920, "height": 1080, "frame_count": 3600, "has_audio_stream": true, "start_time_seconds": 0.0, "end_time_seconds": 120.0, "duration_seconds": 120.0, "chunk_size_bytes": 2097152 } ``` ## Type Inference and Flexibility [#type-inference-and-flexibility] * If `type` is not present in `generated_metadata`, it is inferred from `file_type` when possible. * If neither `type` nor a recognized `file_type` is present, the `type` defaults to `"text"`. * The system may include additional fields as needed for future enhancements; clients should read the documented fields and ignore unknown ones. # Create Files (/docs/stores/store-files) Upload files to your Stores to make them instantly searchable. Stores support a variety of file formats and languages—you just upload your data and we take care of the optimal processing. Let's start with the upload method. ## Basic File Ingestion [#basic-file-ingestion] Upload a single file to your Store: For complete details on the file object structure including all properties and status values, see [Data Models](/docs/stores/data-models#store-file). ## Ingestion Options [#ingestion-options] ### External ID [#external-id] You can optionally assign a unique external ID to the file. This identifier lets you reference the file later and makes it easy to replace or update the same file by using the same external ID. The ID can be any string value, though we recommend using a relative file path to mirror your repository's structure. **Overwrite Behavior**: By default, uploading a file with an existing `external_id` will overwrite the previous file. You can control this behavior with the `overwrite` parameter: * `overwrite: true` (default): Replaces the existing file with the same `external_id` * `overwrite: false`: Prevents overwriting and returns an error if the `external_id` already exists This makes it easy to update files in your Store while preventing accidental overwrites when needed. ### File Types [#file-types] Stores understand any data format: * **Documents**: PDFs (including scanned), Word docs, text files, Markdown * **Presentations**: PowerPoint slides with images and text * **Code**: Python, JavaScript, TypeScript, Java, C# * **Images**: Photos, diagrams, charts with OCR and visual understanding * **Specialized**: Pre-structured JSON/JSONL formats Each file type is automatically processed to understand both text and visual content, preserving context and meaning. For the complete list of supported formats and processing details, see [Supported File Types](/docs/stores/store-files/file-types). ### Metadata [#metadata] Enhance your files with structured metadata for better organization and filtering: Metadata is structured information about your files that enables powerful filtering, organization, and search capabilities. It's inherited by all chunks created from the file, enabling precise filtering during search operations. **Supported Metadata Types:** * **String values**: Categories, names, tags, status values * **Numeric values**: Scores, versions, counts, measurements * **Boolean values**: Flags, permissions, feature toggles * **Date/time values**: Timestamps, deadlines, publishing dates * **Array values**: Multiple values, collections, tags For supported metadata types, see [Supported Metadata Types](/docs/stores/store-files/metadata-types). Learn more about [Metadata Filtering](/docs/stores/metadata-filtering) to search with metadata filtering. ### Parsing Strategy [#parsing-strategy] Control how your files are processed with parsing strategy options (see examples above): **Available Parsing Strategies:** * **`fast`** (default): Optimized for speed, good quality for most documents * **`high_quality`**: Enhanced processing for complex layouts, including OCR, transcription, and summaries for text, audio and visual content ## Upload Helpers [#upload-helpers] The SDK provides two convenient helpers for file ingestion: * `upload`: Uploads the file and immediately returns the created Store File. The file's `status` begins as `pending` and progresses to `in_progress` and `completed` in the background. Use this when you want to upload files asynchonisly and as fast as possible * `uploadAndPoll` / `upload_and_poll`: Uploads the file and polls until processing completes. Use this when you want to proceed only after complete processing. For example if the upload is directly followed by a search method. To monitor progress without blocking, retrieve the file by ID and check its `status` using [Retrieve Store File](/docs/stores/store-files/manage-store-files#retrieve-store-file). ## Store File Status [#store-file-status] * **`pending`**: File uploaded and queued for processing * **`in_progress`**: Active processing (extraction, chunking, embedding, indexing) * **`completed`**: Successfully processed and searchable * **`failed`**: Processing error (check `last_error` for details) * **`cancelled`**: Processing stopped manually or automatically You can retrieve the status of any file using [Retrieve Store File](/docs/stores/store-files/manage-store-files#retrieve-store-file). # Manage Files (/docs/stores/store-files/manage-store-files) Once files are uploaded to your Store, you can inspect and manage them using these core operations. All operations work with either the file ID or the file's external ID (if provided during upload). **File Identifiers**: You can reference files using either their UUID (`file_id`) or their external ID. External IDs support slashes, making it easy to use file paths as identifiers (e.g., `docs/api/authentication.md`). ## Retrieve Store File [#retrieve-store-file] Get detailed information about a specific file using either its ID or external ID: By default, `retrieve` returns the file object and its file-level metadata. The `chunks` field is `null` unless you explicitly request chunks with `return_chunks`. The response includes processing status, metadata, usage statistics, and error details if applicable. For complete details on file object properties, see [Data Models](/docs/stores/data-models#store-file). ## Retrieve File Chunks [#retrieve-file-chunks] Use `return_chunks` when you want the parsed, searchable representation of a file instead of only the file-level metadata. Use this when you want to inspect parsed text, OCR output, transcriptions, or chunk-level `generated_metadata`. **File Metadata vs. Chunk Metadata**: `metadata` is your file-level metadata and is shared across all chunks from that file. `generated_metadata` is produced during parsing and can differ for each chunk. For complete details on chunk fields and chunk types, see [Data Models](/docs/stores/data-models#store-chunk). ### Retrieve Specific Chunks by Index [#retrieve-specific-chunks-by-index] `return_chunks` also accepts a list of chunk indices. This is useful when you want a small, exact slice of a file instead of every chunk. Chunk indices are zero-based and correspond to the file's parsed chunk order. ### Retrieve the Exact Chunk Returned by Search [#retrieve-the-exact-chunk-returned-by-search] Search results include both `file_id` and `chunk_index`, so you can use them to load the exact source chunk that matched a query. This is the easiest way to go from a semantic search hit back to the precise chunk in the original file. ## File Status and Availability [#file-status-and-availability] To reliably inspect chunks, wait until the file reaches `completed` status. * `pending`: The file was accepted and queued for processing * `in_progress`: Parsing, chunking, embedding, and indexing are still running * `completed`: Chunks are ready to inspect and search * `failed`: Processing failed; inspect `last_error` for details * `cancelled`: Processing stopped before completion If you need a file to be ready before continuing, use `uploadAndPoll` / `upload_and_poll` during ingestion or poll `retrieve` until the status becomes `completed`. ## List Store Files [#list-store-files] View all files in your Store. The list operation uses cursor-based pagination: **Pagination Details**: For complete information about cursor-based pagination including parameters, response format, and advanced usage patterns, see the [Pagination Reference](/api-reference/pagination). ### Metadata Filtering [#metadata-filtering] Filter Store Files based on their metadata. **Complete Filtering Guide**: For detailed information about filter operators, logical operations, data types, and advanced patterns, see [Metadata Filtering](/docs/stores/metadata-filtering). ## Paginate and Filter Files [#paginate-and-filter-files] List all available files and filter them by status. This operation combines cursor-based pagination with the status filter to retrieve only the subsets of files you care about. For a complete explanation of cursor-based pagination options, see the [Pagination Reference](/api-reference/pagination). ## Delete Store File [#delete-store-file] Remove files from your Store: **Important**: Deleting a file permanently removes: * The original file from storage * All generated chunks and embeddings * Associated metadata and search indexes * Processing history and logs If you want to replace a file instead of deleting it first, upload new content with the same `external_id`. By default, uploads with the same `external_id` overwrite the previous version. For details, see [File Ingestion](/docs/stores/store-files#external-id). # Supported Metadata Types (/docs/stores/store-files/metadata-types) Metadata is structured information about your files that enables powerful filtering, organization, and search capabilities. This page covers **what types of metadata you can store** and how to structure them effectively. **Looking for filtering syntax?** This page covers metadata types and structure. For filtering operations and syntax, see [Metadata Filtering](/docs/stores/metadata-filtering). ## Understanding Metadata [#understanding-metadata] * **File-Level**: Metadata attached to entire files * **Inheritance**: Chunks inherit metadata from their parent file * **Filtering**: Use metadata to narrow search results ([learn more](/docs/stores/metadata-filtering)) * **Content Organization**: Structure content for easier discovery ## Metadata Types [#metadata-types] ### String Values [#string-values] **Best For**: Categories, names, tags, status values **Filtering**: Equality, inequality, pattern match (like, not like) ### Numeric Values [#numeric-values] **Best For**: Scores, versions, counts, measurements **Filtering**: Comparisons (`>`, `<`, `>=`, `<=`) ### Boolean Values [#boolean-values] **Best For**: Flags, permissions, feature toggles **Filtering**: True/false conditions ### Date/Time Values [#datetime-values] **Best For**: Timestamps, deadlines, publishing dates **Filtering**: Comparisons (`>`, `<`, `>=`, `<=`) **Format**: ISO 8601 recommended ### Array/List Values [#arraylist-values] **Best For**: Multiple values, collections # Multipart Upload (/docs/stores/store-files/multipart-upload) Both `upload` and `uploadAndPoll` / `upload_and_poll` automatically use multipart upload for large files. The file is split into chunks and uploaded in parallel, improving reliability and speed. No extra configuration is needed — it just works. ## Default Behavior [#default-behavior] Files over 100MB automatically use multipart upload. The existing upload calls work without any changes: ## Custom Threshold [#custom-threshold] Lower the threshold to trigger multipart upload for smaller files: ## Custom Concurrency [#custom-concurrency] Control how many parts upload in parallel. The default is 5 concurrent uploads: ## Custom Part Size [#custom-part-size] Control the size of each chunk. The default part size is 100MB: ## Progress Tracking [#progress-tracking] Get notified after each part finishes uploading. Works with both `upload` and `uploadAndPoll` / `upload_and_poll`: The callback receives a `PartUploadEvent` with the following fields: | Field | Description | | ---------------------------------- | ------------------------------------ | | `partNumber` / `part_number` | 1-based part number that completed | | `totalParts` / `total_parts` | Total number of parts in this upload | | `partSize` / `part_size` | Size of this part in bytes | | `uploadedBytes` / `uploaded_bytes` | Cumulative bytes uploaded so far | | `totalBytes` / `total_bytes` | Total file size in bytes | ## All Options Together [#all-options-together] Combine threshold, part size, concurrency, and progress tracking: ## Options Reference [#options-reference] | Option | Default | Description | | --------------------------------- | ------- | --------------------------------------------- | | `threshold` | `100MB` | Minimum file size to trigger multipart upload | | `partSize` / `part_size` | `100MB` | Size of each upload chunk | | `concurrency` | `5` | Number of parts uploaded in parallel | | `onPartUpload` / `on_part_upload` | — | Callback invoked after each part completes | # Mixedbread JSON Format (/docs/stores/store-files/mxjson) **This format is for specialized use cases** where you need complete control over chunking. For most workflows, use the standard [file upload](/docs/stores/store-files) — it handles chunking, metadata generation, and indexing automatically. The Mixedbread JSON format (`.mxjson` / `.mxjsonl`) allows you to ingest pre-chunked content directly into Stores. Use this format when you have already processed your content into chunks, want to preserve specific chunk boundaries, or need to include pre-computed metadata. ## Schema Checker [#schema-checker] Validate your mxjson files before uploading. Drop a `.mxjson` or `.mxjsonl` file below to check it against the current schema. You can also download the JSON Schema. ## File Formats [#file-formats] | Format | Extension | MIME Type | Structure | | -------------- | ---------- | ------------------------------------ | ------------------------- | | **JSON** | `.mxjson` | `application/vnd-mxbai.chunks-json` | Array of chunk objects | | **JSON Lines** | `.mxjsonl` | `application/vnd-mxbai.chunks-jsonl` | One chunk object per line | ## Chunk Structure [#chunk-structure] Each chunk in an mxjson file follows the same structure as [Store Chunks](/docs/stores/data-models#store-chunk). The `type` field determines which properties are required: * `text` - Text content * `image_url` - Image reference * `audio_url` - Audio reference * `video_url` - Video reference Each chunk contains exactly one modality. To represent a document with text and images, use separate chunks for each. ### Input Properties [#input-properties] When creating chunks for mxjson files, these properties control ingestion: | Property | Type | Required | Description | | -------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------ | | `type` | string | Yes | Chunk type: `text`, `image_url`, `audio_url`, `video_url` | | `mime_type` | string | No | Content MIME type (defaults per chunk type) | | `chunk_index` | integer | No | Position in file. Auto-generated sequentially if omitted | | `generated_metadata` | object | No | Typed metadata structure — see [Generated Metadata](/docs/stores/store-files/generated-metadata) | ### Text Chunks [#text-chunks] | Property | Type | Required | | -------- | ------- | ------------------------ | | `text` | string | Yes (1-65536 characters) | | `offset` | integer | No (default: 0) | ```json { "type": "text", "text": "Sourdough fermentation relies on wild yeast and lactic acid bacteria.", "mime_type": "text/plain", "generated_metadata": { "type": "text", "file_type": "text/plain", "language": "en", "word_count": 10, "file_size": 512 } } ``` ```json { "type": "object", "required": ["text"], "properties": { "type": { "const": "text", "default": "text" }, "text": { "type": "string", "minLength": 1, "maxLength": 65536 }, "mime_type": { "type": "string", "default": "text/plain" }, "offset": { "type": "integer", "default": 0 }, "chunk_index": { "type": ["integer", "null"], "default": null }, "generated_metadata": { "type": ["object", "null"], "default": null, "properties": { "type": { "const": "text" }, "file_type": { "const": "text/plain" }, "language": { "type": ["string", "null"] }, "word_count": { "type": ["integer", "null"] }, "file_size": { "type": ["integer", "null"] } }, "required": ["type"], "additionalProperties": true } } } ``` ### Image Chunks [#image-chunks] | Property | Type | Required | | --------------- | ------ | -------------------------- | | `image_url.url` | string | Yes (HTTP URL or data URI) | ```json { "type": "image_url", "image_url": { "url": "https://bakery.example.com/images/crumb-structure.png" }, "mime_type": "image/png", "generated_metadata": { "type": "image", "file_type": "image/png", "file_size": 204800, "width": 1200, "height": 800 } } ``` ```json { "type": "object", "required": ["image_url"], "properties": { "type": { "const": "image_url", "default": "image_url" }, "image_url": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "description": "HTTP URL or Data URI" } } }, "mime_type": { "type": "string", "default": "image/jpeg" }, "chunk_index": { "type": ["integer", "null"], "default": null }, "generated_metadata": { "type": ["object", "null"], "default": null, "properties": { "type": { "const": "image" }, "file_type": { "type": "string", "default": "image/jpeg" }, "file_size": { "type": ["integer", "null"] }, "width": { "type": ["integer", "null"] }, "height": { "type": ["integer", "null"] } }, "required": ["type"], "additionalProperties": true } } } ``` ### Audio Chunks [#audio-chunks] | Property | Type | Required | | --------------- | ------- | -------------------------- | | `audio_url.url` | string | Yes (HTTP URL or data URI) | | `sampling_rate` | integer | Yes | ```json { "type": "audio_url", "audio_url": { "url": "https://bakery.example.com/audio/kneading-tutorial.mp3" }, "mime_type": "audio/mpeg", "sampling_rate": 44100, "generated_metadata": { "type": "audio", "file_type": "audio/mpeg", "file_size": 5242880, "total_duration_seconds": 180.5, "sample_rate": 44100, "channels": 2, "audio_format": 1 } } ``` ```json { "type": "object", "required": ["audio_url", "sampling_rate"], "properties": { "type": { "const": "audio_url", "default": "audio_url" }, "audio_url": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "description": "HTTP URL or Data URI" } } }, "mime_type": { "type": "string", "default": "audio/mpeg" }, "sampling_rate": { "type": "integer" }, "chunk_index": { "type": ["integer", "null"], "default": null }, "generated_metadata": { "type": ["object", "null"], "default": null, "properties": { "type": { "const": "audio" }, "file_type": { "type": "string", "default": "audio/mpeg" }, "file_size": { "type": ["integer", "null"] }, "total_duration_seconds": { "type": ["number", "null"] }, "sample_rate": { "type": ["integer", "null"] }, "channels": { "type": ["integer", "null"] }, "audio_format": { "type": ["integer", "null"] } }, "required": ["type"], "additionalProperties": true } } } ``` ### Video Chunks [#video-chunks] | Property | Type | Required | | --------------- | ------ | -------------------------- | | `video_url.url` | string | Yes (HTTP URL or data URI) | ```json { "type": "video_url", "video_url": { "url": "https://bakery.example.com/video/shaping-boule.mp4" }, "mime_type": "video/mp4", "generated_metadata": { "type": "video", "file_type": "video/mp4", "file_size": 10485760, "total_duration_seconds": 120.0, "fps": 30.0, "width": 1920, "height": 1080, "frame_count": 3600, "has_audio_stream": true } } ``` ```json { "type": "object", "required": ["video_url"], "properties": { "type": { "const": "video_url", "default": "video_url" }, "video_url": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "description": "HTTP URL or Data URI" } } }, "mime_type": { "type": "string", "default": "video/mp4" }, "chunk_index": { "type": ["integer", "null"], "default": null }, "generated_metadata": { "type": ["object", "null"], "default": null, "properties": { "type": { "const": "video" }, "file_type": { "type": "string", "default": "video/mp4" }, "file_size": { "type": ["integer", "null"] }, "total_duration_seconds": { "type": ["number", "null"] }, "fps": { "type": ["number", "null"] }, "width": { "type": ["integer", "null"] }, "height": { "type": ["integer", "null"] }, "frame_count": { "type": ["integer", "null"] }, "has_audio_stream": { "type": "boolean", "default": false } }, "required": ["type"], "additionalProperties": true } } } ``` ## Chunk Metadata [#chunk-metadata] Each chunk can optionally include `generated_metadata` — a typed structure that follows a fixed format discriminated by a `type` field. When files are processed by the system, this metadata is automatically generated. When using mxjson, you can provide it yourself to match the same structure. Only the `type` field is required within the metadata object; all other fields are optional. You can also add custom fields beyond the typed ones — any additional key-value pairs are preserved alongside the standard fields. See [Generated Metadata](/docs/stores/store-files/generated-metadata) for the full reference of all metadata types and their fields. ```json { "type": "text", "text": "Autolyse is a rest period after mixing flour and water.", "mime_type": "text/plain", "generated_metadata": { "type": "text", "file_type": "text/plain", "language": "en", "word_count": 10, "file_size": 2048 } } ``` The `generated_metadata` type is determined by the `type` discriminator field. Only `type` is required; all other fields are optional: | Type | Optional Fields | | ---------- | --------------------------------------------------------------------------------------------------------------- | | `text` | `file_type`, `language`, `word_count`, `file_size` | | `markdown` | `file_type`, `language`, `word_count`, `file_size`, `chunk_headings`, `heading_context` | | `pdf` | `file_type`, `total_pages`, `total_size` | | `code` | `file_type`, `language`, `word_count`, `file_size` | | `audio` | `file_type`, `file_size`, `total_duration_seconds`, `sample_rate`, `channels`, `audio_format` | | `video` | `file_type`, `file_size`, `total_duration_seconds`, `fps`, `width`, `height`, `frame_count`, `has_audio_stream` | | `image` | `file_type`, `file_size`, `width`, `height` | File-level metadata (set during upload) applies to all chunks and participates in [contextualization](/docs/stores/stores#store-configuration) if enabled on the Store. ## Complete Example [#complete-example] ### JSON Format (.mxjson) [#json-format-mxjson] ```json [ { "type": "text", "text": "Baguette Shaping Guide", "mime_type": "text/plain", "chunk_index": 0, "generated_metadata": { "type": "text", "file_type": "text/plain", "language": "en", "word_count": 3, "file_size": 1024 } }, { "type": "text", "text": "Pre-shape the dough into a loose rectangle. Let it rest for 15-20 minutes to relax the gluten before final shaping.", "mime_type": "text/plain", "chunk_index": 1, "generated_metadata": { "type": "text", "file_type": "text/plain", "language": "en", "word_count": 20, "file_size": 1024 } }, { "type": "image_url", "image_url": {"url": "https://bakery.example.com/images/baguette-preshape.jpg"}, "mime_type": "image/jpeg", "chunk_index": 2, "generated_metadata": { "type": "image", "file_type": "image/jpeg", "file_size": 153600, "width": 800, "height": 600 } } ] ``` ### JSON Lines Format (.mxjsonl) [#json-lines-format-mxjsonl] ```jsonl {"type": "text", "text": "Baguette Shaping Guide", "mime_type": "text/plain", "chunk_index": 0, "generated_metadata": {"type": "text", "file_type": "text/plain", "language": "en", "word_count": 3, "file_size": 1024}} {"type": "text", "text": "Pre-shape the dough into a loose rectangle.", "mime_type": "text/plain", "chunk_index": 1, "generated_metadata": {"type": "text", "file_type": "text/plain", "language": "en", "word_count": 8, "file_size": 1024}} {"type": "image_url", "image_url": {"url": "https://bakery.example.com/images/baguette-preshape.jpg"}, "mime_type": "image/jpeg", "chunk_index": 2, "generated_metadata": {"type": "image", "file_type": "image/jpeg", "file_size": 153600, "width": 800, "height": 600}} ``` ## Schema Endpoint [#schema-endpoint] Retrieve the JSON Schema programmatically: ```bash curl https://api.mixedbread.com/v1/schemas/mxjson ``` ## Use Cases [#use-cases] **Custom chunking**: When your domain requires specific chunk boundaries (paragraphs, sections, recipe steps). **Pre-processed pipelines**: When existing ETL pipelines produce chunked content. **Multimodal collections**: When combining text, images, audio, and video from different sources. **Metadata preservation**: When chunks carry structured metadata from source systems. **Migration**: When importing pre-chunked data from other vector databases. ## Validation Errors [#validation-errors] | Error | Cause | | --------------------------------- | -------------------------------------------------------------- | | `type` is required | Missing `type` field | | `text` must be 1-65536 characters | Text empty or exceeds limit | | Invalid URL format | Malformed URL or data URI | | Unknown chunk type | Type not one of: `text`, `image_url`, `audio_url`, `video_url` | # Create Stores (/docs/stores/stores) Stores are AI-powered search indexes that organize your files for semantic search. Choose the right configuration for your use case, from temporary development environments to public knowledge bases. ## Basic Creation [#basic-creation] Create a new Store with default settings: When you create a Store, you get a Store object with a unique ID (UUID). You can use either the ID or the name you provide as Store identifiers in all operations. For complete details on the Store object structure, see [Data Models](/docs/stores/data-models#store). ## Configuration Options [#configuration-options] ### Name [#name] Names and IDs are interchangeable identifiers for all operations. **Naming Rules:** * Can only contain lowercase letters, numbers, periods (`.`), and hyphens (`-`) * Must be unique within your organization * Can be updated at any time ### Expiration Policies [#expiration-policies] Set automatic cleanup policies to manage Store lifecycle based on activity: The `last_active_at` anchor resets the expiration timer whenever you add files, delete files, or perform searches. Stores never expire unless explicitly configured. ### Public Access [#public-access] Control read access to your Store: **Private** (default): Only your organization can access. You pay all costs. **Public**: Anyone with an API key can search. They pay for their own searches. ### File contextualization [#file-contextualization] Improve retrieval for long documents by adding global context to individual chunks. When enabled, Mixedbread automatically generates chunk-specific explanatory context from the original file and prepends it to each chunk before embedding. ### Metadata contextualization [#metadata-contextualization] Improve retrieval using metadata by including selected file metadata in each chunk before embedding. * `false` (default): Do not include file metadata * `true`: Include all file metadata (flattened) * An array of field names: Include only the selected fields (supports nested fields using dot notation) ## Configuration Guide [#configuration-guide] | Use Case | Name Pattern | Expiration | Public | Purpose | | --------------- | ----------------- | ---------- | ------ | ------------------------ | | Development | `dev-{feature}` | 7 days | No | Temporary testing | | Production Docs | `docs-v{version}` | Never | Yes | Public documentation | | Customer Data | `customer-{id}` | Never | No | Private customer content | | Demo/POC | `demo-{client}` | 30 days | No | Time-limited demos | ## Combined Configuration [#combined-configuration] Use multiple configuration options together for specific use cases: *** # Manage Stores (/docs/stores/stores/manage-stores) Once you've created Stores, you can manage them using these core operations. All operations work with either the Store ID or the unique name you assigned. ## Retrieve Store [#retrieve-store] Get details about a specific Store: This returns a complete Store object with all properties including file counts, status, and usage statistics. For details on all returned fields, see [Data Models](/docs/stores/data-models#store). ## Update Store [#update-store] Modify an existing Store's configuration: **Updatable Properties:** * **name**: Change the unique identifier (lowercase letters, numbers, periods, and hyphens only) * **description**: Update the description * **is\_public**: Change visibility (public/private) * **expires\_after**: Modify or remove expiration policy ## List Stores [#list-stores] Get all Stores in your organization. The list operation uses cursor-based pagination: **Pagination Details**: For complete information about cursor-based pagination including parameters, response format, and advanced usage patterns, see the [Pagination Reference](/api-reference/pagination). ## Delete Store [#delete-store] Permanently remove a Store and all its contents: **Important**: Deletion is permanent and cannot be undone. All files, embeddings, and metadata are permanently removed. # Public Stores (/docs/stores/stores/public-stores) Public stores are search indexes that can be searched by any Mixedbread user. They include stores maintained by Mixedbread as well as stores shared publicly by other organizations. When a store is public, users outside the owning organization can search it without being added to that organization. For cross-organization access, callers use the store's public name in `store_identifiers`. ## Public Names [#public-names] Every public store has a public name in the following format: ```txt {owner_org_slug}/{store_name} ``` For example, if the organization slug is `acme` and the store name is `music`, the public name is: ```txt acme/music ``` Use that public name when searching a public store from another organization: You can combine public stores with your own stores in a single search: Members of other organizations should use the public name, such as `acme/music`, when searching your public store. ## Billing and API Keys [#billing-and-api-keys] Billing for public store searches is tied to the API key that makes the request. If a user from another organization searches `acme/music` using their own API key, the search is billed to their account, not to `acme`. Making a store public does not cause the store owner to pay for searches initiated by external users. **Example:** If a user at another organization calls `stores.search(store_identifiers=["acme/music"], query="best ambient albums from the 1990s")` with their API key, that user is charged for the search. When sharing a public store with customers, partners, or other teams, provide: * The public name, for example `acme/music` * A sample search request using `store_identifiers` * Clear guidance that searches are billed to the caller's API key ## Mixedbread-Maintained Public Stores [#mixedbread-maintained-public-stores] Mixedbread maintains public stores that provide access to common data sources. These stores are identified by the `mixedbread/` prefix. ### mixedbread/web [#mixedbreadweb] A web search store that provides access to the latest information from across the internet. Use it to augment your AI applications with up-to-date web knowledge. **Billing:** `mixedbread/web` is a special store. Each search query is billed as a **search with rerank query**. See [pricing](https://www.mixedbread.com/pricing) for details. **Use cases:** * Real-time information retrieval * Fact-checking and verification * Research augmentation * Grounding AI responses with current web data # Error Handling (/api-reference/error-handling) ## Common Status Codes [#common-status-codes] Understanding the status codes returned by the API is the first step in handling responses correctly. Here are the most common codes you might encounter: | Code | Meaning | Description | | :--- | :-------------------- | :------------------------------------------------------------------- | | 200 | OK | Request successful. The response contains the requested data. | | 201 | Created | Resource successfully created. Common for POST requests. | | 400 | Bad Request | Malformed request or missing required parameters. | | 401 | Unauthorized | Invalid, expired, or missing API key. | | 402 | Payment Required | Insufficient balance. Top up your account to continue. | | 403 | Forbidden | Valid credentials but insufficient permissions for this resource. | | 404 | Not Found | The requested resource doesn't exist. | | 409 | Conflict | Operation conflicts with current resource state. | | 422 | Unprocessable Entity | Request format is correct but cannot be processed. | | 429 | Rate Limit Exceeded | Too many requests. Wait before retrying. | | 500 | Internal Server Error | Unexpected server error. Retry after a brief wait. | | 503 | Service Unavailable | Service temporarily down for maintenance or overloaded. Retry later. | ## Best Practices [#best-practices] Build reliable applications with these error handling patterns: 1. **Catch specific errors first** - Handle specialized error types before generic exceptions 2. **Check status codes early** - Validate response status before processing the body 3. **Implement smart retries** - Use exponential backoff for transient errors ## Code Examples [#code-examples] # Introduction (/api-reference) ## Overview [#overview] Welcome to the Mixedbread API Reference. This comprehensive guide provides detailed technical specifications for all our endpoints, including request/response schemas, code examples, and best practices. ### Base URL [#base-url] All API requests should be made to: ``` https://api.mixedbread.com/ ``` ### Creating Your API Key [#creating-your-api-key] 1. Log in to your [Mixedbread account](https://platform.mixedbread.com/platform?next=api-keys) 2. Create a new API key 3. Copy your key and save it to your `.env` file ### Authentication [#authentication] Include your API key in the `Authorization` header of all requests: ```bash curl -X POST https://api.mixedbread.com/v1/stores \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "name": "My Knowledge Base", }' ``` ### SDK Quick Starts [#sdk-quick-starts] For a seamless integration experience, use our official SDKs: ## Need Help? [#need-help] * Check our [documentation](/docs) for more information * Contact [support@mixedbread.com](mailto:support@mixedbread.com) for assistance # Pagination (/api-reference/pagination) ## Overview [#overview] Mixedbread API uses cursor-based pagination for endpoints that return large result sets. This approach provides consistent performance regardless of dataset size and ensures reliable pagination even when data is being modified. ## Supported Endpoints [#supported-endpoints] Cursor-based pagination is used for: * **[List Stores](/api-reference/endpoints/stores/manage/list-stores)** * **[List Files](/api-reference/endpoints/files/list-files)** ## Pagination Parameters [#pagination-parameters] ### Request Parameters [#request-parameters] Include these query parameters in your requests: | Parameter | Type | Description | Default | | --------- | ------- | -------------------------------------------------------- | ------- | | `before` | string | Cursor for pagination. Returns items before this cursor. | - | | `after` | string | Cursor for pagination. Returns items after this cursor. | - | | `limit` | integer | Maximum number of items to return (1-100). | 20 | **Important Notes:** * Use either `before` OR `after`, not both * Cursors are opaque strings - don't parse or modify them * Always include `limit` to control result size ### Response Format [#response-format] All paginated responses include: ```json { "data": [...], "pagination": { "first_cursor": "eyJpZCI6InZzXzEyMyJ9", "last_cursor": "eyJpZCI6InZzXzQ1NiJ9", "has_more": true } } ``` | Field | Type | Description | | -------------- | ------- | ------------------------------------------------- | | `data` | array | The actual results for the current page | | `first_cursor` | string | Cursor pointing to the first item in current page | | `last_cursor` | string | Cursor pointing to the last item in current page | | `has_more` | boolean | Whether more results are available | ## Navigation Patterns [#navigation-patterns] ### Forward Pagination [#forward-pagination] Start with no cursor to get the first page: ```bash GET /v1/stores?limit=10 ``` Continue with `last_cursor` from the previous response: ```bash GET /v1/stores?after=eyJpZCI6InZzXzQ1NiJ9&limit=10 ``` ### Backward Pagination [#backward-pagination] Use `first_cursor` with `before` parameter: ```bash GET /v1/stores?before=eyJpZCI6InZzXzEyMyJ9&limit=10 ``` # Rate Limiting (/api-reference/rate-limits) ## Overview [#overview] Rate limits are applied per operation type, with each having its own limit and burst capacity. Exceeding these limits will result in a `429 Too Many Requests` response. If you consistently need higher limits, please [contact us](/contact). ## Rate Limits by Operation Type [#rate-limits-by-operation-type] We apply different rate limits based on the type of operation you're performing: | Operation Type | Limit | Burst Capacity | Window | | -------------- | ----- | -------------- | -------- | | **Read** | 1,200 | 1,000 | 1 minute | | **List** | 600 | 200 | 1 minute | | **Write** | 360 | 120 | 1 minute | | **Update** | 480 | 160 | 1 minute | | **Delete** | 240 | 80 | 1 minute | ## Handling Rate Limits [#handling-rate-limits] When you hit a rate limit: 1. You'll receive a `429 Too Many Requests` response 2. The response will include a `Retry-After` header 3. Wait for the specified time before retrying Example error response: ```json { "type": "too_many_requests_error", "url": "https://www.mixedbread.com/api-reference", "message": "Rate limit exceeded. Please try again later.", "details": { "retry_after": 60, "limit": "1200", "remaining": "0", "reset": "1730000000" } } ``` # Vercel (/api-reference/integrations/vercel) The Mixedbread Vercel integration makes it easy to add our powerful Search API to your Vercel projects. It allows you to create organizations and Stores directly from Vercel and connect them with your projects. You can start with a [template](https://vercel.com/templates/next.js/mixedbread-starter), connect the environment variables and manage everything from the Vercel dashboard. ## How It Works [#how-it-works] The Mixedbread Vercel integration provides a streamlined workflow for working with our Search API: * **Team Installation** → Creates a Mixedbread organization linked to your Vercel account * **Install Products** → Each product creates a Store in your organization * **Connect Projects** → Link Stores to Vercel projects with automatic environment variable injection * **Unified Billing** → All usage is billed through your Vercel account ## Getting Started [#getting-started] ### Install the Integration [#install-the-integration] 1. Navigate to the [Mixedbread Integration](https://vercel.com/marketplace/mixedbread) 2. Click **Install** and choose your team or personal account scope 3. Accept the permissions to allow Mixedbread to manage resources The installation flow includes the creation of your Mixedbread organization and your first Store. You are granted the **owner** role with full access to manage Stores and team members. ## Create a Store [#create-a-store] ### Install Your First Product [#install-your-first-product] 1. From the Mixedbread integration page in Vercel, click **Install** to add a new product 2. Configure your Store: * **Name** - A descriptive identifier for your Store * **Description** - Optional context about the Store's purpose (optional) * **Public Read** - Enable public read access without authentication (optional) 3. Confirm to provision the Store The product creator is granted the **admin** role in the Mixedbread organization if they are not the **owner**. The Store is immediately available for connecting to projects. ### Add More Stores [#add-more-stores] You can create multiple Stores from the Vercel integration page to organize different use cases, environments, or applications. Each Store can be independently configured and connected to different projects. Stores for Vercel-managed organizations can only be created through the Vercel integration page, not from the Mixedbread dashboard. ## Connect to Projects [#connect-to-projects] ### Link Stores to Vercel Projects [#link-stores-to-vercel-projects] 1. In the Mixedbread integration page, click **Connect Project** 2. Select one or more Vercel projects to link 3. Environment variables are automatically added to your selected projects: * `MXBAI_API_KEY` - Authentication key for API requests * `MXBAI_STORE_ID` - The unique identifier for your Store 4. Redeploy your projects to access the new environment variables ### Multi-Project Connections [#multi-project-connections] A single Store can be connected to multiple Vercel projects, making it ideal for: * Sharing data between staging and production environments * Connecting multiple microservices to the same knowledge base * Providing consistent search across different applications Each connected project receives the same environment variables for seamless access. ## Managing the Integration [#managing-the-integration] ### Team Permissions [#team-permissions] Permissions are automatically synchronized between Vercel and Mixedbread: * **Integration Creator** → Mixedbread Organization Owner * **Resource Creators** → Mixedbread Organization Admins Team members can access and manage Stores based on their assigned roles in the Mixedbread organization. ### Monitor Usage and Billing [#monitor-usage-and-billing] * **Billing**: All usage is billed through your Vercel account * **Usage Metrics**: View detailed usage statistics and analytics in both [Vercel dashboard](https://vercel.com/dashboard) and [Mixedbread dashboard](https://www.platform.mixedbread.com/platform?next=settings/billing/invoices) * **Cost Tracking**: Monitor consumption across all stores and projects in the Vercel billing dashboard ## Uninstalling the Integration [#uninstalling-the-integration] When you uninstall the Mixedbread integration from Vercel: * The associated Mixedbread organization is deleted * All Stores in the organization become inaccessible * Connected applications will fail API requests **Before uninstalling**, ensure no production applications depend on the Stores and remove environment variables from your projects if necessary. # Python (/api-reference/sdks/python) ## Introduction [#introduction] The Mixedbread Python SDK provides a convenient interface for accessing our API with built-in error handling, retries, and type safety. ## Installation [#installation] ```bash title="Installation" pip install mixedbread ``` ## Quick Start [#quick-start] Get started with a simple example: ```python title="Basic Usage" from mixedbread import Mixedbread mxbai = Mixedbread(api_key="YOUR_API_KEY") store = mxbai.stores.create( name='my-knowledge-base', description='Product documentation and guides' ) print(f"Created store: {store.id}") ``` ## Configuration [#configuration] The `Mixedbread` constructor accepts the following parameters: ```python class Mixedbread: def __init__( self, api_key: str, max_retries: int = 3, timeout: float = 30.0, base_url: str = "https://api.mixedbread.com" ): # ... ``` * `api_key`: Your Mixedbread API key (required) * `max_retries`: Maximum number of retries for failed requests (default: 3) * `timeout`: Request timeout in seconds (default: 30.0) * `base_url`: Custom base URL for API requests (default: [https://api.mixedbread.com](https://api.mixedbread.com)) ## Async Support [#async-support] For async applications, use the async client: ```python title="Async client" from mixedbread import AsyncMixedbread async_mxbai = AsyncMixedbread(api_key="YOUR_API_KEY") ``` ## Error Handling [#error-handling] Use try/except blocks to handle errors: ```python from mixedbread.exceptions import MixedbreadError, RateLimitError try: results = mxbai.stores.search( query="How does authentication work?", store_identifiers=["your-store-id"], top_k=5, search_options={ 'return_metadata': True, 'rerank': True } ) for chunk in results.data: print(chunk) except RateLimitError as e: print(f"Rate limit exceeded. Retry after {e.retry_after} seconds") except MixedbreadError as e: print(f"API Error: {e}") print(f"Status Code: {e.status_code}") except Exception as e: print(f"Unexpected error: {e}") ``` ## Environment Setup [#environment-setup] ### Using Environment Variables [#using-environment-variables] ```bash title="Environment Configuration" export MXBAI_API_KEY="your_api_key_here" export MXBAI_BASE_URL="https://api.mixedbread.com" ``` ```python title="Environment-based Initialization" from mixedbread import Mixedbread mxbai = Mixedbread( api_key=os.getenv("MXBAI_API_KEY"), base_url=os.getenv("MXBAI_BASE_URL") ) ``` # TypeScript (/api-reference/sdks/typescript) ## Introduction [#introduction] The Mixedbread TypeScript SDK provides a convenient interface for accessing our API with built-in error handling, retries, and type safety. ## Installation [#installation] ```bash title="Installation" npm install @mixedbread/sdk ``` ```bash title="Installation" pnpm add @mixedbread/sdk ``` ```bash title="Installation" yarn add @mixedbread/sdk ``` ```bash title="Installation" bun add @mixedbread/sdk ``` ## Quick Start [#quick-start] Get started with a simple example: ```typescript title="Basic Usage" import { Mixedbread } from "@mixedbread/sdk"; const mxbai = new Mixedbread({ apiKey: process.env.MXBAI_API_KEY!, }); const store = await mxbai.stores.create({ name: 'my-knowledge-base', description: 'Product documentation and guides' }); console.log(`Created store: ${store.id}`); ``` ## Configuration [#configuration] The `Mixedbread` constructor accepts the following options: ```typescript interface MixedbreadOptions { apiKey: string; maxRetries?: number; timeout?: number; baseURL?: string; } ``` * `apiKey`: Your Mixedbread API key (required) * `maxRetries`: Maximum number of retries for failed requests (default: 3) * `timeout`: Request timeout in milliseconds (default: 30000) * `baseURL`: Custom base URL for API requests (default: [https://api.mixedbread.com](https://api.mixedbread.com)) ## Error Handling [#error-handling] Use try/catch blocks to handle errors: ```typescript import { MixedbreadError, RateLimitError } from "@mixedbread/sdk"; try { const results = await mxbai.stores.search({ query: "How does authentication work?", store_identifiers: ["your-store-id"], top_k: 5, search_options: { return_metadata: true, rerank: true } }); for (const chunk of results.data) { console.log(chunk); } } catch (err) { if (err instanceof RateLimitError) { console.error(`Rate limit exceeded. Retry after ${err.retryAfter} seconds`); } else if (err instanceof MixedbreadError) { console.error(`API Error: ${err.message}`); console.error(`Status Code: ${err.statusCode}`); } else { console.error(`Unexpected error: ${err}`); } } ``` ## Environment Setup [#environment-setup] ### Using Environment Variables [#using-environment-variables] ```bash title="Environment Configuration" export MXBAI_API_KEY="your_api_key_here" export MXBAI_BASE_URL="https://api.mixedbread.com" ``` ```typescript title="Environment-based Configuration" import { Mixedbread } from "@mixedbread/sdk"; if (!process.env.MXBAI_API_KEY) { throw new Error("MXBAI_API_KEY environment variable is required"); } if (!process.env.MXBAI_BASE_URL) { throw new Error("MXBAI_BASE_URL environment variable is required"); } const mxbai = new Mixedbread({ apiKey: process.env.MXBAI_API_KEY, baseURL: process.env.MXBAI_BASE_URL, }); ``` # Create a Chat Completion (/api-reference/endpoints/chat/create-chat-completion) ### Authorization [#authorization] ### Request Body [#request-body] ### Response Body [#response-body] # Abort Multipart Upload (/api-reference/endpoints/files/abort-multipart-upload) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Response Body [#response-body] # Complete Multipart Upload (/api-reference/endpoints/files/complete-multipart-upload) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Request Body [#request-body] ### Response Body [#response-body] # Create Multipart Upload (/api-reference/endpoints/files/create-multipart-upload) ### Authorization [#authorization] ### Request Body [#request-body] ### Response Body [#response-body] # Delete File (/api-reference/endpoints/files/delete-file) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Response Body [#response-body] # Download File (/api-reference/endpoints/files/download-file) ### Authorization [#authorization] ### Path Parameters [#path-parameters] # Get File (/api-reference/endpoints/files/get-file) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Response Body [#response-body] # Get Multipart Upload (/api-reference/endpoints/files/get-multipart-upload) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Response Body [#response-body] # List Files (/api-reference/endpoints/files/list-files) ### Authorization [#authorization] ### Query Parameters [#query-parameters] ### Response Body [#response-body] # List Multipart Uploads (/api-reference/endpoints/files/list-multipart-uploads) ### Authorization [#authorization] ### Response Body [#response-body] # Update File (/api-reference/endpoints/files/update-file) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Request Body [#request-body] ### Response Body [#response-body] # Upload File (/api-reference/endpoints/files/upload-file) ### Authorization [#authorization] ### Request Body [#request-body] ### Response Body [#response-body] # Add File to Store (/api-reference/endpoints/stores/files/add-store-file) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Request Body [#request-body] ### Response Body [#response-body] {/* Common Properties - shared by all chunk types */} {/* Type-specific Properties */} # Delete Store File (/api-reference/endpoints/stores/files/delete-store-file) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Response Body [#response-body] # Get Store File (/api-reference/endpoints/stores/files/get-store-file) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Query Parameters [#query-parameters] ### Response Body [#response-body] {/* Common Properties - shared by all chunk types */} {/* Type-specific Properties */} # List Store Files (/api-reference/endpoints/stores/files/list-store-files) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Request Body [#request-body] ### Response Body [#response-body] {/* Common Properties - shared by all chunk types */} {/* Type-specific Properties */} # Update Store File (/api-reference/endpoints/stores/files/update-store-file) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Request Body [#request-body] ### Response Body [#response-body] {/* Common Properties - shared by all chunk types */} {/* Type-specific Properties */} # List Store Events (/api-reference/endpoints/stores/events/list-store-events) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Query Parameters [#query-parameters] ### Response Body [#response-body] # Create Store (/api-reference/endpoints/stores/manage/create-store) ### Authorization [#authorization] ### Request Body [#request-body] ### Response Body [#response-body] # Delete Store (/api-reference/endpoints/stores/manage/delete-store) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Response Body [#response-body] # Get Store (/api-reference/endpoints/stores/manage/get-store) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Response Body [#response-body] # List Stores (/api-reference/endpoints/stores/manage/list-stores) ### Authorization [#authorization] ### Query Parameters [#query-parameters] ### Response Body [#response-body] # Update Store (/api-reference/endpoints/stores/manage/update-store) ### Authorization [#authorization] ### Path Parameters [#path-parameters] ### Request Body [#request-body] ### Response Body [#response-body] # Get Metadata Facets (/api-reference/endpoints/stores/search/get-metadata-facets) ### Authorization [#authorization] ### Request Body [#request-body] ### Response Body [#response-body] # Grep Store Chunks (/api-reference/endpoints/stores/search/grep-store-chunks) ### Authorization [#authorization] ### Request Body [#request-body] ### Response Body [#response-body] {/* Common Properties - shared by all chunk types */} {/* Type-specific Properties */} # List Store Chunks (/api-reference/endpoints/stores/search/list-store-chunks) ### Authorization [#authorization] ### Request Body [#request-body] ### Response Body [#response-body] {/* Common Properties - shared by all chunk types */} {/* Type-specific Properties */} # Question Answering (/api-reference/endpoints/stores/search/question-answering) ### Authorization [#authorization] ### Request Body [#request-body] ### Response Body [#response-body] {/* Common Properties - shared by all chunk types */} {/* Type-specific Properties */} # Search Chunks (/api-reference/endpoints/stores/search/search-chunks) ### Authorization [#authorization] ### Request Body [#request-body] ### Response Body [#response-body] {/* Common Properties - shared by all chunk types */} {/* Type-specific Properties */} # Configuration (/cli/configuration) The mxbai CLI provides flexible configuration management to set defaults, store credentials, and create aliases for common operations. Configuration is stored in platform-specific locations and can be managed using the `mxbai config` commands. ## Configuration File Location [#configuration-file-location] ``` ~/Library/Application Support/mixedbread/config.json ``` ``` ~/.config/mixedbread/config.json or $XDG_CONFIG_HOME/mixedbread/config.json ``` ``` %APPDATA%\mixedbread\config.json ``` ### Custom location [#custom-location] Override the default location by setting the `MXBAI_CONFIG_PATH` environment variable: ```bash export MXBAI_CONFIG_PATH=/path/to/your/config.json ``` ## Configuration Precedence [#configuration-precedence] When using the CLI, configuration values are resolved in the following order (highest to lowest priority): 1. **Command-line flags** - Direct CLI options (e.g., `--strategy high_quality`) 2. **Environment variables** - System environment settings (e.g., `MXBAI_API_KEY`, `MXBAI_BASE_URL`, `MXBAI_CONFIG_PATH`, `MXBAI_DEBUG`) 3. **Manifest entry** - File-specific settings in manifest files (only applies to manifest uploads) 4. **Manifest defaults** - Default settings in manifest files (only applies to manifest uploads) 5. **Config file** - User configuration file settings 6. **Built-in defaults** - CLI default values This allows flexible configuration while maintaining predictable behavior. For example: * If you set `defaults.upload.strategy = "high_quality"` in your config file, but use `--strategy fast` on the command line, the command-line flag takes precedence. * When using manifest files, individual file settings override the manifest defaults, which in turn override your config file settings. ## Add API Key [#add-api-key] ### Command [#command] ```bash mxbai config keys add [name] ``` ### Options [#options] * `` - The API key to add (required, must start with `mxb_`) * `[name]` - Optional name for the API key (if not provided, you will be prompted) ### Examples [#examples] ```bash # Add API key with a name mxbai config keys add mxb_xxxxx work # Add API key without name (will prompt for name) mxbai config keys add mxb_xxxxx ``` ## List API Keys [#list-api-keys] ### Command [#command-1] ```bash mxbai config keys list ``` ### Examples [#examples-1] ```bash # List all stored API keys mxbai config keys list # Output: # work # * personal (default) ``` ## Remove API Key [#remove-api-key] ### Command [#command-2] ```bash mxbai config keys remove ``` ### Options [#options-1] * `` - The name of the API key to remove (required) * `--yes`, `-y` - Skip confirmation prompt ### Examples [#examples-2] ```bash # Remove an API key by name mxbai config keys remove personal # Remove an API key by name without confirmation mxbai config keys remove personal --yes ``` ## Set Default API Key [#set-default-api-key] ### Command [#command-3] ```bash mxbai config keys set-default ``` ### Options [#options-2] * `` - The name of the API key to set as default (required) ### Examples [#examples-3] ```bash # Set default API key mxbai config keys set-default work # Use a specific saved API key for a command (overrides default) mxbai store upload "My Docs" "*.md" --saved-key personal mxbai store search "Knowledge Base" "query" --saved-key work # Or use an actual API key directly mxbai store upload "My Docs" "*.md" --api-key mxb_xxxxx ``` ## Set Configuration Values [#set-configuration-values] ### Command [#command-4] ```bash mxbai config set ``` ### Examples [#examples-4] ```bash # Set upload defaults mxbai config set defaults.upload.strategy high_quality mxbai config set defaults.upload.parallel 10 # Deprecated - contextualization is now configured at the store level # mxbai config set defaults.upload.contextualization true # Set search defaults mxbai config set defaults.search.top_k 20 mxbai config set defaults.search.rerank true # Create store aliases mxbai config set aliases.docs "My Documentation" mxbai config set aliases.kb "Knowledge Base" ``` ## Get Configuration Values [#get-configuration-values] ### Command [#command-5] ```bash mxbai config get [key] ``` ### Examples [#examples-5] ```bash # View all configuration mxbai config get # View specific configuration section mxbai config get defaults.upload # View specific setting mxbai config get api_key ``` ## Configuration Options [#configuration-options] ### API Authentication [#api-authentication] The CLI supports multiple API keys for different organizations or environments. Use the `keys` subcommand to manage them: ```bash mxbai config keys add mxb_xxxxx ``` * Required format: Must start with `mxb_` * Security: Stored locally in your user directory * Multi-key support: Add multiple keys with names for easy switching ### Upload Defaults [#upload-defaults] Configure default options for file uploads: #### Processing Strategy [#processing-strategy] Choose between fast processing for speed or high quality processing for better search results. * Config key: `defaults.upload.strategy` * Default: `fast` * Valid values: `fast`, `high_quality` ```bash mxbai config set defaults.upload.strategy high_quality ``` #### Contextualization [#contextualization] **Deprecated**: Contextualization is now configured at the store level using `mxbai store create --contextualization`, not per-upload. This setting is ignored by the CLI and will be removed in a future version. Include metadata in chunk embeddings to improve search relevance. * Config key: `defaults.upload.contextualization` * Default: `false` * Valid values: `true`, `false` ```bash # Deprecated - this setting is now ignored mxbai config set defaults.upload.contextualization true ``` #### Parallel Uploads [#parallel-uploads] Control how many files are uploaded simultaneously to optimize for your network and system resources. * Config key: `defaults.upload.parallel` * Default: `100` * Valid range: `1` to `200` ```bash mxbai config set defaults.upload.parallel 10 ``` ### Search Defaults [#search-defaults] Configure default search behavior: #### Number of Results [#number-of-results] Set how many search results to return by default when searching your stores. * Config key: `defaults.search.top_k` * Default: `10` * Valid range: `1` to `100` ```bash mxbai config set defaults.search.top_k 20 ``` #### Result Reranking [#result-reranking] Enable AI-powered reranking to reorder search results based on relevance, improving the quality of top results. * Config key: `defaults.search.rerank` * Default: `false` * Valid values: `true`, `false` ```bash mxbai config set defaults.search.rerank true ``` ### Store Aliases [#store-aliases] Create shortcuts for frequently used stores: ```bash # Create aliases for long store names mxbai config set aliases.docs "My Documentation Store" mxbai config set aliases.kb "Company Knowledge Base" mxbai config set aliases.proj "Project Files" ``` Then use aliases in commands: ```bash # Instead of: mxbai store upload "My Documentation Store" "*.md" mxbai store upload docs "*.md" # Instead of: mxbai store search "Company Knowledge Base" "how to get started" mxbai store search kb "how to get started" ``` ## Default Configuration [#default-configuration] When no configuration is set, the CLI uses these default values: ```json { "api_keys": {}, "defaults": { "upload": { "strategy": "fast", "contextualization": false, // Deprecated - now configured at store level "parallel": 100 }, "search": { "top_k": 10, "rerank": false }, "api_key": undefined }, "aliases": {} } ``` ## Configuration File Structure [#configuration-file-structure] After customization, your configuration file might look like: ```json { "api_keys": { "work": "mxb_xxxxx", "personal": "mxb_xxxxx" }, "defaults": { "upload": { "strategy": "high_quality", "contextualization": true, // Deprecated - now configured at store level "parallel": 10 }, "search": { "top_k": 20, "rerank": true }, "api_key": "work" }, "aliases": { "docs": "My Documentation Store", "kb": "Company Knowledge Base" } } ``` ## Common Configuration Examples [#common-configuration-examples] ### Development Setup [#development-setup] Optimize for speed during development: ```bash # Fast uploads for quick iterations mxbai config set defaults.upload.strategy fast mxbai config set defaults.upload.parallel 5 # More search results for exploration mxbai config set defaults.search.top_k 15 # Create development aliases mxbai config set aliases.dev "Development Docs" mxbai config set aliases.test "Test Data" ``` ### Production Setup [#production-setup] Optimize for quality and accuracy: ```bash # High quality processing for better results mxbai config set defaults.upload.strategy high_quality # Note: contextualization is now configured at the store level, not per-upload # mxbai config set defaults.upload.contextualization true # Balanced search configuration mxbai config set defaults.search.top_k 10 mxbai config set defaults.search.rerank true # Production aliases mxbai config set aliases.prod "Production Knowledge Base" mxbai config set aliases.docs "Official Documentation" ``` ### CI/CD Setup [#cicd-setup] Configure for automated environments: ```bash # Store API key (usually from environment variable) mxbai config keys add $MXBAI_API_KEY ci # Fast processing for CI pipelines mxbai config set defaults.upload.strategy fast mxbai config set defaults.upload.parallel 10 ``` ## Debugging [#debugging] Enable debug output to troubleshoot issues: ```bash # Via command flag mxbai store list --debug # Via environment variable export MXBAI_DEBUG=true mxbai store list # Debug shows: # - Configuration resolution # - Error stack traces ``` # File Management (/cli/files) Files serve as the foundation for all content processing workflows in Mixedbread. They provide secure upload, storage, and retrieval of documents with support for various file types including PDFs, images, and structured data. Manage files within your stores with version management, metadata support, and unique ID referencing. ## Upload Files [#upload-files] ### Command [#command] ```bash mxbai store upload [options] ``` ### Options [#options] * `--strategy fast|high_quality` - Processing strategy (default: `fast`) * `--contextualization` - **Deprecated**: Now configured at store level using `mxbai store create --contextualization`. This flag is ignored and will be removed in a future version. * `--metadata ` - JSON metadata for uploaded files * `--dry-run` - Preview what would be uploaded without uploading * `--parallel ` - Number of concurrent uploads (default: `100`, range: `1` - `200`) * `--unique` - Update existing files instead of creating duplicates * `--manifest ` - Upload using manifest file * `--multipart-threshold ` - File size threshold in MB to trigger multipart upload * `--multipart-part-size ` - Size of each part in MB for multipart upload * `--multipart-concurrency ` - Number of concurrent part uploads for multipart upload ### Manifest File Format [#manifest-file-format] The manifest file allows you to define complex upload configurations with different settings for different file patterns. Both JSON (`.json`) and YAML (`.yaml` or `.yml`) formats are supported. **JSON format:** ```json { "version": "1.0", "defaults": { "strategy": "fast", // "contextualization": false, // Deprecated - now configured at store level "metadata": { "project": "my-project" } }, "files": [ { "path": "docs/**/*.md", "metadata": { "category": "documentation" } }, { "path": "README.md", "strategy": "high_quality", // contextualization is deprecated - configure at store level instead "metadata": { "importance": "high" } } ] } ``` **YAML format:** ```yaml version: "1.0" defaults: strategy: fast # contextualization: false # Deprecated - now configured at store level metadata: project: my-project files: - path: "docs/**/*.md" metadata: category: documentation - path: README.md strategy: high_quality # contextualization is deprecated - configure at store level instead metadata: importance: high ``` **Manifest properties:** * `version` - Manifest format version (currently "1.0") * `defaults` - Default settings applied to all files * `strategy` - Default processing strategy * `contextualization` - *(Deprecated)* Include metadata in chunk embeddings to improve search relevance - now configured at store level * `metadata` - Default metadata for all files * `files` - Array of file upload configurations * `path` - Glob pattern for files to upload * `strategy` - Specific strategy for this pattern * `contextualization` - *(Deprecated)* Contextualization for this pattern - now configured at store level * `metadata` - Additional metadata for this pattern (merged with defaults) ### Examples [#examples] ```bash # Upload markdown files mxbai store upload "my-knowledge-base" "*.md" # Upload multiple file types mxbai store upload "my-knowledge-base" "*.md" "docs/**/*.pdf" # Upload with high quality processing mxbai store upload "my-knowledge-base" "*.pdf" --strategy high_quality # Deprecated: contextualization is now configured at the store level # mxbai store upload "my-knowledge-base" "*.md" --contextualization # Upload with metadata mxbai store upload "my-knowledge-base" "*.md" --metadata '{"category": "docs"}' # Dry run to preview upload mxbai store upload "my-knowledge-base" "*.md" --dry-run # Upload with manifest file (JSON or YAML) mxbai store upload "my-knowledge-base" --manifest upload-manifest.json mxbai store upload "my-knowledge-base" --manifest upload-manifest.yaml # Upload large files with multipart upload mxbai store upload "my-knowledge-base" "*.pdf" \ --multipart-threshold 50 \ --multipart-part-size 25 \ --multipart-concurrency 10 ``` ## Upload Summary Information [#upload-summary-information] The upload command displays strategy information in the summary after completion: ```bash ✓ 5 files uploaded successfully Strategy: fast Total size: 25.3 KB ``` For manifest uploads, configuration is shown beside each file: ```bash ✓ docs/api.md (15.2 KB) [fast] ✓ README.md (8.5 KB) [high_quality] ✓ guide.md (1.6 KB) [fast] ``` This allows you to see exactly which strategy was applied to each file, making it easy to verify that your manifest configuration is working as expected. ## List Files [#list-files] ### Command [#command-1] ```bash mxbai store files list [options] ``` **Alias:** `mxbai store files ls ` ### Options [#options-1] * `--status ` - Filter by status: pending, in\_progress, cancelled, completed, failed * `--limit ` - Limit number of results ### Examples [#examples-1] ```bash # List all files in store mxbai store files list "my-knowledge-base" # List using alias mxbai store files ls "my-knowledge-base" # List only completed files mxbai store files list "my-knowledge-base" --status completed # List with limit mxbai store files list "my-knowledge-base" --limit 50 # List failed files for troubleshooting mxbai store files list "my-knowledge-base" --status failed ``` ## Get File Details [#get-file-details] ### Command [#command-2] ```bash mxbai store files get

``` ### Options [#options-2] None ### Examples [#examples-2] ```bash # Get details of a specific file mxbai store files get "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479" # Get file details using store ID mxbai store files get "my-knowledge-base" "b2c3d4e5-f6a7-8901-bcde-f23456789012" ``` ## Delete File [#delete-file] ### Command [#command-3] ```bash mxbai store files delete

[options] ``` **Alias:** `mxbai store files rm

` ### Options [#options-3] * `--yes`, `-y` - Skip confirmation prompt ### Examples [#examples-3] ```bash # Delete file with confirmation mxbai store files delete "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479" # Delete file without confirmation mxbai store files delete "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479" --yes # Delete using alias mxbai store files rm "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479" --yes # Delete from store by ID mxbai store files delete "my-knowledge-base" "b2c3d4e5-f6a7-8901-bcde-f23456789012" --yes ``` # Introduction (/cli) ## Overview [#overview] The mxbai CLI is a comprehensive tool for managing stores, uploading documents, and performing AI-powered search and question-answering operations. Built on top of the Mixedbread SDK, it provides an efficient command-line interface for all core platform features. New to Mixedbread? Check out our [API documentation](/api-reference) to understand the underlying services that power the CLI. ## Key Features [#key-features] ## Quick Start [#quick-start] ### 1. Install the CLI [#1-install-the-cli] ```bash npm install -g @mixedbread/cli ``` ```bash yarn global add @mixedbread/cli ``` ```bash pnpm add -g @mixedbread/cli ``` ```bash bun add -g @mixedbread/cli ``` ### 2. Set your API key [#2-set-your-api-key] ```bash # Option 1: Environment variable export MXBAI_API_KEY=mxb_xxxxx # Option 2: Config file (persistent) mxbai config keys add mxb_xxxxx ``` ### 3. Install shell completion (optional but recommended) [#3-install-shell-completion-optional-but-recommended] ```bash mxbai completion install ``` ### 4. Create a store [#4-create-a-store] ```bash mxbai store create "my-knowledge-base" ``` ### 5. Upload files [#5-upload-files] ```bash # Basic upload mxbai store upload "my-knowledge-base" "*.md" "docs/**/*.pdf" # Upload with high-quality processing mxbai store upload "my-knowledge-base" "**/*.md" --strategy high_quality ``` ### 6. Search your content [#6-search-your-content] ```bash mxbai store search "my-knowledge-base" "how to get started" ``` ## Command Structure [#command-structure] The mxbai CLI is organized around store operations using the `store` subcommand: ### Configuration Management [#configuration-management] * `mxbai config set ` - Set configuration values * `mxbai config get [key]` - Get configuration values * `mxbai config keys add [name]` - Add a new API key * `mxbai config keys list` - List all API keys * `mxbai config keys remove ` - Remove an API key * `mxbai config keys set-default ` - Set the default API key ### Shell Completion [#shell-completion] * `mxbai completion install` - Install shell completion * `mxbai completion uninstall` - Uninstall shell completion * `mxbai completion refresh` - Refresh completion cache for store names ### Store Management [#store-management] * `mxbai store list` - List all stores * `mxbai store create ` - Create a new store * `mxbai store get ` - Get store details * `mxbai store update ` - Update store settings * `mxbai store delete ` - Delete a store ### File Operations [#file-operations] * `mxbai store upload ` - Upload files * `mxbai store files list ` - List files in store * `mxbai store files get

` - Get file details * `mxbai store files delete

` - Delete a file ### Search & Query [#search--query] * `mxbai store search ` - Search store * `mxbai store qa ` - Ask questions about content ### Intelligent Sync [#intelligent-sync] * `mxbai store sync ` - Intelligent sync with change detection ## Global Options [#global-options] All commands support these global options: * `--api-key ` - Actual API key for authentication * `--saved-key ` - Name of saved API key from config * `--base-url ` - Custom API base URL * `--format ` - Output format: `table`, `json`, or `csv` (default: `table`) * `--debug` - Enable debug output (equivalent to `MXBAI_DEBUG=true`) * `--help` - Show help information for commands ## Environment Variables [#environment-variables] The CLI supports the following environment variables: * `MXBAI_API_KEY` - API key for authentication (must start with `mxb_`) * `MXBAI_BASE_URL` - Custom API base URL * `MXBAI_DEBUG` - Enable debug output (set to `true` or `1`) * `MXBAI_CONFIG_PATH` - Override default config file location ## Authentication [#authentication] The CLI looks for your API key in this order: 1. `--api-key` or `--saved-key` command line flags 2. `MXBAI_API_KEY` environment variable 3. Default API key from config file (platform-specific location): * Linux/Unix: `~/.config/mixedbread/config.json` (or `$XDG_CONFIG_HOME/mixedbread/config.json`) * macOS: `~/Library/Application Support/mixedbread/config.json` * Windows: `%APPDATA%\mixedbread\config.json` * Custom: Set `MXBAI_CONFIG_PATH` environment variable to override ### Multi-Organization Support [#multi-organization-support] The CLI supports multiple API keys for different organizations or environments: ```bash # Add API keys with descriptive names mxbai config keys add mxb_xxxxx work mxbai config keys add mxb_xxxxx personal # Use a specific saved API key for a command mxbai store upload "My Docs" "*.md" --saved-key work mxbai store search "Knowledge Base" "query" --saved-key personal # Or use an actual API key directly mxbai store upload "My Docs" "*.md" --api-key mxb_xxxxx # The last added key becomes default automatically # Or explicitly set a default mxbai config keys set-default personal ``` ## Getting Help [#getting-help] Use the `--help` flag to get detailed information about any command: ```bash # General help mxbai --help # Help for store commands mxbai store --help # Help for specific commands mxbai store create --help mxbai store upload --help mxbai store search --help ``` # Installation & Setup (/cli/installation) ## Prerequisites [#prerequisites] Before installing the mxbai CLI, ensure you have: * **Node.js** version 20.0 or higher * A package manager * A Mixedbread API key ([get one here](https://platform.mixedbread.com/platform?next=/api-keys)) ## Installation Methods [#installation-methods] ### Global Installation (Recommended) [#global-installation-recommended] Install the CLI globally to use it from any directory: ```bash npm install -g @mixedbread/cli ``` ```bash yarn global add @mixedbread/cli ``` ```bash pnpm add -g @mixedbread/cli ``` ```bash bun add -g @mixedbread/cli ``` ### Local Installation [#local-installation] For project-specific installations: ```bash npm install --save-dev @mixedbread/cli ``` ```bash yarn add --dev @mixedbread/cli ``` ```bash pnpm add -D @mixedbread/cli ``` ```bash bun add -d @mixedbread/cli ``` When installed locally, use `npx mxbai` or add scripts to your `package.json`: ```json { "scripts": { "mxbai": "mxbai" } } ``` ## Verify Installation [#verify-installation] After installation, verify the CLI is working: ```bash mxbai --version ``` ## Upgrading the CLI [#upgrading-the-cli] ### Global Upgrade [#global-upgrade] To upgrade a globally installed CLI to the latest version: ```bash npm install -g @mixedbread/cli@latest ``` ```bash yarn global add @mixedbread/cli@latest ``` ```bash pnpm add -g @mixedbread/cli@latest ``` ```bash bun add -g @mixedbread/cli@latest ``` ### Local Upgrade [#local-upgrade] For project-specific installations: ```bash npm install --save-dev @mixedbread/cli@latest ``` ```bash yarn add --dev @mixedbread/cli@latest ``` ```bash pnpm add -D @mixedbread/cli@latest ``` ```bash bun add -d @mixedbread/cli@latest ``` ## Authentication [#authentication] To use the CLI, you need a Mixedbread API key. The CLI checks for authentication in this order: 1. **Command line flag**: `--api-key mxb_xxxxx` 2. **Environment variable**: `export MXBAI_API_KEY=mxb_xxxxx` 3. **Configuration file**: `mxbai config set api_key mxb_xxxxx` ### Quick Setup [#quick-setup] The easiest way to get started is with an environment variable: ```bash export MXBAI_API_KEY=mxb_xxxxx ``` For persistent configuration across sessions, use the config file: ```bash mxbai config set api_key mxb_xxxxx ``` Learn more about configuration options in the [Configuration Guide](/cli/configuration). ## Shell Completion [#shell-completion] The CLI supports intelligent tab completion for commands, subcommands, and **store names**. ### Installation [#installation] ```bash # Install completion (auto-detects your shell) mxbai completion install # Install completion for a specific shell mxbai completion install --shell bash mxbai completion install --shell zsh mxbai completion install --shell fish mxbai completion install --shell pwsh ``` **Supported shells:** bash, zsh, fish, pwsh (PowerShell) After installation, restart your shell or reload your shell configuration: * **bash**: `source ~/.bashrc` or restart terminal * **zsh**: `source ~/.zshrc` or restart terminal * **fish**: Completion is ready to use (fish auto-loads completions) * **pwsh**: `. $PROFILE` or restart terminal ### Dynamic Store Name Completion [#dynamic-store-name-completion] The CLI provides intelligent tab completion for store names in commands: ```bash # Tab completion shows your store names mxbai store get [TAB] # Shows: store1 store2 my-docs ... mxbai store delete [TAB] # Shows: store1 store2 my-docs ... mxbai store sync [TAB] # Shows: store1 store2 my-docs ... mxbai store upload [TAB] # Shows: store1 store2 my-docs ... # Also works with files subcommands mxbai store files list [TAB] # Shows: store1 store2 my-docs ... ``` **How it works:** * Store names are cached locally for instant completion (no API latency) * Cache updates automatically when you create, update, delete, or list stores * Supports multiple API keys - completions show stores for your current default key * Manual refresh available: `mxbai completion refresh` **Cache management:** * Caches up to 50 most recent store names per API key * Cache location follows your config directory: * Linux/Unix: `~/.config/mixedbread/completion-cache.json` * macOS: `~/Library/Application Support/mixedbread/completion-cache.json` * Windows: `%APPDATA%\mixedbread\completion-cache.json` ### Managing Completion [#managing-completion] ```bash # Remove completion mxbai completion uninstall # Refresh store name cache mxbai completion refresh ``` # Question Answering (/cli/qa) Get AI-powered answers to questions about your store content. The system searches through your documents, retrieves the most relevant chunks, and generates context-aware responses with source file metadata for transparency. Perfect for building Q\&A systems and knowledge bases from your document collections. ## Command [#command] ```bash mxbai store qa [options] ``` ## Options [#options] * `--top-k ` - Number of context chunks to use (default: `10`) * `--threshold ` - Minimum relevance score for context chunks * `--return-metadata` - Include source file metadata in the response **Note:** Default values for `--top-k` can be configured using `mxbai config`. See the [Configuration Guide](/cli/configuration#search-defaults) for details. ## Examples [#examples] ```bash # Ask a basic question mxbai store qa "my-knowledge-base" "How do I configure authentication?" # Ask for more results mxbai store qa "my-knowledge-base" "What are the deployment steps?" --top-k 15 # Ask with relevance threshold mxbai store qa "my-knowledge-base" "What is the API rate limit?" --threshold 0.8 # Ask and include metadata in results mxbai store qa "my-knowledge-base" "How to handle errors?" --return-metadata # Combine options mxbai store qa "my-knowledge-base" "Best practices for security" --top-k 20 --return-metadata ``` # Search (/cli/search) Perform semantic search that understands meaning rather than just keywords. Uses advanced multimodal embedding models to find relevant content based on context and intent with sub-second response times. Search across text chunks within stores using natural language queries like "comfortable running shoes" to find "cushioned athletic sneakers". ## Command [#command] ```bash mxbai store search [options] ``` ## Options [#options] * `--top-k ` - Number of results to return (default: `10`, range: `1` - `100`) * `--threshold ` - Minimum similarity score (range: `0.0` - `1.0`) * `--return-metadata` - Include file metadata in results * `--rerank` - Enable result reranking for better relevance (default: `false`) * `--file-search` - Search files instead of chunks **Note:** Default values for `--top-k` and `--rerank` can be configured using `mxbai config`. See the [Configuration Guide](/cli/configuration#search-defaults) for details. ## Examples [#examples] ```bash # Basic search mxbai store search "my-knowledge-base" "how to get started" # Search with more results mxbai store search "my-knowledge-base" "authentication" --top-k 20 # Search with similarity threshold mxbai store search "my-knowledge-base" "configuration" --threshold 0.8 # Search and include metadata in results mxbai store search "my-knowledge-base" "deployment" --return-metadata # Search and rerank results mxbai store search "my-knowledge-base" "best practices" --rerank # Search showing text chunks mxbai store search "my-knowledge-base" "error handling" --file-search # Combine multiple options mxbai store search "my-knowledge-base" "API usage" --top-k 15 --rerank --return-metadata ``` # Store Management (/cli/stores) Stores transform any data into AI-native search engines that understand meaning, not just keywords. They act as containers for your files, automatically generating embeddings and enabling advanced search capabilities. Use these commands to create, manage, and organize your stores. Learn more about stores in the [documentation](https://www.mixedbread.com/docs). ## List Stores [#list-stores] ### Command [#command] ```bash mxbai store list [options] ``` ### Options [#options] * `--filter ` - Filter by name pattern * `--limit ` - Limit number of results ### Examples [#examples] ```bash # List all stores mxbai store list # Filter stores by name mxbai store list --filter "docs" # Limit results mxbai store list --limit 5 ``` ## Create Store [#create-store] ### Command [#command-1] ```bash mxbai store create [options] ``` ### Arguments [#arguments] * `` - Name for the store (lowercase letters, numbers, periods, and hyphens only) ### Options [#options-1] * `--description ` - Description for the store * `--expires-after ` - Auto-delete after specified days * `--metadata ` - JSON metadata for the store * `--public [value]` - Make store publicly accessible (requestor pays for usage) * `--contextualization [fields]` - Include metadata in chunk embeddings to improve search relevance. Can be used as a flag to enable globally, or with comma-separated metadata field names for targeted contextualization (e.g., `--contextualization=title,author`). ### Examples [#examples-1] ```bash # Create a basic store mxbai store create my-knowledge-base # Create with description mxbai store create my-knowledge-base --description "Project documentation" # Create with expiration mxbai store create temp-store --expires-after 30 # Create with metadata mxbai store create project-store --metadata '{"project": "web-app", "team": "engineering"}' # Create a public store mxbai store create my-public-store --public # Create with contextualization enabled mxbai store create my-knowledge-base --contextualization # Create with contextualization using specific metadata fields mxbai store create my-knowledge-base --contextualization=title,author,date ``` ## Get Store Details [#get-store-details] ### Command [#command-2] ```bash mxbai store get ``` ### Options [#options-2] None ### Examples [#examples-2] ```bash # Get store by name mxbai store get "my-knowledge-base" # Get store by ID mxbai store get "my-knowledge-base" ``` ## Update Store [#update-store] ### Command [#command-3] ```bash mxbai store update [options] ``` ### Options [#options-3] * `--name ` - New name for the store (lowercase letters, numbers, periods, and hyphens only) * `--description ` - New description * `--expires-after ` - Update expiration * `--metadata ` - Update metadata * `--public [value]` - Make store publicly accessible (requestor pays for usage) ### Examples [#examples-3] ```bash # Update description mxbai store update my-knowledge-base --description "Updated description" # Rename store mxbai store update old-name --name new-name # Update metadata mxbai store update my-store --metadata '{"version": "2.0"}' # Make store public mxbai store update my-store --public # Make store private mxbai store update my-store --public=false ``` ## Delete Store [#delete-store] ### Command [#command-4] ```bash mxbai store delete [options] ``` **Alias:** `mxbai store rm ` ### Options [#options-4] * `--yes`, `-y` - Skip confirmation prompt ### Examples [#examples-4] ```bash # Delete with confirmation prompt mxbai store delete "my-knowledge-base" # Delete without confirmation mxbai store delete "my-knowledge-base" --yes # Delete using alias mxbai store rm "my-knowledge-base" --yes # Delete by ID mxbai store delete "my-knowledge-base" --yes ``` # Sync (/cli/sync) Intelligently sync files to your store with two methods of change detection: Git-based (fastest) and hash-based (most accurate). Only uploads files that have changed since the last sync, making it efficient for large document collections and perfect for CI/CD workflows. ## Command [#command] ```bash mxbai store sync [options] ``` ## Options [#options] * `--strategy ` - Processing strategy: `fast` or `high_quality` (default: `fast`) * `--contextualization` - **Deprecated**: Now configured at store level using `mxbai store create --contextualization`. This flag is ignored and will be removed in a future version. * `--from-git ` - Git reference for change detection (e.g., `HEAD~1`, `main`) * `--dry-run` - Preview changes without syncing * `--yes`, `-y` - Skip confirmation prompt * `--force`, `-f` - Force upload regardless of whether content has changed or not * `--metadata ` - JSON metadata to attach to synced files * `--parallel ` - Number of concurrent operations (default: `100`, range: `1` - `200`) ## Change Detection [#change-detection] The sync command provides two methods of change detection: 1. **Git-based** (fast): Uses `git diff` to detect changes since a specific commit 2. **Hash-based** (accurate): Compares file hashes with stored metadata ## Examples [#examples] ```bash # Sync with git-based detection mxbai store sync "my-knowledge-base" "docs/**" --from-git HEAD~1 # Sync with hash-based detection and custom parallel processing mxbai store sync "my-knowledge-base" "**/*.md" --parallel 10 # Sync with high-quality processing mxbai store sync "my-knowledge-base" "**/*.md" --strategy high_quality # Deprecated: contextualization is now configured at the store level # mxbai store sync "my-knowledge-base" "**/*.md" --strategy high_quality --contextualization # Dry run to preview changes mxbai store sync "my-knowledge-base" "docs/**/*.md" --dry-run # Skip confirmation prompt mxbai store sync "my-knowledge-base" "**/*.md" --yes # Force sync all files regardless of changes mxbai store sync "my-knowledge-base" "**/*.md" --force # Sync and set metadata mxbai store sync "my-knowledge-base" "docs/**" --metadata '{"updated": "2024-01-15"}' # Sync in CI/CD environment mxbai store sync "my-knowledge-base" "docs/**" --yes --from-git HEAD~1 ``` # Introduction (/mcp) The Mixedbread MCP Server is the missing link between your AI assistants and your knowledge Stores. Todays AI agents are powerful, but their built-in search capabilities are weak. Web search and local grep often waste context, take forever, surface irrelevant results and struggle with complex search queries. The MCP changes that. By connecting your AI directly to our Search API, it improves context usage, retrieval accuracy and reduces latency. ## What You Can Do [#what-you-can-do] With the MCP you empower your favorite LLM to: * Search documents - Find relevant information using natural language queries * Manage knowledge bases - Create, list, and delete Stores for different projects * Handle complex queries - Combine multiple search operations for deeper research ## Get Started [#get-started] * [Integration Guides](/mcp/integrations/claude-desktop) - Platform-specific setup for Claude Desktop, Cursor, and more * [Tools Reference](/mcp/tools) - Complete documentation of available commands # Tools (/mcp/tools) The Mixedbread MCP server provides a comprehensive set of tools for store management and search. ## Tool Categories [#tool-categories] * **[Store Search](#store-search)** * **[Store File Search](#store-file-search)** * **[Store Create](#store-create)** * **[Store Retrieve](#store-retrieve)** * **[Store List](#store-list)** * **[Store Delete](#store-delete)** ## Search Operations [#search-operations] ### Store Search [#store-search] Search for relevant document chunks within stores. **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------- | --------- | -------- | ------- | ------------------------------------------ | | `query` | string | Yes | - | The search query text | | `store_identifiers` | string\[] | Yes | - | Array of store IDs or names to search in | | `top_k` | number | No | 5 | Number of top results to return (max: 100) | | `filters` | object | No | - | Custom filters to apply to the search | | `file_ids` | string\[] | No | - | Specific file IDs to search within | | `search_options` | object | No | - | Additional search configuration options | ### Store File Search [#store-file-search] Search for relevant files stored in stores. **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------- | --------- | -------- | ------- | ---------------------------------- | | `query` | string | Yes | - | The search query text | | `store_identifiers` | string\[] | Yes | - | Array of store IDs or names | | `top_k` | number | No | 5 | Number of top files to return | | `filters` | object | No | - | Custom filters to apply | | `file_ids` | string\[] | No | - | Specific file IDs to search within | | `search_options` | object | No | - | Advanced search options | ## Store Management [#store-management] ### Store Create [#store-create] Create a new store with specified name and optional description. **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | ------------------------------------------- | | `name` | string | Yes | - | Name of the store (must be unique) | | `description` | string | No | - | Optional description of the store's purpose | ### Store Retrieve [#store-retrieve] Get detailed information about a specific store. **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------ | ------ | -------- | ------- | --------------------------- | | `store_identifier` | string | Yes | - | The identifier of the store | ### Store List [#store-list] List all available stores with optional filtering and pagination. **Parameters:** | Parameter | Type | Required | Default | Description | | --------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------- | | `q` | string | No | - | Search query for fuzzy matching over name and description fields | | `limit` | number | No | 20 | Maximum number of items to return per page (1-100) | | `after` | string | No | - | Cursor for forward pagination - get items after this position. Use last\_cursor from previous response. | | `before` | string | No | - | Cursor for backward pagination - get items before this position. Use first\_cursor from previous response. | | `include_total` | boolean | No | false | Whether to include total count in response (expensive operation) | ### Store Delete [#store-delete] Delete an existing store and all its contents. **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------ | ------ | -------- | ------- | ------------------------------------- | | `store_identifier` | string | Yes | - | The identifier of the store to delete | **Warning:** This action is irreversible. All files and chunks in the store will be permanently deleted. # Claude Code (/mcp/integrations/claude-code) Learn how to set up the Mixedbread MCP server with Claude Code. ## Prerequisites [#prerequisites] Before we configure Claude Code, make sure you have the following: * [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed * [Node.js 22+](https://nodejs.org) installed * A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration [#configuration] You can configure the Mixedbread MCP server in Claude Code either by importing from Claude Desktop or running the `claude mcp add` command. ### Method 1 — Import from Claude Desktop [#method-1--import-from-claude-desktop] 1. Import your Claude Desktop MCP configuration into Claude Code: ```bash claude mcp add-from-claude-desktop ``` ### Method 2 — CLI command [#method-2--cli-command] To configure the Mixedbread MCP server globally: 1. Add the Mixedbread server: ```bash claude mcp add mixedbread --transport stdio --scope user -- npx -y mcp-remote@latest https://www.mcp.mixedbread.com/api/mcp --header "Authorization: Bearer YOUR_MIXEDBREAD_API_KEY" ``` 2. Notes: * **--transport stdio** connects locally via stdio to mcp-remote, which tunnels to the remote Mixedbread MCP server. * **--scope user** sets the configuration scope to your user profile. * **--** separates Claude's flags from the mcp-remote command and arguments. 3. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). ## Verification [#verification] Now let's confirm the integration is working. 1. List all configured servers: ```bash claude mcp list ``` 2. Use the `/mcp` command to view available tools and server status. 3. Test the connection with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from Claude Code. ## References [#references] * [Claude Code docs: Model Context Protocol](https://docs.claude.com/en/docs/claude-code/mcp) # Claude Desktop (/mcp/integrations/claude-desktop) Learn how to set up the Mixedbread MCP server with Claude Desktop. ## Prerequisites [#prerequisites] Before we configure Claude Desktop, make sure you have the following: * [Claude Desktop](https://claude.ai/download) installed * A [Mixedbread account](https://platform.mixedbread.com) ## Configuration [#configuration] You can connect Claude Desktop to the Mixedbread MCP server using either the built-in custom connector or a manual configuration file. ### Method 1 — Custom Connector (Recommended) [#method-1--custom-connector-recommended] Claude Desktop supports adding remote MCP servers directly from the UI. This is the simplest way to connect. 1. Open Claude Desktop → **Settings** → **Connectors**. 2. Click **Add custom connector**. 3. Enter the Mixedbread MCP server URL: ``` https://www.mcp.mixedbread.com/api/mcp ``` 4. Click **Add**. 5. You will be redirected to sign in to your Mixedbread account and authorize Claude Desktop. 6. Review the requested permissions and click **Authorize**. That's it — no API key or config file needed. Custom connectors are available on Claude Pro, Max, Team, and Enterprise plans. ### Method 2 — Configuration File [#method-2--configuration-file] If you prefer manual setup or need more control, you can configure the server via the `claude_desktop_config.json` file. **Additional prerequisites:** * [Node.js 22+](https://nodejs.org) installed * A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform **Steps:** 1. Locate the configuration file: * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` * Windows: `%APPDATA%\Claude\claude_desktop_config.json` * Linux: `~/.config/Claude/claude_desktop_config.json` 2. Open and edit configuration: * Open Claude Desktop → Settings * Navigate to Developer in the sidebar * Click Edit Config 3. Add a Mixedbread server entry Add the following to your `claude_desktop_config.json`: ```json { "mcpServers": { "mixedbread": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "env": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" } } } } ``` * **command** runs mcp-remote via npx. * **args** specify the Mixedbread MCP endpoint and authentication header. * **env** sets an environment variable with your API key. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). 4. Save and restart Claude Desktop: * Save the file and fully restart Claude Desktop for the changes to take effect. ## Verification [#verification] Now let's confirm the integration is working. 1. Open a new conversation in Claude Desktop. 2. Click Search & Tools in the input field and verify that Mixedbread is connected. 3. Test the connection with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from Claude Desktop. ## References [#references] * [Claude Help Center: Custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) * [MCP docs: Connect remote servers](https://modelcontextprotocol.io/docs/develop/connect-remote-servers) # Codex CLI (/mcp/integrations/codex-cli) Learn how to set up the Mixedbread MCP server with the Codex CLI. ## Prerequisites [#prerequisites] Before we configure Codex, make sure you have the following: * [Codex CLI](https://developers.openai.com/codex/cli/) installed * [Node.js 22+](https://nodejs.org) installed * A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration [#configuration] Codex configures MCP servers via a configuration file named `config.toml`. 1. Locate the configuration file Global scope: `~/.codex/config.toml` If this file doesn't exist yet, you can create it manually. 2. Add a Mixedbread server entry Add the following to your `config.toml`: ```toml [mcp_servers.mixedbread] command = "npx" args = [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ] [mcp_servers.mixedbread.env] MXBAI_AUTH_HEADER = "Bearer YOUR_MIXEDBREAD_API_KEY" ``` * **command** tells Codex to run mcp-remote via npx. * **args** specify the remote MCP endpoint and the header used for authentication. * **env** sets an environment variable that contains your API key. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual API key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). ## Verification [#verification] Now let's confirm the integration is working. 1. Open the Codex CLI and start a chat session. 2. Use the `/mcp` command to list configured MCP servers and verify that `Mixedbread` appears in the output. 3. Test the connection with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from the Codex CLI. ## References [#references] * [Codex docs: Model Context Protocol](https://developers.openai.com/codex/config-advanced#mcp-servers) # Cursor (/mcp/integrations/cursor) Learn how to set up the Mixedbread MCP server with Cursor IDE. ## Prerequisites [#prerequisites] Before we configure Cursor, make sure you have the following: * [Cursor IDE](https://cursor.sh) installed * [Node.js 22+](https://nodejs.org) installed * A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration [#configuration] Cursor supports MCP servers via a configuration file named `mcp.json`. ### Method 1 — Edit via the terminal [#method-1--edit-via-the-terminal] 1. Locate or create the configuration file Cursor looks for `mcp.json` in the following paths: * **macOS/Linux:** `~/.cursor/mcp.json` * **Windows:** `%USERPROFILE%\.cursor\mcp.json` If the directory or file doesn't exist, create it manually: **macOS/Linux:** ```bash mkdir -p ~/.cursor touch ~/.cursor/mcp.json ``` **Windows:** ```powershell New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.cursor" New-Item -ItemType File -Force -Path "$env:USERPROFILE\.cursor\mcp.json" ``` 2. Add a Mixedbread server entry Add the following to your `mcp.json`: ```json { "mcpServers": { "mixedbread": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "env": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" } } } } ``` * **command** runs mcp-remote via npx. * **args** specify the Mixedbread MCP endpoint and authentication header. * **env** sets an environment variable with your API key. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). 3. Save and restart Cursor to apply the changes. ### Method 2 — Add via the UI [#method-2--add-via-the-ui] 1. Open Settings → Cursor Settings → MCP → New MCP Server. 2. Paste the Mixedbread configuration from Method 1. 3. Save. Cursor will automatically reload the MCP servers. ## Verification [#verification] Now let's confirm the integration is working. 1. Open Settings → Cursor Settings → MCP and check that `Mixedbread` is listed. 2. Ensure Cursor is in Agent Mode so MCP tools can be used. 3. Test the connection with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from Cursor. ## References [#references] * [Cursor docs: Model Context Protocol](https://cursor.com/docs/context/mcp#model-context-protocol-mcp) # Gemini CLI (/mcp/integrations/gemini-cli) Learn how to set up the Mixedbread MCP server with the Gemini CLI. ## Prerequisites [#prerequisites] Before we configure Gemini CLI, make sure you have the following: * [Gemini CLI](https://google-gemini.github.io/gemini-cli/) installed * [Node.js 22+](https://nodejs.org) installed * A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration [#configuration] Gemini CLI configures MCP servers via a configuration file named `settings.json`. 1. Locate the configuration file Global scope: `~/.gemini/settings.json` If this file doesn't exist yet, you can create it manually. 2. Add a Mixedbread server entry Add the following to your `settings.json`: ```json { "mcpServers": { "mixedbread": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "env": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" }, "trust": false, "timeout": 600000 } } } ``` * **command** tells Gemini to run mcp-remote via npx. * **args** specify the remote MCP endpoint and the header used for authentication. * **env** sets an environment variable that contains your API key. * **trust** controls whether tools require confirmation before execution. * **timeout** sets the request timeout in milliseconds. Defaults to 600000ms (10 minutes). Replace `YOUR_MIXEDBREAD_API_KEY` with your actual API key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). ## Verification [#verification] Now let's confirm the integration is working. 1. List servers: ```bash gemini mcp list ``` You should see `Mixedbread` in the output. 2. Test the connection with a simple command in chat: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from the Gemini CLI. ## References [#references] * [Gemini CLI docs: MCP servers](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) # OpenCode (/mcp/integrations/opencode) Learn how to set up the Mixedbread MCP server with OpenCode. ## Prerequisites [#prerequisites] Before we configure OpenCode, make sure you have the following: * [OpenCode](https://opencode.ai) installed * [Node.js 22+](https://nodejs.org) installed * A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration [#configuration] OpenCode configures MCP servers via a configuration file named `opencode.json`. 1. Create the configuration file The recommended setup is project-level: Place an `opencode.json` file in the root of your repository. 2. Add a Mixedbread server entry Add the following to your `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "mixedbread": { "type": "local", "command": [ "npx", "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "enabled": true, "environment": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" } } } } ``` * **type** specifies that the server runs locally. * **command** runs mcp-remote with the Mixedbread MCP endpoint and authentication header. * **enabled** controls whether the server is active. * **environment** sets your API key as an environment variable. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). ## Verification [#verification] Now let's confirm the integration is working. 1. Start OpenCode and reload the configuration. 2. Confirm the `Mixedbread` server is listed under tools and enabled. 3. Test the connection with a simple command, for example: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from OpenCode. ## References [#references] * [OpenCode docs: MCP servers](https://opencode.ai/docs/mcp-servers) # VS Code (/mcp/integrations/vs-code) Learn how to set up the Mixedbread MCP server with Visual Studio Code. ## Prerequisites [#prerequisites] Before we configure VS Code, make sure you have the following: * [Visual Studio Code](https://code.visualstudio.com) installed * [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) extension * [Node.js 22+](https://nodejs.org) installed * A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration [#configuration] VS Code configures MCP servers via a configuration file named `mcp.json`. 1. Open the configuration file From the Command Palette, run: ``` MCP: Configure Servers ``` This will open `mcp.json` for your current scope. 2. Add a Mixedbread server entry Add the following to your `mcp.json`: ```json { "servers": { "mixedbread": { "type": "stdio", "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "env": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" } } } } ``` * **command** runs mcp-remote via npx. * **args** specify the Mixedbread MCP endpoint and authentication header. * **env** sets an environment variable with your API key. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). ## Enable and Use in Agent Mode [#enable-and-use-in-agent-mode] 1. Open Copilot Chat in Agent Mode. 2. Select the Tools button and ensure `Mixedbread` is enabled. 3. Test the connection with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from VS Code. ## References [#references] * [VS Code docs: MCP servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) # Windsurf (/mcp/integrations/windsurf) Learn how to set up the Mixedbread MCP server with Windsurf. ## Prerequisites [#prerequisites] Before we configure Windsurf, make sure you have the following: * [Windsurf](https://windsurf.com) installed * [Node.js 22+](https://nodejs.org) installed * A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration [#configuration] Windsurf configures MCP servers via a configuration file named `mcp_config.json`. 1. Locate or create the configuration file Windsurf looks for `mcp_config.json` in the following paths: * **macOS/Linux:** `~/.codeium/windsurf/mcp_config.json` * **Windows:** `%USERPROFILE%\.codeium\windsurf\mcp_config.json` If the directory or file doesn't exist, create it manually: **macOS/Linux:** ```bash mkdir -p ~/.codeium/windsurf touch ~/.codeium/windsurf/mcp_config.json ``` **Windows (PowerShell):** ```powershell New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codeium\windsurf" New-Item -ItemType File -Force -Path "$env:USERPROFILE\.codeium\windsurf\mcp_config.json" ``` 2. Add a Mixedbread server entry Add the following to your `mcp_config.json`: ```json { "mcpServers": { "mixedbread": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "env": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" } } } } ``` * **command** runs mcp-remote via npx. * **args** specify the Mixedbread MCP endpoint and authentication header. * **env** sets an environment variable with your API key. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). ## Managing Tools [#managing-tools] Cascade limits total enabled tools to 100 at a time. You can manage tool access by: * Opening the Tools tab inside the plugin * Navigating to Windsurf Settings → Cascade → Manage plugins From here, you can toggle specific tools on or off. ## Verification [#verification] Now let's confirm the integration is working. 1. Open the Cascade panel → Plugins and press Refresh. 2. Confirm that `Mixedbread` appears and is enabled. 3. Start a session and test Mixedbread tools with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from Windsurf. ## References [#references] * [Windsurf docs: Model Context Protocol](https://docs.windsurf.com/windsurf/cascade/mcp) # Zed (/mcp/integrations/zed) Learn how to set up the Mixedbread MCP server with Zed. ## Prerequisites [#prerequisites] Before we configure Zed, make sure you have the following: * [Zed](https://zed.dev) installed * [Node.js 22+](https://nodejs.org) installed * A [Mixedbread API key](https://platform.mixedbread.com/platform?next=api-keys) from our platform ## Configuration [#configuration] Zed configures MCP servers via a configuration file named `settings.json`. ### Method 1 — Edit settings.json [#method-1--edit-settingsjson] 1. Open Zed settings: * Command Palette → Zed: Open settings 2. Add the Mixedbread MCP server by adding the following JSON to your `settings.json`: ```json { "context_servers": { "mixedbread": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://www.mcp.mixedbread.com/api/mcp", "--header", "Authorization:${MXBAI_AUTH_HEADER}" ], "env": { "MXBAI_AUTH_HEADER": "Bearer YOUR_MIXEDBREAD_API_KEY" } } } } ``` * **source** specifies a custom context server. * **command** runs mcp-remote with the Mixedbread MCP endpoint. * **env** sets an environment variable with your API key. Replace `YOUR_MIXEDBREAD_API_KEY` with your actual key from the [Mixedbread platform](https://platform.mixedbread.com/platform?next=api-keys). 3. Save your settings. Zed will start the server shortly after saving. You can confirm status in the Agent Panel. ### Method 2 — Add via Agent Panel UI [#method-2--add-via-agent-panel-ui] 1. Open the Agent Panel → Settings. 2. Click Add Custom Server. 3. Fill in the fields: * Name: mixedbread * Command: npx * Args: * `-y` * `mcp-remote@latest` * `https://www.mcp.mixedbread.com/api/mcp` * `--header` * `Authorization:${MXBAI_AUTH_HEADER}` * Env: * `MXBAI_AUTH_HEADER=Bearer YOUR_MIXEDBREAD_API_KEY` 4. Save. The server should appear in the panel with a status indicator. ## Verification [#verification] Now let's confirm the integration is working. 1. Open the Agent Panel → Settings. 2. Confirm the status dot next to `Mixedbread` is green and the tooltip says "Server is active." 3. Test the connection with a simple command: ```bash Create a new store called "my-knowledge-base" ``` Now you can manage your Stores and perform Search directly from Zed. ## References [#references] * [Zed docs: Model Context Protocol](https://zed.dev/docs/ai/mcp)