Sign in
stores

Perform semantic search across store chunks

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

post/v1/stores/search

Headers

X-Mxbai-Tool-Ticketstring 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.

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

top_kinteger

Number of results to return

file_idsstring[] nullable

Optional list of file IDs to filter chunks by (inclusion filter)

streamboolean

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].

Example request

{
  "filters": {
    "all": [
      {
        "key": "price",
        "operator": "gt",
        "value": "100"
      },
      {
        "key": "color",
        "operator": "eq",
        "value": "red"
      }
    ],
    "any": [
      {
        "key": "price",
        "operator": "gt",
        "value": "100"
      },
      {
        "key": "color",
        "operator": "eq",
        "value": "red"
      }
    ],
    "none": [
      {
        "key": "price",
        "operator": "gt",
        "value": "100"
      },
      {
        "key": "color",
        "operator": "eq",
        "value": "red"
      }
    ]
  },
  "file_ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "123e4567-e89b-12d3-a456-426614174001"
  ],
  "query": "This is a sample text input.",
  "search_options": {
    "rerank": {
      "model": "rerank_model",
      "top_k": 10
    }
  }
}

Response

List of semantically similar chunks with relevance scores and pagination details

object'list'

The object type of the response

Example response

{
  "data": [
    {
      "mime_type": "text/plain",
      "model": "text-embedding-ada-002",
      "score": 0.5,
      "file_id": "file1",
      "filename": "file1",
      "store_id": "store1",
      "external_id": "ext-123",
      "metadata": {
        "key": "value"
      },
      "context": "This chunk is from an SEC filing on ACME corp's Q2 2023 performance.",
      "summary": "A short overview of ACME's Q2 2023 performance."
    }
  ]
}