sync

Create S3 Sync

Create a Sync for a collection and start the initial backfill. AWS S3 authenticates with cross-account assume-role (recommended) or an access key. Works across S3-compatible cloud storage: AWS S3, Google Cloud Storage, Cloudflare R2, Supabase Storage, and Backblaze B2 (each has its own create endpoint). Returns the sync; indexing runs asynchronously.

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

Path parameters

collection_namestring required

Destination collection.

Headers

authorizationstring nullable

Bearer {api_key}. Your Captain API key.

Request body

bucketstring required

Bucket to keep in sync with the collection.

prefixstring

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

regionstring

Region of the bucket (AWS region for S3, or the provider's region, e.g. 'auto' for R2, 'us-west-004' for Backblaze B2).

storage_type's3' | 'r2' | 'supabase' | 'backblaze'

Cloud storage type. 's3' = AWS S3 (assume-role or access-key). 'r2'/'supabase'/'backblaze' are S3-compatible and require access-key auth with an endpoint_url.

authS3SyncCreateRequestDocsAuth required

Auth for reading the bucket: assume-role (AWS S3) or access-key (S3 or S3-compatible). Non-S3 stores require access-key auth.

processing_type'advanced' | 'basic' required

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

include_patternsstring[]

Glob patterns; only matching keys are synced. Empty includes everything under the prefix.

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.

metadata_mappingobject nullable

Maps an S3 object tag/key to a Captain metadata field name.

custom_metadataobject

Static metadata applied to every synced document.

sync_interval_minutesinteger nullable

Scheduled reconcile cadence. MINIMUM 5 minutes (the scheduler ticks every 5 min); values below 5 are silently raised to 5; >=5 honored exactly. null/omitted = manual (events + on-demand only). For sub-5-min propagation use the event webhook.

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

No recorded changes to this endpoint across all 2 revisions of this API.