mixedbread-search

Mixedbread Search

Create and search managed knowledge bases using the Stores API. Stores are multimodal search indexes that handle text, images, tables, audio, and video across 100+ languages.

Docs: https://www.mixedbread.com/docs/stores/overview.md Agent-readable docs: https://www.mixedbread.com/docs/llms.txt Latest docs search: https://www.mixedbread.com/question?q=stores&section=docs

Setup

pip install mixedbread          # Python
npm install @mixedbread/sdk     # TypeScript

export MXBAI_API_KEY=your_api_key

Quick Start

Python:

import os
from mixedbread import Mixedbread

mxbai = Mixedbread(api_key=os.environ["MXBAI_API_KEY"])

store = mxbai.stores.create(name="my-docs", description="Product documentation")

mxbai.stores.files.upload(
    store_identifier=store.id,
    file=open("guide.pdf", "rb"),
    metadata={"category": "guides", "version": "2.0"},
)

results = mxbai.stores.search(
    query="How does authentication work?",
    store_identifiers=["my-docs"],
    top_k=5,
)
for chunk in results.data:
    print(f"{chunk.score:.3f} | {chunk.filename}: {chunk.text[:100]}")

TypeScript:

import { Mixedbread } from '@mixedbread/sdk';
import fs from 'fs';

const mxbai = new Mixedbread({
    apiKey: process.env.MXBAI_API_KEY!,
});

const store = await mxbai.stores.create({
    name: 'my-docs',
    description: 'Product documentation',
});

await mxbai.stores.files.upload({
    storeIdentifier: store.id,
    file: fs.createReadStream('guide.pdf'),
    body: { metadata: { category: 'guides', version: '2.0' } },
});

const results = await mxbai.stores.search({
    query: 'How does authentication work?',
    store_identifiers: ['my-docs'],
    top_k: 5,
});

Decision Tree

• What kind of retrieval do you need?
  • Simple keyword/semantic lookup → Standard search() with top_k
  • Natural-language answer with citations → question_answering() with cite enabled
  • Complex multi-hop question → search() with agentic enabled
  • Combine internal docs with live web → Add "mixedbread/web" to store_identifiers
• Do you need metadata filtering?
  • Don't know what metadata exists → Call metadata_facets() first
  • Know the fields → Build filters with all/any/none combinators
• Do you need higher relevance?
  • Yes → Set "rerank": true in search_options, or use {"rerank": {"model": "mixedbread-ai/mxbai-rerank-large-v2"}} to choose a model
• Do you need OCR, summaries, or transcriptions from files?
  • Yes → Upload files with config: {"parsing_strategy": "high_quality"}. Stores auto-extract OCR text, summaries, and transcriptions — no separate parsing needed.
  • No / text-only documents → Default parsing_strategy ("fast") is sufficient.
• Does the user's query language overlap with metadata fields (titles, categories, authors)?
  • Yes → Enable contextualization at store creation so embeddings carry that metadata. See Contextualization.
  • No → Leave it off (the default).
• Do you need the exact stored chunks for a known file (not a query)?
  • Yes → Call stores.files.retrieve() with return_chunks=True (or a list of indices). See Retrieve Chunks by File.
  • No, you want relevance ranking → Use search().
• Is the store temporary (e.g., PR review)?
  • Yes → Set expires_after with a day limit at creation

Workflows

Build a Searchable Knowledge Base

Create a store, upload documents, and search. Most of the time you do not need to poll for finished files. Only gate on processing when the workflow depends on complete batch coverage, such as benchmarks or recall evaluation.

Python:

store = mxbai.stores.create(
    name="product-docs",
    description="Product documentation",
    config={"contextualization": {"with_metadata": ["title", "category"]}},
)

mxbai.stores.files.upload(
    store_identifier=store.id,
    file=open("guide.pdf", "rb"),
    metadata={"title": "Setup Guide", "category": "guides"},
)
mxbai.stores.files.upload(
    store_identifier=store.id,
    file=open("faq.md", "rb"),
    metadata={"title": "FAQ", "category": "support"},
)

results = mxbai.stores.search(
    query="How do I reset my password?",
    store_identifiers=["product-docs"],
    top_k=5,
    search_options={"rerank": True, "return_metadata": True},
)
for chunk in results.data:
    print(f"{chunk.score:.3f} | {chunk.filename}: {chunk.text[:100]}")

# Optional: poll store.file_counts if you need deterministic full-batch coverage (benchmarks, migrations).

TypeScript:

const store = await mxbai.stores.create({
    name: 'product-docs',
    description: 'Product documentation',
    config: { contextualization: { with_metadata: ['title', 'category'] } },
});

await mxbai.stores.files.upload({
    storeIdentifier: store.id,
    file: fs.createReadStream('guide.pdf'),
    body: { metadata: { title: 'Setup Guide', category: 'guides' } },
});
await mxbai.stores.files.upload({
    storeIdentifier: store.id,
    file: fs.createReadStream('faq.md'),
    body: { metadata: { title: 'FAQ', category: 'support' } },
});

const results = await mxbai.stores.search({
    query: 'How do I reset my password?',
    store_identifiers: ['product-docs'],
    top_k: 5,
    search_options: { rerank: true, return_metadata: true },
});

// Optional: poll store.file_counts if you need deterministic full-batch coverage (benchmarks, migrations).

Filter-Driven Search

Discover available metadata, then build targeted filters.

Python:

facets = mxbai.stores.metadata_facets(store_identifiers=["product-docs"])
for key, values in facets.facets.items():
    print(f"{key}: {values}")

results = mxbai.stores.search(
    query="deployment guide",
    store_identifiers=["product-docs"],
    top_k=10,
    filters={
        "all": [
            {"key": "category", "operator": "eq", "value": "guides"},
            {"key": "status", "operator": "not_eq", "value": "archived"},
        ]
    },
    search_options={"rerank": True, "return_metadata": True},
)

TypeScript:

const facets = await mxbai.stores.metadataFacets({
    store_identifiers: ['product-docs'],
});
for (const [key, values] of Object.entries(facets.facets ?? {})) {
    console.log(`${key}: ${JSON.stringify(values)}`);
}

const results = await mxbai.stores.search({
    query: 'deployment guide',
    store_identifiers: ['product-docs'],
    top_k: 10,
    filters: {
        all: [
            { key: 'category', operator: 'eq', value: 'guides' },
            { key: 'status', operator: 'not_eq', value: 'archived' },
        ],
    },
    search_options: { rerank: true, return_metadata: true },
});

Filter operators: eq, not_eq, gt, gte, lt, lte, in, not_in, like, starts_with, not_like, regex. Combine with all (AND), any (OR), none (NOT).

Web-Augmented Search

Include "mixedbread/web" in store_identifiers to combine store search with live web results. This is a reserved store identifier — no setup required. You can also search the web alone.

Python:

results = mxbai.stores.search(
    query="latest best practices",
    store_identifiers=["my-docs", "mixedbread/web"],
)

TypeScript:

const results = await mxbai.stores.search({
    query: 'latest best practices',
    store_identifiers: ['my-docs', 'mixedbread/web'],
});

Contextualization

Appends selected file metadata to chunk text before embedding, so queries that overlap with fields like title, category, or author rank more accurately. Configured on the store's config.contextualization at creation time and only affects files uploaded afterward. Look up the modes (false / true / {"with_metadata": [...]}) in the Stores docs — fetch llms.txt (linked at the top of this skill) and follow the link to the Stores configuration page.

Retrieve Chunks by File

When you already know the file (preview, export, ingestion debugging) and don't need ranking, call stores.files.retrieve() with return_chunks=True (all chunks) or return_chunks=[indices] (specific chunk_index positions). For the exact request/response shape, look up the "Get Store File" endpoint in the API reference — fetch llms.txt and follow the link, or search the docs.

Question Answering

Get a generated answer with cited sources. The answer may contain <cite i="n"/> tags referencing the sources list.

Python:

result = mxbai.stores.question_answering(
    query="What are the rate limits?",
    store_identifiers=["my-docs"],
    top_k=10,
    qa_options={"cite": True},
    search_options={"rerank": True},
)
print(result.answer)
for source in result.sources:
    print(f"  {source.filename} (score: {source.score:.3f})")

TypeScript:

const result = await mxbai.stores.questionAnswering({
    query: 'What are the rate limits?',
    store_identifiers: ['my-docs'],
    top_k: 10,
    qa_options: { cite: true },
    search_options: { rerank: true },
});
console.log(result.answer);
for (const source of result.sources) {
    console.log(`  ${source.filename} (score: ${source.score.toFixed(3)})`);
}

Question Answering with Agentic Fallback

When QA returns no sources, retry with agentic search for deeper retrieval. Always re-call question_answering() — do not fall back to raw search(), which loses the generated answer.

Python:

result = mxbai.stores.question_answering(
    query="Compare the pricing tiers and their feature differences",
    store_identifiers=["my-docs"],
    top_k=10,
    qa_options={"cite": True},
    search_options={"rerank": True},
)

if not result.sources:
    result = mxbai.stores.question_answering(
        query="Compare the pricing tiers and their feature differences",
        store_identifiers=["my-docs"],
        top_k=10,
        qa_options={"cite": True},
        search_options={
            "rerank": True,
            "agentic": {"max_rounds": 3},
        },
    )

print(result.answer)
for source in result.sources:
    print(f"  {source.filename} (score: {source.score:.3f})")

Agentic Search

For complex questions requiring multi-step retrieval. The system decomposes your query into sub-queries and runs multiple rounds. Works in both search() and question_answering().

Python:

results = mxbai.stores.search(
    query="Compare the pricing tiers and their feature differences",
    store_identifiers=["product-docs"],
    search_options={
        "agentic": {
            "max_rounds": 3,
            "queries_per_round": 2,
            "instructions": (
                "Prioritize official pricing pages over blog posts. "
                "Surface tier names, monthly cost, and included feature lists."
            ),
        }
    },
)

TypeScript:

const results = await mxbai.stores.search({
    query: 'Compare the pricing tiers and their feature differences',
    store_identifiers: ['product-docs'],
    search_options: {
        agentic: {
            max_rounds: 3,
            queries_per_round: 2,
            instructions:
                'Prioritize official pricing pages over blog posts. ' +
                'Surface tier names, monthly cost, and included feature lists.',
        },
    },
});

Agentic options

• agentic: true — enable with defaults.
• agentic: { ... } — override individual fields:
  • max_rounds (default 3, range 1–10) — maximum retrieval rounds.
  • queries_per_round (default 3, range 1–5) — sub-queries generated per round.
  • instructions (string, up to 2000 chars) — the agent prompt input. Tells the agent how to plan and rank its searches: which entities, metrics, or source types to prioritize; what to treat as authoritative; what to ignore. The top-level query remains the user's question — use instructions for guidance that shouldn't appear in every sub-query.

When agentic is enabled, search_options.rewrite_query and search_options.rerank are ignored — the agent handles query decomposition and ranking itself.

Writing good agentic instructions

• Prefer directive phrases ("prioritize X", "ignore Y", "treat Z as authoritative") over restating the question.
• Name the concrete fields, metrics, or document types to surface so ranking is grounded in what you care about.
• Keep the question itself in query; put ranking/planning guidance in instructions.

Response Shapes

Search results (search() returns):

response.data  # list of chunks
chunk.text       # str — the matched text
chunk.score      # float — relevance score (0–1)
chunk.filename   # str — source file name
chunk.file_id    # str — source file ID
chunk.store_id   # str — store the chunk belongs to
chunk.metadata   # dict — attached metadata (when return_metadata is enabled)
chunk.type       # str — chunk type (e.g. "text", "image_url")
chunk.image_url  # dict | None — image payload for image chunks
chunk.ocr_text   # str | None — OCR text for image-heavy chunks
chunk.summary    # str | None — auto-generated summary for image chunks (high_quality mode)
chunk.transcription # str | None — transcription for audio/video chunks (high_quality mode)

QA results (question_answering() returns):

result.answer    # str — generated answer, may contain <cite i="n"/> tags
result.sources   # list of source objects
source.filename  # str
source.score     # float
source.file_id   # str
source.text      # str — the source chunk text
source.image_url # dict | None — image payload with url/format for image chunks

Store Management

stores = mxbai.stores.list(limit=20)
for store in stores.data:
    print(store.name)

store = mxbai.stores.retrieve(store_identifier="my-docs")
print(store.file_counts)  # {"completed": 5, "in_progress": 2, "failed": 0}

mxbai.stores.delete(store_identifier="my-docs")

files = mxbai.stores.files.list(store_identifier="my-docs", limit=20)
for file in files.data:
    print(file.filename, file.status)

Rules

CRITICAL

• Store names must be lowercase letters, numbers, hyphens, and periods only. Invalid names cause creation to fail. No spaces, underscores, or uppercase.
• For field-level contextualization, use the documented {"with_metadata": [...]} form. The other documented modes are true (all metadata) and false (none). Dot notation is supported for nested fields.

HIGH

• Do not block on full ingestion unless completeness matters. Stores process files asynchronously, and completed files become searchable as they finish. Most of the time, especially for interactive flows, upload and search immediately without polling. Poll file status or file_counts only when the workflow depends on complete batch coverage, such as benchmarks, migrations, or sync verification.
• Use metadata_facets() before building filters. Don't guess metadata keys — discover them. Typos in filter keys silently return no results.
• Enable rerank for production search. Reranking significantly improves relevance. Only skip it for latency-sensitive prototyping.
• Use parsing_strategy: "high_quality" to enable automatic content extraction. When set in per-file config at upload time, high quality mode extracts OCR text and summaries for images, and transcriptions for audio and video. These fields are directly usable as LLM context. The default "fast" strategy indexes content without these additional extractions.
• Use standard search for simple lookups. Agentic search adds latency from multiple retrieval rounds. Only use it for complex, multi-hop questions.

MEDIUM

• Set expires_after for temporary stores. PR review stores, demo stores, and test stores should auto-expire to avoid accumulating unused indexes.
• One store per knowledge domain, not per query. Stores are persistent indexes meant to be reused. Create once, search many times.
• Use chunk scores to filter low-relevance noise. If you need a minimum relevance cutoff, post-filter on chunk.score (for example >= 0.3) after retrieval.
• Start with default agentic settings. Only increase max_rounds if results are insufficient.
• Use agentic.instructions to steer retrieval, not query. Keep query as the user's natural-language question. Put "prioritize X", "ignore Y", source-type preferences, and ranking hints in search_options.agentic.instructions (up to 2000 chars).

Troubleshooting

Symptom	Cause	Fix
No results returned	Newly uploaded files are still processing, or the store name/query is wrong	Retry after processing completes for at least one file. For completeness-sensitive runs, verify the expected files are completed before evaluating results.
No results returned	Score cutoff too high	Lower or remove your post-filter threshold.
No results returned	Wrong store_identifiers	Verify the store name or ID matches exactly.
Metadata filters return nothing	Wrong key name or value	Use metadata_facets() to discover actual keys and values.
Slow agentic search	Too many rounds or queries	Reduce max_rounds or queries_per_round. Use standard search if the query is simple.
API key error	Invalid or missing key	Verify MXBAI_API_KEY is set. Get a key at https://platform.mixedbread.com/platform?next=api-keys