Query - v2 (Legacy) | Captain Docs

import requests
import uuid
import json
BASE_URL = "https://api.runcaptain.com"
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.",
      "chunk_id": "chk_abc123_003",
      "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"
}

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.

rerankboolean or nullOptionalDefaults to false

Enable reranking. Multimodal collections default to reranking; pass false to opt out and a warning is returned noting reduced cross-modal ranking quality. Text-only collections use the value as sent. Adds roughly 200 ms.

include_bboxboolean or nullOptionalDefaults to false

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

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

token_balanceobject or nullOptional