Skip to navigation
File SearchIndexingLocal File(s)

Index File

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, ‘auto’ to inspect each PDF and use advanced only when it has photos, drawings, tables or scanned pages (logos and signatures do not count).

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