Index URL | Captain Docs

Index documents from public URL(s) into a collection.

Accepts either a single url string or a urls array of strings. Documents are downloaded from the provided URLs and processed through the same pipeline as cloud storage indexing.

Supported formats: PDF, TXT, DOCX, CSV, XLSX, and other document types.

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) body: URL configuration with url or urls

Returns: { job_id, status: “pending” }

Index documents from public URL(s) into a collection. Accepts either a single `url` string or a `urls` array of strings. Documents are downloaded from the provided URLs and processed through the same pipeline as cloud storage indexing. Supported formats: PDF, TXT, DOCX, CSV, XLSX, and other document types. 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) body: URL configuration with url or urls Returns: { job_id, status: "pending" }

Path parameters

collection_namestringRequired

Request

This endpoint expects an object.

processing_typeenumRequired

Document processing type. ‘advanced’ uses agentic OCR with AI-enhanced extraction for complex layouts, tables, figures, charts, and documents containing images. ‘basic’ provides reliable OCR optimized for general document indexing and high-volume processing.

custom_metadatamap from strings to strings or integers or doubles or booleans or lists of strings or nullOptional

Custom metadata to attach to all indexed chunks. Keys must be strings. Values: str, int, float, bool, or List[str].

parsing_scriptstring or nullOptional

Relative path to a JS parsing script for JSON files (e.g. ‘research/paper-parser’). When provided, .json files are processed through a sandboxed V8 isolate. Without this, .json files are indexed as raw text.

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

urlstring or nullOptional

A single public URL to a hosted document. Supported types: PDF, DOCX, DOC, XLSX, XLS, CSV, TSV, TXT, MD, JSON, YAML, YML, PNG, JPG, JPEG, GIF, BMP, TIFF. Provide either ‘url’ or ‘urls’, not both.

urlslist of strings or nullOptional

A list of public URLs to hosted documents. Provide either 'url' or 'urls', not both.

mask_piibooleanOptionalDefaults to false

When true, detected PII (emails, phone numbers, SSNs, credit cards, names, and locations) is masked in the parsed content before it is embedded and stored — replaced with entity tags like <PERSON> and <EMAIL_ADDRESS>. For images (including images embedded in PDFs), PII text visible in the image is also pixel-redacted. Opt-in; defaults to false, which leaves content unchanged.

Response

Successful Response

job_idstring

statusstringOptionalDefaults to pending

1	import requests
2
3	BASE_URL = "https://api.runcaptain.com"
4	API_KEY = "your_api_key"
5
6	headers = {
7	"Authorization": f"Bearer {API_KEY}",
8	"Content-Type": "application/json"
9	}
10
11	response = requests.post(
12	f"{BASE_URL}/v2/collections/my_documents/index/url",
13	headers=headers,
14	json={
15	"url": "https://example.com/documents/report.pdf",
16	"processing_type": "advanced"
17	},
18	timeout=60.0
19	)
20
21	if response.status_code in [200, 201]:
22	data = response.json()
23	print(f"Job started! ID: {data['job_id']}")
24	else:
25	print(f"Error: {response.status_code}")

1	{
2	"job_id": "job_url_abc123",
3	"status": "pending"
4	}