--- title: "Enhance a search query" method: POST path: "/v1/stores/queries/enhance" tags: ["stores"] --- # Enhance a search query `POST /v1/stores/queries/enhance` 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` 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. - `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 - `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 --- [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/2eece97b5ae5/schema)