Query Collection | Captain Docs

Execute a natural language query against a collection.

When inference=true, returns an AI-generated response with relevant documents. When inference=false, returns raw search results with content and metadata.

Streaming (SSE)

When stream: true and inference: true, the response is a Server-Sent Events stream. Every data: field is a JSON object with a type discriminator.

SSE Event Types

`type` value	Schema	Description
`text.delta`	`QueryStreamTextEvent`	Incremental text chunk of the AI response.
`tool.start`	`QueryStreamToolStartEvent`	The agent is performing a knowledge-base search.
`tool.end`	`QueryStreamToolEndEvent`	A tool call completed. `tool_call_id` correlates with the preceding `tool.start`.
`stream_complete`	`QueryStreamCompleteEvent`	Stream finished successfully. Close the connection.
`stream_error`	`QueryStreamErrorEvent`	An error occurred. Close the connection.

Example SSE Stream

data: {"type":"tool.start","seq":1,"run_id":"run_abc","tool_call_id":"tc_1","name":"searchKnowledgeBase","args":{"query":"revenue projections Q4"}}
data: {"type":"tool.end","seq":2,"run_id":"run_abc","tool_call_id":"tc_1","name":"searchKnowledgeBase","ok":true,"result_summary":{"resultCount":12}}
data: {"type":"text.delta","seq":3,"run_id":"run_abc","data":"Based on the documents"}
data: {"type":"text.delta","seq":4,"run_id":"run_abc","data":" provided, the revenue"}
data: {"type":"text.delta","seq":5,"run_id":"run_abc","data":" projections for Q4 show"}
data: {"type":"text.delta","seq":6,"run_id":"run_abc","data":" a 15% increase over Q3."}
data: {"type":"stream_complete","metadata":{"totalResults":12,"totalSearches":1},"stats":{"totalTokens":150}}

Notes

The agent may perform multiple searches per query. Each search produces a tool.start / tool.end pair.
Text chunks are interleaved between tool events - text arrives after the agent has gathered results from a search.
Connect with Accept: text/event-stream and set a generous timeout (120s+) for long responses.

Bounding Box Data

Set include_bbox: true (inference=false only) to receive element-level layout coordinates for each search result. Each result will include a layout object with normalized bounding box blocks for PDF and DOCX files.

Each block contains:

type: element type (text, title, section_header, list_item, table, figure, key_value, header, footer)
content: the text content
page: page number
bbox: normalized 0-1 coordinates { top, left, width, height } relative to page dimensions
confidence: extraction confidence (high/low) when available
image_url: presigned URL for figure/chart images when available

Files without OCR data (TXT, CSV, images) will have layout: null.

Execute a natural language query against a collection. When `inference=true`, returns an AI-generated response with relevant documents. When `inference=false`, returns raw search results with content and metadata. ## Streaming (SSE) When `stream: true` and `inference: true`, the response is a Server-Sent Events stream. Every `data:` field is a JSON object with a `type` discriminator. ### SSE Event Types | `type` value | Schema | Description | |---|---|---| | `text.delta` | `QueryStreamTextEvent` | Incremental text chunk of the AI response. | | `tool.start` | `QueryStreamToolStartEvent` | The agent is performing a knowledge-base search. | | `tool.end` | `QueryStreamToolEndEvent` | A tool call completed. `tool_call_id` correlates with the preceding `tool.start`. | | `stream_complete` | `QueryStreamCompleteEvent` | Stream finished successfully. Close the connection. | | `stream_error` | `QueryStreamErrorEvent` | An error occurred. Close the connection. | ### Example SSE Stream ``` data: {"type":"tool.start","seq":1,"run_id":"run_abc","tool_call_id":"tc_1","name":"searchKnowledgeBase","args":{"query":"revenue projections Q4"}} data: {"type":"tool.end","seq":2,"run_id":"run_abc","tool_call_id":"tc_1","name":"searchKnowledgeBase","ok":true,"result_summary":{"resultCount":12}} data: {"type":"text.delta","seq":3,"run_id":"run_abc","data":"Based on the documents"} data: {"type":"text.delta","seq":4,"run_id":"run_abc","data":" provided, the revenue"} data: {"type":"text.delta","seq":5,"run_id":"run_abc","data":" projections for Q4 show"} data: {"type":"text.delta","seq":6,"run_id":"run_abc","data":" a 15% increase over Q3."} data: {"type":"stream_complete","metadata":{"totalResults":12,"totalSearches":1},"stats":{"totalTokens":150}} ``` ### Notes - The agent may perform multiple searches per query. Each search produces a `tool.start` / `tool.end` pair. - Text chunks are interleaved between tool events - text arrives after the agent has gathered results from a search. - Connect with `Accept: text/event-stream` and set a generous timeout (120s+) for long responses. ## Bounding Box Data Set `include_bbox: true` (inference=false only) to receive element-level layout coordinates for each search result. Each result will include a `layout` object with normalized bounding box blocks for PDF and DOCX files. Each block contains: - `type`: element type (text, title, section_header, list_item, table, figure, key_value, header, footer) - `content`: the text content - `page`: page number - `bbox`: normalized 0-1 coordinates `{ top, left, width, height }` relative to page dimensions - `confidence`: extraction confidence (high/low) when available - `image_url`: presigned URL for figure/chart images when available Files without OCR data (TXT, CSV, images) will have `layout: null`.

Authentication

AuthorizationBearer

Bearer token authentication using API key

Path parameters

collection_namestringRequired

Request

This endpoint expects an object.

querystringRequired

The natural language query to search for

inferencebooleanOptionalDefaults to false

Enable LLM-generated answers based on the relevant sections retrieved. When false, returns raw search results.

streambooleanOptionalDefaults to false

Enable real-time streaming of the response

top_kintegerOptionalDefaults to 10

Number of results to return. Only valid when inference=false. Not supported when inference=true (the agent controls its own search strategy).

rerankbooleanOptionalDefaults to false

Enable reranking for improved relevance ordering. Uses Gemini Flash 2.5 by default, or Voyage AI rerank-2.5 as fallback. Adds ~100-300ms latency.

metadata_filtermap from strings to anyOptional

Filter expression for vector search. Supports: $eq,$ ne, $gt,$ gte, $lt,$ lte, $in,$ nin, $and,$ or

custom_promptstringOptional

Custom system prompt to override the default RAG prompt when inference=true. Allows customizing how the LLM processes and responds to the query with the retrieved context.

include_bboxbooleanOptionalDefaults to false

Include normalized bounding box layout data for each search result. Returns element-level positions (titles, paragraphs, tables, figures, form fields) with page coordinates for PDF and DOCX files. Only supported with inference=false.

search_resultsbooleanOptionalDefaults to false

When inference=true, include the raw search result chunks that were used as context for the LLM response. Defaults to false. Always true when inference=false.

Response

Successful Response - returns JSON when stream: false, or SSE event stream when stream: true.

successboolean

Whether the query was successful

summarystring

AI-generated summary/response (when inference=true)

responsestring

Alias for summary (v1 compatibility)

inferenceboolean

Whether inference mode was used

search_resultslist of objects

Search results with chunk content, scores, and source URIs. Returned for both inference=true (the chunks used as context) and inference=false (raw search results).

total_resultsinteger

Total number of search results found

top_kinteger

Number of results returned

querystring

The original query

tokens_usedmap from strings to integers

Token usage breakdown by category

execution_time_msinteger

Query execution time in milliseconds

request_idstring

Unique request identifier (used for streaming)

streamingobject

Streaming configuration (when stream=true)

token_balanceobject

Current token balance after this request

Execute a natural language query against a collection.

When inference=true, returns an AI-generated response with relevant documents. When inference=false, returns raw search results with content and metadata.

Streaming (SSE)

When stream: true and inference: true, the response is a Server-Sent Events stream. Every data: field is a JSON object with a type discriminator.

SSE Event Types

`type` value	Schema	Description
`text.delta`	`QueryStreamTextEvent`	Incremental text chunk of the AI response.
`tool.start`	`QueryStreamToolStartEvent`	The agent is performing a knowledge-base search.
`tool.end`	`QueryStreamToolEndEvent`	A tool call completed. `tool_call_id` correlates with the preceding `tool.start`.
`stream_complete`	`QueryStreamCompleteEvent`	Stream finished successfully. Close the connection.
`stream_error`	`QueryStreamErrorEvent`	An error occurred. Close the connection.

Example SSE Stream

data: {"type":"tool.start","seq":1,"run_id":"run_abc","tool_call_id":"tc_1","name":"searchKnowledgeBase","args":{"query":"revenue projections Q4"}}
data: {"type":"tool.end","seq":2,"run_id":"run_abc","tool_call_id":"tc_1","name":"searchKnowledgeBase","ok":true,"result_summary":{"resultCount":12}}
data: {"type":"text.delta","seq":3,"run_id":"run_abc","data":"Based on the documents"}
data: {"type":"text.delta","seq":4,"run_id":"run_abc","data":" provided, the revenue"}
data: {"type":"text.delta","seq":5,"run_id":"run_abc","data":" projections for Q4 show"}
data: {"type":"text.delta","seq":6,"run_id":"run_abc","data":" a 15% increase over Q3."}
data: {"type":"stream_complete","metadata":{"totalResults":12,"totalSearches":1},"stats":{"totalTokens":150}}

Notes

The agent may perform multiple searches per query. Each search produces a tool.start / tool.end pair.
Text chunks are interleaved between tool events - text arrives after the agent has gathered results from a search.
Connect with Accept: text/event-stream and set a generous timeout (120s+) for long responses.

Bounding Box Data

Each block contains:

type: element type (text, title, section_header, list_item, table, figure, key_value, header, footer)
content: the text content
page: page number
bbox: normalized 0-1 coordinates { top, left, width, height } relative to page dimensions
confidence: extraction confidence (high/low) when available
image_url: presigned URL for figure/chart images when available

Files without OCR data (TXT, CSV, images) will have layout: null.

1	import requests
2	import uuid
3	import json
4
5	BASE_URL = "https://api.runcaptain.com"
6	API_KEY = "your_api_key"
7
8	headers = {
9	"Authorization": f"Bearer {API_KEY}",
10	"Content-Type": "application/json",
11	"Idempotency-Key": str(uuid.uuid4())
12	}
13
14	response = requests.post(
15	f"{BASE_URL}/v2/collections/my_documents/query",
16	headers=headers,
17	json={
18	"query": "What are the key terms in the contract?",
19	"inference": False,
20	"stream": False,
21	"rerank": True,
22	"top_k": 10,
23	"include_bbox": False
24	},
25	timeout=120.0
26	)
27
28	print(json.dumps(response.json(), indent=2))

1	{
2	"success": true,
3	"summary": "Based on the contract, the key terms include payment schedules, termination clauses, confidentiality obligations, and liability limitations.",
4	"response": "Based on the contract, the key terms include payment schedules, termination clauses, confidentiality obligations, and liability limitations.",
5	"inference": true,
6	"search_results": [
7	{
8	"score": 0.92,
9	"content": "The contract shall commence on the Effective Date and continue for a period of twelve (12) months. Either party may terminate this Agreement with thirty (30) days written notice. The Contractor shall,",
10	"document_id": "doc_abc123",
11	"filename": "contract.pdf",
12	"uri": "s3://my-company-docs/contracts/contract.pdf",
13	"chunk_index": 3,
14	"page_start": 2,
15	"page_end": 2
16	}
17	],
18	"total_results": 1,
19	"query": "What are the key terms in the contract?"
20	}

Streaming (SSE)

SSE Event Types

Example SSE Stream

Notes

Bounding Box Data

Authentication

Path parameters

Headers

Request

Response

Streaming (SSE)

SSE Event Types

Example SSE Stream

Notes

Bounding Box Data