File Search API

Captain File Search retrieves source chunks from indexed files. Use v3 for new applications. It has cleaner response fields, explicit include controls, document inspection, chunk metadata, and graph relations.

v2 remains available for existing clients. It keeps search_results and content so older code does not break.

Query With v3

1
import requests
2
3
BASE_URL = "https://api.runcaptain.com"
4
API_KEY = "your_api_key"
5
COLLECTION = "medical_claims"
6
7
response = requests.post(
8
    f"{BASE_URL}/v3/collections/{COLLECTION}/query",
9
    headers={
10
        "Authorization": f"Bearer {API_KEY}",
11
        "Content-Type": "application/json",
12
    },
13
    json={
14
        "query": "What evidence supports the safety claim?",
15
        "limit": 10,
16
        "rerank": True,
17
        "include": {
18
            "document": True,
19
            "metadata": True,
20
            "regions": False,
21
            "relations": True,
22
            "related_chunks": True
23
        }
24
    },
25
    timeout=120.0,
26
)
27
28
data = response.json()
29
for result in data["results"]:
30
    print(result["document"]["filename"], result["score"])
31
    print(result["text"])

See the v3 Query endpoint for the full request and response schema.

Response Shape

v3 returns results, and each result uses text for chunk text.

1
{
2
  "query": "What evidence supports the safety claim?",
3
  "results": [
4
    {
5
      "chunk_id": "chk_abc123_004",
6
      "text": "Patients receiving therapy reported no treatment-related serious adverse events.",
7
      "score": 0.92,
8
      "document": {
9
        "id": "doc_abc123",
10
        "filename": "study-summary.pdf",
11
        "source": null
12
      },
13
      "metadata": {
14
        "review_state": "approved"
15
      },
16
      "custom_metadata": {
17
        "claim_type": "safety"
18
      },
19
      "relations": [],
20
      "related_chunks": []
21
    }
22
  ],
23
  "total_results": 1,
24
  "limit": 10
25
}

Use Advanced Search & Relations for metadata filters, chunk custom_metadata, region data, relations, and relation-aware queries.

Documents and Chunks

Use document and chunk endpoints when your application needs stable source objects outside the search response:

• Get Document: inspect a document and its chunks.
• List Chunks: page through chunks in a document.
• Get Chunk: fetch one chunk by ID.

These endpoints are useful for citations, review flows, and source-grounded UI state.

v2 Compatibility

Existing v2 clients should continue using v2 Query. v2 keeps the old field names:

1
{
2
  "search_results": [
3
    {
4
      "content": "Patients receiving therapy reported no treatment-related serious adverse events."
5
    }
6
  ]
7
}

Do not document v3 behavior as v2 behavior. v2 does not return v3 fields such as results, text, custom_metadata, relations, or related_chunks.