Index GCS File | Captain Docs

Index a single file from a GCS bucket into a collection. Returns a job_id for tracking progress.

Authentication

AuthorizationBearer

Bearer token authentication using API key

Path parameters

collection_namestringRequired

Request

This endpoint expects an object.

bucket_namestringRequired

Name of the GCS bucket

file_uristringRequired

GCS URI format: gs://bucket-name/path/to/file.pdf

service_account_jsonstringRequired

GCP service account JSON key with read access to the bucket

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.

Allowed values:

custom_metadatamap from strings to anyOptional

Custom metadata to attach to all chunks from this file. Keys must be strings. Values: str, int, float, bool, or array of strings.

parsing_scriptstringOptional

Relative path to a JavaScript parsing script for JSON files (e.g. ‘research/paper-parser’). When provided, .json files are processed through a sandboxed V8 isolate that executes the script to extract text and metadata. Without this parameter, .json files are indexed as raw text. Scripts are org-scoped and managed in the Parser Studio.

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.

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.

Response

Indexing Job Started

job_idstring

statusenum

Allowed values:

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	with open("service-account.json") as f:
12	sa_json = f.read()
13
14	response = requests.post(
15	f"{BASE_URL}/v2/collections/my_documents/index/gcs/file",
16	headers=headers,
17	json={
18	"bucket_name": "my-gcs-documents",
19	"file_uri": "gs://my-gcs-documents/reports/annual-review.pdf",
20	"service_account_json": sa_json,
21	"processing_type": "advanced"
22	},
23	timeout=60.0
24	)
25
26	if response.status_code in [200, 201]:
27	data = response.json()
28	print(f"Job started! ID: {data['job_id']}")
29	else:
30	print(f"Error: {response.status_code}")

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

Authentication

Path parameters

Headers

Request

Response