query

Query Collection

Execute the v2 File Search endpoint against a collection. Returns retrieved chunks in search_results with content fields.

post/v2/collections/{collection_name}/query

Path parameters

collection_namestring required

Request body

querystring required

Natural-language search query.

top_kinteger nullable

Maximum number of search results to return.

metadata_filterobject nullable

Filter expression for indexed document metadata. Supports $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $and, and $or.

include_archivedboolean

Include chunks archived by a sync archive deletion policy. Archived content is excluded from search by default; set true to surface it.

include_bboxboolean nullable

Legacy v2 layout option retained for clients that already depend on bounding boxes.

semantic_rationumber double

Balance between semantic and keyword retrieval. Captain searches both ways at once: keyword (sparse, BM25) matches the words in the query, semantic (dense vector) matches its meaning. 0.0 is keyword only, 1.0 is semantic only, and 0.5 (the default) weighs them equally. Lower it for corpora full of exact terms such as part numbers or error codes; raise it when callers phrase questions in their own words. Between the endpoints both searches run, so a result found only by the down-weighted side still appears, just lower. The endpoints skip the other search entirely: 0.0 also skips embedding the query, making it the fastest option, though queries using boost and collections holding images, video, or audio keep vector search running. See the Advanced Querying guide for more.

Response

Successful Response

successboolean required

querystring required

total_resultsinteger required

top_kinteger required

warningsstring[] nullable

tokens_usedobject nullable

execution_time_msinteger nullable

request_idstring nullable

Changes

No recorded changes to this endpoint across all 1 revision of this API.