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 will be deleted and re-indexed with the latest changes. 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.

Response

Successful Response

job_idstring

statusstringDefaults 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))