Query - v2 (Legacy) | Captain Docs

import requests
import uuid
import json
BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"
COLLECTION_NAME = "my_documents"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Idempotency-Key": str(uuid.uuid4()),
}
response = requests.post(
    f"{BASE_URL}/v2/collections/{COLLECTION_NAME}/query",
    headers=headers,
    json={
        "query": "What are the key terms in the contract?",
        "top_k": 10,
        "rerank": True,
    },
    timeout=120.0,
)
print(json.dumps(response.json(), indent=2))

{
  "success": true,
  "query": "What are the key terms in the contract?",
  "search_results": [
    {
      "score": 0.92,
      "content": "The contract shall commence on the Effective Date and continue for a period of twelve (12) months.",
      "document_id": "doc_abc123",
      "filename": "contract.pdf",
      "uri": "s3://my-company-docs/contracts/contract.pdf",
      "chunk_index": 3,
      "metadata": {
        "pageStart": 2,
        "pageEnd": 2
      },
      "rerank_score": 0.98
    }
  ],
  "total_results": 1,
  "top_k": 10,
  "warnings": [],
  "tokens_used": {
    "search": 28
  },
  "execution_time_ms": 245,
  "request_id": "req_abc123",
  "query_id": "019a0e2a-7b31-7c4e-9d2f-3a8c1e5b6f90"
}

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

Path parameters

collection_namestringRequired

Request

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.

include_archivedbooleanOptionalDefaults to false

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

rerankboolean or object or nullOptionalDefaults to false

Rerank retrieved candidates before returning the top results (adds roughly 200 ms). Boolean form uses the defaults: voyage-rerank-2.5 over a pool of limit x 3 candidates. Object form tunes reranking — see RerankOptions. Multimodal collections default to reranking; an explicit false (or {"enabled": false}) opts out and returns a warning noting reduced cross-modal ranking quality. On v2, the deprecated inference=true path honours only the enabled/disabled state; the tuning fields apply to retrieval queries.

include_bboxboolean or nullOptionalDefaults to false

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

semantic_ratiodoubleOptional0-1Defaults to 0.5

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

querystring

search_resultslist of objects

total_resultsinteger

top_kinteger

warningslist of strings or nullOptional

tokens_usedmap from strings to integers or nullOptional

execution_time_msinteger or nullOptional

request_idstring or nullOptional

query_idstring or nullOptional

Id of this query in your history. Fetch it back with GET /v2/queries/{query_id}. Present when the query was stored (completed, non-streamed queries).

token_balanceobject or nullOptional