> For a complete page index of the Captain API documentation, fetch https://docs.filesearch.dev/llms.txt?excludeSpec=true

# Create Supabase Sync

POST https://api.filesearch.dev/v2/collections/{collection_name}/sync/supabase
Content-Type: application/json

Create a Supabase Storage Sync for a collection and start the initial backfill. Returns the sync; indexing runs asynchronously.

Reference: https://docs.filesearch.dev/reference/sync/supabase/create

## Request

### Path parameters

- `collection_name` (string, required) — Destination collection.

### Headers

- `authorization` (string, optional, nullable) — Bearer \{api\_key}. Your Captain API key.

### Body (application/json)

This endpoint expects a SupabaseSyncCreateRequestDocs.

- `bucket` (string, required) — Supabase Storage bucket to keep in sync with the collection.
- `endpoint_url` (string, required) — Supabase S3 endpoint, e.g. https://PROJECT_REF.storage.supabase.co/storage/v1/s3
- `access_key_id` (string, required) — Supabase S3 access key ID.
- `secret_access_key` (string, required) — Supabase S3 secret access key. Stored securely, never returned.
- `processing_type` (enum, required) — Parsing tier.
  - Allowed values: `advanced`, `basic`, `auto`
- `prefix` (string, optional, default: ) — Key prefix to scope the sync. Empty syncs the whole bucket.
- `region` (string, optional, default: us-east-1) — Region for the S3 protocol.
- `include_patterns` (list of string, optional) — Glob patterns; only matching keys are synced.
- `exclude_patterns` (list of string, optional) — Glob patterns; matching keys are excluded.
- `deletion_policy` (enum, optional, default: 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.
  - Allowed values: `mirror`, `archive`, `ignore`
- `custom_metadata` (map from string to any, optional) — Static metadata applied to every synced document.
- `sync_interval_minutes` (integer, optional, nullable) — Scheduled reconcile cadence (minimum 5; null = manual).

## Response

### 201

Successful Response

- `sync_id` (string, optional)
- `collection_name` (string, optional)
- `bucket` (string, optional)
- `prefix` (string, optional)
- `region` (string, optional)
- `storage_type` (enum, optional) — The sync's cloud storage type. Returned by the list endpoint (GET /v2/syncs) only; other sync endpoints omit this field.
  - Allowed values: `s3`, `gcs`, `r2`, `supabase`, `backblaze`, `azure`
- `auth_method` (enum, optional) — 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).
  - Allowed values: `iam_role`, `access_key`, `service_account`, `account_key`
- `account_name` (string, optional, nullable) — Azure Blob syncs only: the storage account name. Null for other providers.
- `endpoint_url` (string, optional, 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` (enum, optional)
  - Allowed values: `advanced`, `basic`, `auto`
- `include_patterns` (list of string, optional)
- `exclude_patterns` (list of string, optional)
- `deletion_policy` (enum, optional)
  - Allowed values: `mirror`, `archive`, `ignore`
- `status` (enum, optional)
  - Allowed values: `active`, `paused`, `inactive`
- `secret_set` (boolean, optional) — True once an event-webhook secret has been minted.
- `sns_subscribe_url` (string, optional, nullable) — SNS subscribe URL; only surfaced by the subscribe-webhook endpoint.
- `last_backfill_job_id` (string, optional, nullable)
- `last_reconcile_at` (string, optional, nullable)
- `sync_interval_minutes` (integer, optional, nullable) — Effective (already-clamped) cadence; null = manual.
- `next_sync_at` (integer, optional, nullable) — Epoch ms of the next due scheduled reconcile.
- `sync_state` (enum, optional, nullable)
  - Allowed values: `idle`, `running`, `error`
- `last_sync_at` (integer, optional, nullable)
- `last_sync_error` (string, optional, nullable)
- `created_at` (string, optional)
- `updated_at` (string, optional, nullable)

## Examples

**Request**

```json
{
  "bucket": "my-bucket",
  "endpoint_url": "https://PROJECT_REF.storage.supabase.co/storage/v1/s3",
  "access_key_id": "your-key-id",
  "secret_access_key": "your-secret",
  "processing_type": "advanced",
  "prefix": "docs/",
  "region": "us-east-1",
  "include_patterns": [
    "*.pdf",
    "*.docx"
  ],
  "exclude_patterns": [
    "drafts/*"
  ],
  "deletion_policy": "mirror",
  "custom_metadata": {
    "team": "research",
    "source": "supabase"
  },
  "sync_interval_minutes": 15
}
```

**Response**

```json
{
  "sync_id": "sync_7e0abee6e110457db2c8",
  "collection_name": "company-knowledge",
  "bucket": "my-bucket",
  "prefix": "docs/",
  "region": "us-east-1",
  "auth_method": "access_key",
  "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"
}
```

**SDK Code**

```python Python REST
import requests

BASE_URL = "https://api.filesearch.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/supabase",
    headers=headers,
    json={
        "bucket": "my-bucket",
        "prefix": "docs/",
        "endpoint_url": "https://PROJECT_REF.storage.supabase.co/storage/v1/s3",
        "region": "us-east-1",
        "access_key_id": "your-key-id",
        "secret_access_key": "your-secret",
        "processing_type": "advanced",
        "include_patterns": [
            "*.pdf",
            "*.docx"
        ],
        "exclude_patterns": [
            "drafts/*"
        ],
        "deletion_policy": "mirror",
        "custom_metadata": {
            "team": "research",
            "source": "supabase"
        },
        "sync_interval_minutes": 15
    }
)

print(response.json())
```

```typescript TypeScript REST
const BASE_URL = "https://api.filesearch.dev";
const API_KEY = "your_api_key";

const response = await fetch(
    `${BASE_URL}/v2/collections/company-knowledge/sync/supabase`,
    {
        method: "POST",
        headers: {
            "Authorization": `Bearer ${API_KEY}`,
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            bucket: "my-bucket",
            prefix: "docs/",
            endpoint_url: "https://PROJECT_REF.storage.supabase.co/storage/v1/s3",
            region: "us-east-1",
            access_key_id: "your-key-id",
            secret_access_key: "your-secret",
            processing_type: "advanced",
            include_patterns: ["*.pdf", "*.docx"],
            exclude_patterns: ["drafts/*"],
            deletion_policy: "mirror",
            custom_metadata: {
                team: "research",
                source: "supabase"
            },
            sync_interval_minutes: 15
        })
    }
);

const data = await response.json();
console.log(data);
```