Create S3 Sync | Captain Docs

import requests
BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}
response = requests.post(
    f"{BASE_URL}/v2/collections/company-knowledge/sync/s3",
    headers=headers,
    json={
        "bucket": "my-company-docs",
        "prefix": "knowledge-base/",
        "region": "us-east-1",
        "auth": {
            "type": "assume_role",
            "role_arn": "arn:aws:iam::123456789012:role/captain-s3-read",
            "external_id": "captain-abc123"
        },
        "processing_type": "advanced",
        "include_patterns": [
            "*.pdf",
            "*.docx"
        ],
        "exclude_patterns": [
            "drafts/*"
        ],
        "deletion_policy": "mirror",
        "custom_metadata": {
            "team": "research",
            "source": "s3"
        },
        "sync_interval_minutes": 15
    }
)
print(response.json())

{
  "sync_id": "sync_7e0abee6e110457db2c8",
  "collection_name": "company-knowledge",
  "bucket": "my-company-docs",
  "prefix": "knowledge-base/",
  "region": "us-east-1",
  "auth_method": "iam_role",
  "processing_type": "advanced",
  "include_patterns": [
    "*.pdf",
    "*.docx"
  ],
  "exclude_patterns": [
    "drafts/*"
  ],
  "deletion_policy": "mirror",
  "status": "active",
  "secret_set": false,
  "sns_subscribe_url": null,
  "last_backfill_job_id": "91f2aa031d8f4e7d8877c4564eb486bd-1786120498",
  "last_reconcile_at": null,
  "sync_interval_minutes": 15,
  "next_sync_at": 1786120589056,
  "sync_state": "idle",
  "last_sync_at": null,
  "last_sync_error": null,
  "created_at": "2026-08-07T16:34:58.188233+00:00",
  "updated_at": "2026-08-07T16:34:58.612676+00:00"
}

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.

Path parameters

collection_namestringRequired

Destination collection.

Request

This endpoint expects an object.

bucketstringRequired

Bucket to keep in sync with the collection.

authobjectRequired

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

processing_typeenumRequired

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

prefixstringOptionalDefaults to

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

regionstringOptionalDefaults to us-east-1

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_typeenumOptionalDefaults to s3

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.

include_patternslist of stringsOptional

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

exclude_patternslist of stringsOptional

Glob patterns; matching keys are excluded.

deletion_policyenumOptionalDefaults to mirror

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_mappingmap from strings to strings or nullOptional

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

custom_metadatamap from strings to anyOptional

Static metadata applied to every synced document.

sync_interval_minutesinteger or nullOptional

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_idstringOptional

collection_namestringOptional

bucketstringOptional

prefixstringOptional

regionstringOptional

storage_typeenumOptional

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

auth_methodenumOptional

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).

account_namestring or nullOptional

Azure Blob syncs only: the storage account name. Null for other providers.

endpoint_urlstring or nullOptional

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_typeenumOptional

include_patternslist of stringsOptional

exclude_patternslist of stringsOptional

deletion_policyenumOptional

statusenumOptional

secret_setbooleanOptional

True once an event-webhook secret has been minted.

sns_subscribe_urlstring or nullOptional

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

last_backfill_job_idstring or nullOptional

last_reconcile_atstring or nullOptional

sync_interval_minutesinteger or nullOptional

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

next_sync_atinteger or nullOptional

Epoch ms of the next due scheduled reconcile.

sync_stateenum or nullOptional

last_sync_atinteger or nullOptional

last_sync_errorstring or nullOptional

created_atstringOptional

updated_atstring or nullOptional

Path parameters

Headers

Request

Response