---
title: "Enhance a search query"
method: POST
path: "/v1/stores/queries/enhance"
tags: ["stores"]
---

# Enhance a search query

`POST /v1/stores/queries/enhance`

## Request

- Base URL: `https://api.mixedbread.com`
- URL: `https://api.mixedbread.com/v1/stores/queries/enhance`
- Auth: HTTP bearer

Extract metadata filters and ranking preferences from a search query.

## Request body

- QueryEnhanceParams: Parameters for enhancing a search query.
  - `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` union: Optional list of file IDs to filter chunks by (inclusion filter)
    - unknown[]
      - unknown
    - string[]
  - `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 agent fills the final ranking to top_k chunks from what it retrieved, capped at top_k, instead of returning only the chunks it judged relevant
        - `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.
    - `lsf` boolean, nullable: Whether to apply the learned scoring function to second-stage scoring. Requires weights configured for the searched stores; silently skipped otherwise.
    - `return_metadata` boolean: Whether to return file metadata
  - `instructions` string, nullable: Optional guidance for query enhancement.

## Response `200`

A single enhanced query item

- QueryEnhanceResults: Enhanced query response.
  - `items` union[], required: Enhanced query item
    - union
      - QueryEnhanceQueryItem: Enhanced semantic search query with optional filters.
        - `type` 'query'
        - `query` string, required: Search query text
        - `metadata_filters` QueryEnhanceMetadataFilter[], nullable: Metadata filters to apply
          - `key` string, required: Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required: Operator for a filter condition.
          - `value` union, required: Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any': How to combine filters
        - `rank_by` unknown
        - `direction` unknown
      - QueryEnhanceSortItem: Ranking request based on metadata.
        - `type` 'sort'
        - `metadata_filters` QueryEnhanceMetadataFilter[], nullable: Metadata filters to apply
          - `key` string, required: Metadata field key
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required: Operator for a filter condition.
          - `value` union, required: Value to compare against. Use a list for `in`/`not_in`.
            - string
            - integer
            - number
            - boolean
            - union[]
              - …
        - `filter_mode` 'all' | 'any': How to combine filters
        - `rank_by` string, required: Metadata field to rank results by
        - `direction` 'asc' | 'desc', required: Ranking direction

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-03** `da24b4f7e983`: 1 warning
  - removed the request property `search_options/apply_search_rules`
- **2026-10-31** `9179fec93d29`: 1 info
  - request property `search_options/apply_search_rules` deprecated
- **2026-09-08** `ce403656bc18`: 1 warning
  - the `top_k` request property's max was set to `10000.00`
- **2026-08-29** `b4acfee36575`: 1 info
  - added the new optional request property `search_options/lsf`
- **2026-08-20** `42cbb70e7218`: 1 warning
  - removed the request property `stream`

[Operation history](https://skmtc.dev/mixedbread/apis/mxbai-omni/changes/v1/stores/queries/enhance/post.md)

---

[API](https://skmtc.dev/mixedbread/apis/mxbai-omni.md) - [All operations](https://skmtc.dev/mixedbread/apis/mxbai-omni/llms.txt) - [OpenAPI document](https://skmtc.dev/mixedbread/apis/mxbai-omni/revisions/da24b4f7e983?raw)