Changelog

• Cap one document’s share of the page: max_chunks_per_document on the v3 Query request stops a single long file from occupying every result slot. Surplus chunks drop and the page backfills with the next best chunks from other documents; ranking is unchanged, only the page composition is.
• Ask for the top documents: top_documents: N adds a top_documents array to the response, ranking documents by their best chunk across the whole ranked pool. Each group carries the stable document_id (usable with Get Document and stable across re-indexing), filename, best score, pool chunk_count, and chunk references that resolve into results. The flat results list is unaffected. See Return the Top Documents.
• Jobs report a terminal stage: a finished job’s progress.current_stage now ends at completed, failed, or cancelled instead of sitting on finalizing forever, and per-file stage values end at completed (indexed or skipped; the file’s status carries which) or failed. A job whose files all failed now says Job failed rather than Job completed.

• Azure Blob Storage joins the sync providers: POST /v2/collections/{collection_name}/sync/azure keeps an Azure container synced with a collection. Authenticate with the storage account’s name and access key (container + account_name + account_key; the key is stored securely, never returned, and rotates in place via PATCH /v2/syncs/{sync_id} with an account_key field). Reconciliation defaults to a 60-minute cadence, and real-time events arrive through an Event Grid subscription: one click with the Deploy to Azure template, or one az eventgrid event-subscription create: the setup guide shows both. The template is self-verifying: the deployment only goes green when Event Grid proves delivery to Captain and Captain confirms the webhook enrollment.

• Your query history, from the API: GET /v2/queries lists the queries your keys and agents have run, newest first, scoped to the calling key’s environment, with collection, status, from/to and sort filters and cursor paging. GET /v2/queries/{query_id} returns one query with its request body, response body and the retrieved chunks in one normalised shape across v2 and v3. Add include=results,request,response to the list to get feed and previews in one request; the body fields are always present and null unless requested. Bodies are archived 90 days after the query (body_status: archived); summaries are kept.
• Query responses now carry query_id: every POST .../query response (v2 and v3) returns the id of its history row, so you can fetch it back with GET /v2/queries/{query_id} straight away. The request_id a query response returns is accepted on that endpoint too.

• Two new reranker options: rerank.model on v3 Query and v2 Query now accepts voyage-rerank-3 (alias rerank-3) and gemini-3.8-flash alongside the existing voyage-rerank-2.5 (default) and gemini-2.5-flash. Voyage models are fast cross-encoders; the Gemini models are LLM rerankers with a higher quality ceiling on complex queries at higher latency — pair them with small candidate pools. The family aliases voyage and gemini keep resolving to each family’s default, so existing requests are unchanged, and the response’s rerank envelope keeps reporting the model that actually ran.

• Collection copies now include chunk relations and chunk metadata: fixed a bug where POST /v2/collections/{name}/copy cloned documents and vectors but left the graph behind. A copied collection had no relations, and its chunk metadata matched search filters but never appeared on the metadata read endpoint. Copies now carry both. Captain rewrites each relation’s document pointer to the new collection’s own document ids, so a copy keeps resolving after you delete the source. The response reports relations_copied, chunk_metadata_copied, and relations_unresolved, and include_graph: false skips the graph if you only want documents and vectors.

• Tune the keyword/semantic balance: semantic_ratio on v2 and v3 Query (0.0 to 1.0, default 0.5) weights the fused result set: 0.0 is keyword only, 1.0 is semantic only. See Advanced Search & Relations.

Same day: MCP Guide, Metadata Boosts, Mint Asset URLs, Supported File Types Guide, YouTube Audio & Video Modes

• MCP has its own guide: the hosted server, all 48 tools, and client configs for Claude Code, Cursor, VS Code, and Windsurf now live at MCP Server. OpenClaw and Hermes keep their page under Integrations.

• Rank by your own metadata, not just filter by it: v3 Query accepts an optional boost array. Each clause retrieves chunks matching one of your custom_metadata keys and multiplies their retrieval score by a weight between 0.2 and 5.0. Use it when a chunk is the right answer but does not share wording with the query: a reviewer marked it, a curated tag applies, or your application already cited it. Send no boost and retrieval is unchanged.
• Soft by default, guaranteed when you ask: with reranking on, boosts decide which chunks the reranker considers and the reranker still decides the final order. Set reserve on a clause to guarantee its best matches a place on the page.
• Every boost explains itself: each clause is echoed with matched, in_pool, and on_page counts; boosted results carry a boost record with the multiplier and the rank they held beforehand, and report metadata in match_sources. See Advanced Search & Relations.

• Fetch figure crops on demand: Mint Asset URLs takes the figure_ids from a document’s regions and returns short-lived signed image URLs. Batch up to 100, set ttl_seconds (default 900), and each id degrades on its own.

• Supported file types guide: documents, text, images, video, and audio formats with their extensions, at Supported File Types. File Size Limits keeps the size ceilings.

• Index the video, not just the captions: Index YouTube now takes a mode parameter. transcript (the default, unchanged and staying that way) indexes the caption track as text. audio pulls the audio track through the multimodal audio pipeline, billed at 5 credits per minute. video pulls the video itself for frame descriptions plus transcription, billed at 20 credits per minute.
• Captionless videos can fall back instead of failing: set on_missing_transcript to audio or video and a video with no captions is indexed through that media pipeline instead of failing the file. Because the fallback changes what you are billed, it is never silent: Get Job Status returns a per-video youtube array with mode_used, fell_back_from, transcript_available, and languages.
• youtube.com/live/ URLs are now accepted alongside the existing watch, youtu.be, shorts, embed, and /v/ shapes. Duplicate videos in one request are deduplicated, live streams are refused, and media over 4 hours is rejected before any processing starts.

• Unreliable chart extractions no longer reach your results: when the parser cannot verify that it read a figure accurately (dense multi-panel charts are the main case), Captain now withholds that figure’s extracted text instead of indexing numbers that may be wrong. Nothing is inserted in its place: surrounding text, captions, and tables are untouched, and search results simply never contain unverified chart data.
• Machine-detectable, still renderable: the withheld figure surfaces as a region with extraction: "unavailable", text: null, an intact bounding box, and a working image_url, so your UI can render the real figure and decide how to present the omission. Regions with extraction null or absent are included content as always.
• Verified charts keep their data: figures whose extraction was verified against the source image continue to return their structured data.

• Tune reranking per request: rerank on v3 Query and v2 Query now also accepts an object, {"enabled": true, "candidate_limit": 50, "model": "voyage-rerank-2.5"}. Pick the reranker (voyage-rerank-2.5, default, or gemini-2.5-flash), and size the candidate pool that gets reranked before your top limit returns (default limit × 3, must be ≥ limit, capped at 200). Booleans keep working unchanged, and the v3 response’s rerank envelope now reports the model and candidate_limit that ran.

• Every parsed chunk now carries a layout role: v3 query results, document chunks, and related chunks include a first-class chunk_type field classified from the parser’s block structure at indexing time. The closed set of values is body, table, heading, page_header, page_footer, footnote, and figure. chunk_type is null for unlabeled content: anything indexed before this shipped, plain-text and media files, and regions the parser returned without block structure.
• Keep page furniture out of retrieval: pass exclude_chunk_types on v3 Query (for example ["page_header", "page_footer", "footnote"]) and matching chunks are excluded at retrieval time, before reranking, combined with filter when both are sent. Chunks with a null label always pass, so existing collections behave exactly as before. Unknown values return a 400 listing the allowed set, and excluding body adds a warning since body is a document’s primary text. The response always echoes exclude_chunk_types.
• Reserved key: chunk_type is now reserved; writing it through custom_metadata is rejected on every write surface.
• Applies to newly indexed documents: labels are written at indexing time, so re-index a document to pick them up. See Advanced Search & Relations for the full semantics.

• Four compliance entities: mask_pii now detects US_NMLS_ID, US_SURETY_BOND_NUMBER, SURETY_COMPANY, and SURETY_BOND_PRINCIPAL. Entities are label-anchored, so loan numbers, NAIC codes, and amounts on the same form stay readable. See PII Masking.

• MCP gains captain_copy_collection and captain_change_environment: clone a collection, or move one between environments, from any MCP client. API keys are environment-scoped, so a moved collection leaves the old environment’s keys behind. See MCP Server.

Same day: Document Metadata Endpoints, Image Dimension Limits, Neighboring Chunks, Page-Level Retrieval

• Replace or merge a document’s metadata: PUT and PATCH on /v3/collections/{collection_name}/documents/{document_id}/metadata write custom metadata after indexing, and the v3 documents list accepts metadata_filter to look documents up by that metadata.

• Image dimension limits: images index up to 200 megapixels, with or without mask_pii; an oversized image fails as a per-file error on the job record without blocking the batch. See File Size Limits.

• Read past a cut-off chunk without a second query: set include.neighboring_chunks: true on v3 Query and each result carries the chunk immediately before and after it in the source file, under neighboring_chunks.prev and neighboring_chunks.next. prev is null for the first chunk in a document, next is null for the last. See Advanced Search & Relations.
• Off by default: the base query response is unchanged unless include.neighboring_chunks is set.

• Fetch one page of a document: GET /v3/collections/{collection_name}/documents/{document_id}/pages/{page_number} returns the chunks, text, and regions of a single page, next to Get Document in the v3 reference.