---
title: "Search a Collection"
method: POST
path: "/v3/collections/search"
tags: ["Collections"]
---

# Search a Collection

`POST /v3/collections/search`

Run a vector/keyword search against a collection and return the raw retrieval hits
(distinct, best match first). Uses the same retrieval as an enrich step — `semantic`,
`hybrid` (weighted Reciprocal Rank Fusion), or `exact` — but does NOT apply the LLM
re-rank that a full enrich step layers on top.

## Request body

- SearchCollectionRequestV3 — Request to search a collection directly (vector/keyword retrieval).
  - `collectionName` string, required — The name/path of the collection to search. Must use only letters, digits, underscores, and dots. Each segment must start with a letter or underscore.
  - `query` string, required — The text to search with.
  - `topK` integer — Number of distinct results to return (default 1).
  - `searchMode` 'semantic' | 'exact' | 'hybrid' — Search mode: - `semantic` (default): dense-vector cosine similarity (matches on meaning). - `exact`: case-insensitive substring keyword match. - `hybrid`: weighted Reciprocal Rank Fusion of the semantic and keyword rankings.
  - `includeScore` boolean — Include the retrieval score on each result.
  - `includeSubcollections` boolean — Also search child collections under `collectionName`.
  - `scoreThreshold` number, double — Drops results whose score exceeds this value — a 0–2 dissimilarity cutoff (lower = closer), applied to `semantic` and `hybrid` modes exactly as an enrich step's `scoreThreshold` does. Ignored for `exact` mode. Omit for no threshold filtering (all topK returned); pass 0.6 to mirror the enrich default.
  - `rerank` boolean — Apply the same LLM re-rank an enrich step performs over the retrieved candidates. Ignored for `exact` mode (which is never re-ranked). Off by default; enabling it adds an LLM call per request. When on, each result carries `rank`/`confidence`.

## Response `200`

The request has succeeded.

- SearchCollectionResponseV3 — Collection search results, distinct and best match first. By default these are the raw retrieval hits and the LLM re-rank an enrich step applies is NOT run; when the request sets `rerank: true`, the results are LLM-re-ranked (each carries `rank`/`confidence`).
  - `collectionName` string, required — The collection that was searched.
  - `searchMode` string, required — The resolved search mode (`semantic`, `exact`, or `hybrid`).
  - `results` SearchCollectionResultV3[], required — Matching items, best match first.
    - `data` union, required — The matched item's stored data.
      - string
      - object
    - `score` number, double — The retrieval score (0.0–2.0, lower is closer/better). Present only when `includeScore` is set. `scoreType` names which score it is. Mirrors the rerank / enrich output shape.
    - `scoreType` 'cosineDistance' | 'hybridScore' — Which score `score` is: `cosineDistance` for `semantic` mode, or `hybridScore` for `hybrid` mode (Reciprocal Rank Fusion mapped onto the same 0–2 dissimilarity scale).
    - `rank` integer — 1-based LLM re-rank position (best first). Present only when `rerank` is set.
    - `confidence` number, double — The LLM's 0–1 confidence for a re-ranked match. Present only when `rerank` is set, and omitted for backfilled entries the LLM did not rank (order those by score, not confidence).
    - `reasoning` string — The LLM's justification for a re-ranked match, when it provided one.

## Other responses

- `400` — The server could not understand the request due to invalid syntax.
- `404` — The server cannot find the requested resource.

---

[API](https://skmtc.dev/bem-team/apis/bem-api.md) · [All operations](https://skmtc.dev/bem-team/apis/bem-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bem-team/bem-api/revisions/a6e4624117c6/schema)