Query - v2 (Legacy) | Captain Docs

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

collection_namestringRequired

This endpoint expects an object.

querystringRequired

Natural-language search query.

top_kinteger or nullOptionalDefaults to 10

Maximum number of search results to return.

metadata_filtermap from strings to any or nullOptional

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

rerankboolean or nullOptionalDefaults to false

Enable reranking for text-only collections. Multimodal collections always rerank and return a warning if rerank=false is ignored.

include_bboxboolean or nullOptionalDefaults to false

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

Successful Response

successboolean

querystring

search_resultslist of objects

total_resultsinteger

top_kinteger

warningslist of strings or null

tokens_usedmap from strings to integers or null

execution_time_msinteger or null

request_idstring or null

token_balanceobject or null

1	import json
2	import requests
3	import uuid
4
5	BASE_URL = "https://api.runcaptain.com"
6	API_KEY = "your_api_key"
7	COLLECTION_NAME = "my_documents"
8
9	headers = {
10	"Authorization": f"Bearer {API_KEY}",
11	"Content-Type": "application/json",
12	"Idempotency-Key": str(uuid.uuid4()),
13	}
14
15	response = requests.post(
16	f"{BASE_URL}/v2/collections/{COLLECTION_NAME}/query",
17	headers=headers,
18	json={
19	"query": "payment authorization requirements",
20	"top_k": 10,
21	"rerank": True,
22	"metadata_filter": {
23	"document_type": {"$eq": "policy"}
24	},
25	},
26	timeout=120.0,
27	)
28
29	print(json.dumps(response.json(), indent=2))