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.

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 the search as a server-sent event stream: live agentic-search trace events when the search is agentic, and nothing before the results otherwise. 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."
    }
  ]
}

Changes

Changed in 7 of the 30 revisions of this API.4112

Sep 15, 2026957bf8ec8df844See the full diff
- ▲
  added to the //// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the //// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the //// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the //// response property oneOf list for the response status
  response-property-one-of-added
- ○
  added csv discriminator mapping keys to the //// response property for the response status
  response-property-discriminator-mapping-added
- ○
  added csv discriminator mapping keys to the //// response property for the response status
  response-property-discriminator-mapping-added
- ○
  added csv discriminator mapping keys to the //// response property for the response status
  response-property-discriminator-mapping-added
- ○
  added csv discriminator mapping keys to the //// response property for the response status
  response-property-discriminator-mapping-added
Sep 8, 2026ce403656bc181See the full diff
- ●
  the request property's max was set to 10000.00
  request-property-max-set
This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 29, 2026b4acfee365751See the full diff
- ○
  added the new optional request property /
  new-optional-request-property
Aug 20, 202642cbb70e72181See the full diff
- ○
  added the media type text/event-stream for the response with the status
  response-media-type-added
Aug 19, 2026f66774ddecfc1See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Aug 14, 2026e5ddc69af9411See the full diff
- ○
  added the new optional header request parameter X-Mxbai-Tool-Ticket
  new-optional-request-parameter
Jul 26, 2026587cbdf607b04See the full diff
- ○
  the request property default value changed from mixedbread-ai/mxbai-rerank-v3-listwise to mixedbread-ai/mxbai-rerank-v3.1-listwise
  request-property-default-value-changed
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history