---
title: "Perform semantic search across store chunks"
method: POST
path: "/v1/stores/search"
tags: ["stores"]
---

# Perform semantic search across store chunks

`POST /v1/stores/search`

Perform semantic search across store chunks.

This endpoint searches through store chunks using semantic similarity matching.
It supports complex search queries with filters and returns relevance-scored results.
Agentic searches can set `stream=true` to receive live trace events as
server-sent events while the search runs, followed by the final search response.

For the special 'mixedbread/web' store, this endpoint performs web search using
a mixture of different providers instead of semantic search. Web search results are always
reranked for consistent scoring.

Args:
    search_params: Search configuration including:
        - query text or embeddings
        - store_identifiers: List of store identifiers to search
        - file_ids: Optional list of file IDs to filter chunks by (or tuple of list and condition operator)
        - metadata filters
        - pagination parameters
        - sorting preferences
    _state: API state dependency
    _ctx: Service context dependency

Returns:
    StoreSearchResponse containing:
        - List of matched chunks with relevance scores
        - Pagination details including total result count

Raises:
    HTTPException (400): If search parameters are invalid
    HTTPException (404): If no vector stores are found to search

## Headers

- `X-Mxbai-Tool-Ticket` string, nullable — Ticket from a chat completion's `tool_tickets`, proving this call runs a tool call that completion asked for. Redeems once, and bills the operation at the discounted agent rate.

## Request body

- StoreChunkSearchParams — Query parameters for searching store chunks.
  - `store_identifiers` union[], required — IDs or names of stores
    - union
      - string
      - string, uuid
  - `top_k` integer — Number of results to return
  - `filters` union — Optional filter conditions
    - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
      - `all` union[], nullable — List of conditions or filters to be ANDed together
        - union
          - SearchFilterInput — recursive
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
      - `any` union[], nullable — List of conditions or filters to be ORed together
        - union
          - SearchFilterInput — recursive
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
      - `none` union[], nullable — List of conditions or filters to be NOTed
        - union
          - SearchFilterInput — recursive
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
    - SearchFilterCondition — Represents a condition with a field, operator, and value.
      - `key` string, required — The field to apply the condition on
      - `value` string, required — The value to compare against
      - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
    - union[]
      - union
        - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
          - `all` union[], nullable — List of conditions or filters to be ANDed together
            - union
              - …
          - `any` union[], nullable — List of conditions or filters to be ORed together
            - union
              - …
          - `none` union[], nullable — List of conditions or filters to be NOTed
            - union
              - …
        - SearchFilterCondition — Represents a condition with a field, operator, and value.
          - `key` string, required — The field to apply the condition on
          - `value` string, required — The value to compare against
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
  - `file_ids` string[], nullable — Optional list of file IDs to filter chunks by (inclusion filter)
  - `query` union, required
    - string — The text input document to create embeddings for.
    - union
      - ImageUrlInput — Model for image input validation.
        - `type` 'image_url' — Input type identifier
        - `image_url` ImageUrlInput, required — recursive
      - TextInput — Model for text input validation. Attributes: type: Input type identifier, always "text" text: The actual text content, with length and whitespace constraints
        - `type` 'text' — Input type identifier
        - `text` string, required — Text content to process
  - `search_options` StoreChunkSearchOptions — Options for configuring store chunk searches.
    - `score_threshold` number — Minimum similarity score threshold
    - `rewrite_query` boolean — Whether to rewrite the query. Ignored when agentic is enabled (the agent handles query decomposition).
    - `rerank` union — Whether to rerank results and optional reranking configuration. Ignored when agentic is enabled (the agent handles ranking).
      - boolean
      - RerankConfig — Represents a reranking configuration.
        - `model` string — The name of the reranking model
        - `with_metadata` union — Whether to include metadata in the reranked results
          - boolean
          - string[]
        - `top_k` integer, nullable — Maximum number of results to return after reranking. If None, returns all reranked results.
    - `agentic` union — Whether to use agentic multi-query search with automatic query decomposition and ranking. When enabled, rewrite_query and rerank options are ignored.
      - boolean
      - AgenticSearchConfig — Configuration for agentic multi-query search.
        - `max_rounds` integer — Maximum number of search rounds
        - `queries_per_round` integer — Maximum queries per round
        - `strict_top_k` boolean — Whether the final retrieved chunk list must provide exactly top_k ranked chunks
        - `media_content` 'auto' | 'never' | 'always' — Controls when retrieved image content is provided to the agent. `auto` sends images only when no OCR text or summary is available, `never` disables image content, and `always` sends image content when available. Currently not forwarded: the search agent runs without image content.
        - `instructions` string, nullable — Additional custom instructions (followed only when not in conflict with existing rules)
        - `verbose` boolean — Internal: when set, the response includes a `trace` field with the full tool-call timeline. Used by the Mixedbread playground; not part of the documented public API.
    - `return_metadata` boolean — Whether to return file metadata
    - `apply_search_rules` boolean — Whether to apply search rules
  - `stream` boolean — When true, return live agentic-search trace events as a server-sent event stream. Requires search_options.agentic to be enabled. A successful stream ends with a search.completed event containing the final search response, followed by [DONE].

## Response `200`

List of semantically similar chunks with relevance scores and pagination details

- StoreSearchResponse
  - `object` 'list' — The object type of the response
  - `data` union[], required — The list of scored store file chunks
    - union
      - MxbaiOmniCoreStoreModelsChunkTypesScoredTextInputChunk
        - `chunk_index` integer, required — position of the chunk in a file
        - `mime_type` string — mime type of the chunk
        - `generated_metadata` union — metadata of the chunk
          - MarkdownChunkGeneratedMetadata
            - `type` 'markdown'
            - `file_type` 'text/markdown'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `chunk_headings` MarkdownHeading[]
              - …
            - `heading_context` MarkdownHeading[]
              - …
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
            - `frontmatter` object
          - TextChunkGeneratedMetadata
            - `type` 'text'
            - `file_type` 'text/plain' | 'message/rfc822'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - PDFChunkGeneratedMetadata
            - `type` 'pdf'
            - `file_type` 'application/pdf'
            - `total_pages` integer, nullable
            - `total_size` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
          - CodeChunkGeneratedMetadata
            - `type` 'code'
            - `file_type` string, required
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - AudioChunkGeneratedMetadata
            - `type` 'audio'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `sample_rate` integer, nullable
            - `channels` integer, nullable
            - `audio_format` integer, nullable
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - VideoChunkGeneratedMetadata
            - `type` 'video'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `fps` number, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `frame_count` integer, nullable
            - `has_audio_stream` boolean
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - ImageChunkGeneratedMetadata
            - `type` 'image'
            - `file_type` string
            - `file_size` integer, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
        - `model` string, nullable — model used for this chunk
        - `score` number, required — score of the chunk
        - `file_id` string, required — file id
        - `filename` string, required — filename
        - `store_id` string, required — store id
        - `external_id` string, nullable — external identifier for this file
        - `metadata` unknown
        - `type` 'text' — Input type identifier
        - `offset` integer — The offset of the text in the file relative to the start of the file.
        - `text` string, nullable — Text content
        - `context` string, nullable — LLM-generated context that situates this chunk within its source document
        - `summary` string, nullable — summary of the text chunk
      - MxbaiOmniCoreStoreModelsChunkTypesScoredImageUrlInputChunk
        - `chunk_index` integer, required — position of the chunk in a file
        - `mime_type` string — mime type of the chunk
        - `generated_metadata` union — metadata of the chunk
          - MarkdownChunkGeneratedMetadata
            - `type` 'markdown'
            - `file_type` 'text/markdown'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `chunk_headings` MarkdownHeading[]
              - …
            - `heading_context` MarkdownHeading[]
              - …
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
            - `frontmatter` object
          - TextChunkGeneratedMetadata
            - `type` 'text'
            - `file_type` 'text/plain' | 'message/rfc822'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - PDFChunkGeneratedMetadata
            - `type` 'pdf'
            - `file_type` 'application/pdf'
            - `total_pages` integer, nullable
            - `total_size` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
          - CodeChunkGeneratedMetadata
            - `type` 'code'
            - `file_type` string, required
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - AudioChunkGeneratedMetadata
            - `type` 'audio'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `sample_rate` integer, nullable
            - `channels` integer, nullable
            - `audio_format` integer, nullable
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - VideoChunkGeneratedMetadata
            - `type` 'video'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `fps` number, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `frame_count` integer, nullable
            - `has_audio_stream` boolean
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - ImageChunkGeneratedMetadata
            - `type` 'image'
            - `file_type` string
            - `file_size` integer, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
        - `model` string, nullable — model used for this chunk
        - `score` number, required — score of the chunk
        - `file_id` string, required — file id
        - `filename` string, required — filename
        - `store_id` string, required — store id
        - `external_id` string, nullable — external identifier for this file
        - `metadata` unknown
        - `type` 'image_url' — Input type identifier
        - `ocr_text` string, nullable — ocr text of the image
        - `context` string, nullable — LLM-generated context that situates this image within its source document
        - `summary` string, nullable — summary of the image
        - `image_url` ImageUrlOutput — Model for image URL validation.
          - `url` string, required — The image URL. Can be either a URL or a Data URI.
          - `format` string — The image format/mimetype
      - MxbaiOmniCoreStoreModelsChunkTypesScoredAudioUrlInputChunk
        - `chunk_index` integer, required — position of the chunk in a file
        - `mime_type` string — mime type of the chunk
        - `generated_metadata` union — metadata of the chunk
          - MarkdownChunkGeneratedMetadata
            - `type` 'markdown'
            - `file_type` 'text/markdown'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `chunk_headings` MarkdownHeading[]
              - …
            - `heading_context` MarkdownHeading[]
              - …
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
            - `frontmatter` object
          - TextChunkGeneratedMetadata
            - `type` 'text'
            - `file_type` 'text/plain' | 'message/rfc822'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - PDFChunkGeneratedMetadata
            - `type` 'pdf'
            - `file_type` 'application/pdf'
            - `total_pages` integer, nullable
            - `total_size` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
          - CodeChunkGeneratedMetadata
            - `type` 'code'
            - `file_type` string, required
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - AudioChunkGeneratedMetadata
            - `type` 'audio'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `sample_rate` integer, nullable
            - `channels` integer, nullable
            - `audio_format` integer, nullable
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - VideoChunkGeneratedMetadata
            - `type` 'video'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `fps` number, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `frame_count` integer, nullable
            - `has_audio_stream` boolean
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - ImageChunkGeneratedMetadata
            - `type` 'image'
            - `file_type` string
            - `file_size` integer, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
        - `model` string, nullable — model used for this chunk
        - `score` number, required — score of the chunk
        - `file_id` string, required — file id
        - `filename` string, required — filename
        - `store_id` string, required — store id
        - `external_id` string, nullable — external identifier for this file
        - `metadata` unknown
        - `type` 'audio_url' — Input type identifier
        - `transcription` string, nullable — speech recognition (sr) text of the audio
        - `context` string, nullable — LLM-generated context that situates this audio chunk within its source file
        - `summary` string, nullable — summary of the audio
        - `audio_url` AudioUrl — Model for audio URL validation.
          - `url` string, required — The audio URL. Can be either a URL or a Data URI.
        - `sampling_rate` integer, required — The sampling rate of the audio.
      - MxbaiOmniCoreStoreModelsChunkTypesScoredVideoUrlInputChunk
        - `chunk_index` integer, required — position of the chunk in a file
        - `mime_type` string — mime type of the chunk
        - `generated_metadata` union — metadata of the chunk
          - MarkdownChunkGeneratedMetadata
            - `type` 'markdown'
            - `file_type` 'text/markdown'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `chunk_headings` MarkdownHeading[]
              - …
            - `heading_context` MarkdownHeading[]
              - …
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
            - `frontmatter` object
          - TextChunkGeneratedMetadata
            - `type` 'text'
            - `file_type` 'text/plain' | 'message/rfc822'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - PDFChunkGeneratedMetadata
            - `type` 'pdf'
            - `file_type` 'application/pdf'
            - `total_pages` integer, nullable
            - `total_size` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
          - CodeChunkGeneratedMetadata
            - `type` 'code'
            - `file_type` string, required
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - AudioChunkGeneratedMetadata
            - `type` 'audio'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `sample_rate` integer, nullable
            - `channels` integer, nullable
            - `audio_format` integer, nullable
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - VideoChunkGeneratedMetadata
            - `type` 'video'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `fps` number, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `frame_count` integer, nullable
            - `has_audio_stream` boolean
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - ImageChunkGeneratedMetadata
            - `type` 'image'
            - `file_type` string
            - `file_size` integer, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
        - `model` string, nullable — model used for this chunk
        - `score` number, required — score of the chunk
        - `file_id` string, required — file id
        - `filename` string, required — filename
        - `store_id` string, required — store id
        - `external_id` string, nullable — external identifier for this file
        - `metadata` unknown
        - `type` 'video_url' — Input type identifier
        - `transcription` string, nullable — speech recognition (sr) text of the video
        - `context` string, nullable — LLM-generated context that situates this video chunk within its source file
        - `summary` string, nullable — summary of the video
        - `video_url` VideoUrl — Model for video URL validation.
          - `url` string, required — The video URL. Can be either a URL or a Data URI.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/mixedbread/apis/mxbai-omni.md) · [All operations](https://skmtc.net/mixedbread/apis/mxbai-omni/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixedbread/mxbai-omni/revisions/6dac6bb49f72/schema)