Sign in
sync

Create GCS Sync

Create a Google Cloud Storage Sync for a collection and start the initial backfill. GCS authenticates with a service-account JSON (stored in Secrets Manager, never returned), so there is no region, endpoint_url, or access-key pair. Returns the sync; indexing runs asynchronously.

post/v2/collections/{collection_name}/sync/gcs

Path parameters

collection_namestring required

Destination collection.

Headers

authorizationstring nullable

Bearer {api_key}. Your Captain API key.

Request body

bucketstring required

GCS bucket to keep in sync with the collection.

prefixstring

Object-name prefix to scope the sync (e.g. 'docs/2024/'). Empty syncs the whole bucket.

service_account_jsonstring required

Google service-account key JSON (type='service_account') with read access to the bucket (roles/storage.objectViewer). Stored securely in Secrets Manager, never returned.

processing_type'advanced' | 'basic' required

Parsing tier. 'advanced' = full document understanding; 'basic' = faster/cheaper.

include_patternsstring[]

Glob patterns; only matching object names are synced.

exclude_patternsstring[]

Glob patterns; matching object names are excluded.

deletion_policy'mirror' | 'archive' | 'ignore'

How to propagate objects removed from GCS: mirror removes them from the collection so they no longer appear in search; archive keeps the document's content but marks it archived, excluded from search by default and surfaced with include_archived: true; ignore leaves the indexed copy in place.

metadata_mappingobject nullable

Maps a GCS object metadata key to a Captain metadata field name.

custom_metadataGcsSyncCreateRequestDocsCustomMetadata

Static metadata applied to every synced document.

sync_interval_minutesinteger nullable

Scheduled reconcile cadence in minutes (minimum 5; below 5 clamps to 5; null = manual).

Response

Successful Response

sync_idstring
collection_namestring
bucketstring
prefixstring
regionstring
storage_type's3' | 'gcs' | 'r2' | 'supabase' | 'backblaze'

The sync's cloud storage type. Returned by the list endpoint (GET /v2/syncs) only; other sync endpoints omit this field.

auth_method'iam_role' | 'access_key' | 'service_account'

How the sync authenticates to the bucket: 'iam_role' (AWS cross-account assume-role), 'access_key' (S3-compatible key pair), or 'service_account' (GCS service-account JSON).

endpoint_urlstring nullable

S3-compatible endpoint URL (access-key syncs on non-AWS providers); null for AWS S3. Returned by the list endpoint (GET /v2/syncs) only; other sync endpoints omit this field.

processing_type'advanced' | 'basic'
include_patternsstring[]
exclude_patternsstring[]
deletion_policy'mirror' | 'archive' | 'ignore'
status'active' | 'paused' | 'inactive'
secret_setboolean

True once an event-webhook secret has been minted.

sns_subscribe_urlstring nullable

SNS subscribe URL; only surfaced by the subscribe-webhook endpoint.

last_backfill_job_idstring nullable
last_reconcile_atstring nullable
sync_interval_minutesinteger nullable

Effective (already-clamped) cadence; null = manual.

next_sync_atinteger nullable

Epoch ms of the next due scheduled reconcile.

sync_state'idle' | 'running' | 'error'
last_sync_atinteger nullable
last_sync_errorstring nullable
created_atstring
updated_atstring nullable

Changes