Concepts
Mixedbread Search has a small number of core concepts. This page walks through each one and shows how they connect.
High-Level ArchitectureLink to section
Files get split into chunks and ingested into a Store. You query the Store with natural language, and it returns the relevant chunks.
The API exposes three objects: Store, Store File, and Chunk. You read from it through Search and Agentic Search.
StoreLink to section
A Store holds a searchable collection of files. Every search runs against one or more Stores.
Common uses:
- A product's documentation
- A customer knowledge base
- A codebase
- A research library
Each Store has a unique ID and an optional human-readable name. Either works as an identifier in API calls. The object also exposes file counts by processing state, total storage used, and an optional expiration policy.
See Data Models → Store for the full object, or Create Stores to make one.
Store FileLink to section
A Store File represents an uploaded file. It tracks the original filename, any metadata you attached, the processing status, and a version number. Each file is split into chunks, and those chunks are what search runs against.
When you upload a file, it moves through a small lifecycle:
If parsing fails, the file ends up in a failed state instead of completed. The specific error is available on last_error.
While in_progress, Mixedbread parses the file, splits it into chunks, and generates embeddings. Parsing covers OCR for scans, layout understanding for PDFs, and transcription for audio and video. Once a file reaches completed, its chunks are searchable.
File metadata propagates to every chunk produced from the file. That means you can filter searches by file-level attributes like category or version without attaching metadata to each chunk individually.
For the full object, see Data Models → Store File. To upload files, see Create Files.
ChunkLink to section
A Chunk is a searchable segment of content produced from a Store File. Every search response is a ranked list of chunks.
How a file splits depends on its type. A PDF usually produces one chunk per page. Long text files split into several text chunks, videos split into timed segments, and so on.
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 with a transcription
- Video: a video segment with a transcription
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.
SearchLink to section
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_ids - 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/webalongside your Stores for hybrid internal and web search
For the full API, see Search.
Agentic SearchLink to section
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 Search → Agentic Search.
Putting It TogetherLink to section
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 is a good starting point. You can also skip straight to Create Stores, Create Files, or Search.