Sign in
sync

Create R2 Sync

Create a Cloudflare R2 Sync for a collection and start the initial backfill. The endpoint is derived from account_id and jurisdiction. Returns the sync; indexing runs asynchronously.

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

Path parameters

collection_namestring required

Destination collection.

Headers

authorizationstring nullable

Bearer {api_key}. Your Captain API key.

Request body

bucketstring required

Cloudflare R2 bucket to keep in sync with the collection.

prefixstring

Key prefix to scope the sync. Empty syncs the whole bucket.

account_idstring required

Cloudflare account ID (from the R2 dashboard URL). Determines the endpoint.

access_key_idstring required

R2 S3 API token access key ID.

secret_access_keystring required

R2 S3 API token secret access key. Stored securely, never returned.

jurisdiction'default' | 'eu' | 'fedramp'

R2 jurisdiction; selects the endpoint.

processing_type'advanced' | 'basic' required

Parsing tier.

include_patternsstring[]

Glob patterns; only matching keys are synced.

exclude_patternsstring[]

Glob patterns; matching keys are excluded.

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

How to propagate objects removed from the source: 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.

custom_metadataobject

Static metadata applied to every synced document.

sync_interval_minutesinteger nullable

Scheduled reconcile cadence (minimum 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