Index File | Captain Docs

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” }

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

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.

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

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

Response

Successful Response

job_idstring

statusstringOptionalDefaults to pending

Errors

400

Bad Request Error

Index uploaded files into a collection.

Headers:

Authorization: Bearer {api_key} - Captain API key for authentication
X-Organization-ID: Organization UUID
Idempotency-Key: UUID for request deduplication (optional)

Returns: { job_id, status: “pending” }

1	import json
2	import requests
3	import uuid
4
5	BASE_URL = "https://api.runcaptain.com"
6	API_KEY = "your_api_key"
7	COLLECTION_NAME = "my_documents"
8
9	headers = {
10	"Authorization": f"Bearer {API_KEY}",
11	"Idempotency-Key": str(uuid.uuid4()),
12	}
13
14	response = requests.post(
15	f"{BASE_URL}/v2/collections/{COLLECTION_NAME}/index/file",
16	headers=headers,
17	timeout=120.0
18	)
19
20	print(json.dumps(response.json(), indent=2))

1	{
2	"job_id": "c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8-1783111727",
3	"status": "pending"
4	}