For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Index uploaded files into a collection.
Upload one or more files directly via multipart form-data. Supports PDF, DOCX,
XLSX, CSV, TXT, images, and other document types. Files are processed through
the same pipeline as cloud storage indexing.
Headers:
- Authorization: Bearer {api_key} - Captain API key for authentication
- X-Organization-ID: Organization UUID
- Idempotency-Key: UUID for request deduplication (optional)
Args:
collection_name: Name of the collection (path parameter)
files: One or more files to upload and index
processing_type: "advanced" or "basic" (default: "basic")
custom_metadata: JSON string of custom metadata (optional)
Returns:
{ job_id, status: "pending" }
Path parameters
collection_namestringRequired
Headers
authorizationstring or nullOptional
Request
This endpoint expects a multipart form with multiple files.
custom_metadatastring or nullOptional
JSON string of custom metadata to attach to all indexed chunks.
filesfilesRequired
One or more files to index (max 20). Supported: PDF, DOCX, XLSX, CSV, TXT, MD, JSON, YAML, PNG, JPG, GIF, BMP, TIFF, WEBP, MP4, MOV, AVI, MKV, WEBM, MP3, WAV, AAC, FLAC, M4A, OGG.
overwrite_existingbooleanOptionalDefaults to false
When true, files that already exist in the collection are re-indexed and replaced with zero downtime: the new version is built alongside the live one and atomically swapped in when complete, so the previous version keeps serving search results throughout the rebuild. The document keeps the same document_id across overwrites, and its status reads 'updating' in the document listing while the rebuild runs. Requires skip_existing=false. Setting both to true returns a 400 error.
processing_typestringOptionalDefaults to basic
Document processing type: ‘advanced’ for AI-enhanced extraction (tables, figures, charts), ‘basic’ for standard processing.
skip_existingbooleanOptionalDefaults to true
When true, files already indexed in the collection are skipped and will not be re-indexed with incoming changes. When false, all incoming files are indexed regardless of whether they already exist.
transcription_languagestring or nullOptional
AWS Transcribe language code for the spoken audio (e.g. 'es-US', 'pt-BR'). Omit to auto-detect per file. Video and audio files only. Supported codes: https://docs.aws.amazon.com/transcribe/latest/dg/supported-languages.html
mask_piibooleanOptionalDefaults to false
When true, mask detected PII in the parsed content before it is embedded and stored.
pii_engineenumOptionalDefaults to kev
Masking engine for this job. `kev` (default): the Kev classifier model on Captain's infrastructure; supports `pii_fields` and `pii_instructions`; no fallback, so a file kev cannot mask fails to index and the rest of the job continues. `jev`: TypeSafe's hosted Jev model, slightly more accurate, best-effort availability; supports custom fields and instructions and may list fallbacks in `pii_fallback`. `presidio`: the legacy pattern engine, built-in categories only (rejects `pii_fields` or `pii_instructions` with 422), never a fallback. Requires `mask_pii: true`. The earlier names `captain-jev` and `captain-presidio` keep working as before; new requests should use `kev`, `jev` or `presidio`.
Allowed values:
pii_fallbackobject or booleanOptional
Ordered fallback engines for `jev`, as `{"engines": [...], "retry_budget_seconds": n}`. Omitted or an empty `engines` list means no fallback. Only valid with `pii_engine: "jev"`; with `kev` or `presidio` a non-empty list answers 422. On the multipart file upload endpoint, send it as a JSON string form field. With the earlier engine name `captain-jev` it is `true` (default, fall back to `captain-presidio`) or `false`.
pii_fieldsstring or nullOptional
JSON string of additional PII categories to mask, an array of objects with name, description and optional examples (the same shape as pii_fields on the JSON indexing endpoints). Requires mask_pii to be true.
pii_instructionsstring or nullOptional<=1000 characters
Plain-language guidance that steers what counts as personal data for this job. Requires mask_pii to be true. Up to 1,000 characters.
Response
Successful Response
job_idstring
statusstringOptionalDefaults to pending
custom_metadatamap from strings to any or nullOptional
The custom_metadata Captain accepted for this job, echoed back as validated. Null when none was supplied.
Errors
400
Bad Request Error
Index uploaded files into a collection.
Upload one or more files directly via multipart form-data. Supports PDF, DOCX,
XLSX, CSV, TXT, images, and other document types. Files are processed through
the same pipeline as cloud storage indexing.
Headers:
Authorization: Bearer {api_key} - Captain API key for authentication
X-Organization-ID: Organization UUID
Idempotency-Key: UUID for request deduplication (optional)
Args:
collection_name: Name of the collection (path parameter)
files: One or more files to upload and index
processing_type: “advanced” or “basic” (default: “basic”)
custom_metadata: JSON string of custom metadata (optional)
Returns:
{ job_id, status: “pending” }
When true, files that already exist in the collection are re-indexed and replaced with zero downtime: the new version is built alongside the live one and atomically swapped in when complete, so the previous version keeps serving search results throughout the rebuild. The document keeps the same document_id across overwrites, and its status reads ‘updating’ in the document listing while the rebuild runs. Requires skip_existing=false. Setting both to true returns a 400 error.
Masking engine for this job. kev (default): the Kev classifier model on Captain’s infrastructure; supports pii_fields and pii_instructions; no fallback, so a file kev cannot mask fails to index and the rest of the job continues. jev: TypeSafe’s hosted Jev model, slightly more accurate, best-effort availability; supports custom fields and instructions and may list fallbacks in pii_fallback. presidio: the legacy pattern engine, built-in categories only (rejects pii_fields or pii_instructions with 422), never a fallback. Requires mask_pii: true. The earlier names captain-jev and captain-presidio keep working as before; new requests should use kev, jev or presidio.
Ordered fallback engines for jev, as {"engines": [...], "retry_budget_seconds": n}. Omitted or an empty engines list means no fallback. Only valid with pii_engine: "jev"; with kev or presidio a non-empty list answers 422. On the multipart file upload endpoint, send it as a JSON string form field. With the earlier engine name captain-jev it is true (default, fall back to captain-presidio) or false.
