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

# Update Sync

PATCH https://api.captain.dev/v2/syncs/{sync_id}
Content-Type: application/json

Update a sync's prefix, glob filters, deletion policy, cadence, custom metadata, or status (pause/resume). Only provided fields change.

Reference: https://docs.captain.dev/reference/sync/manage/update

## Request

### Path parameters

- `sync_id` (string, required) — The sync id.

### Headers

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

### Body (application/json)

This endpoint expects a S3SyncUpdateRequestDocs.

- `prefix` (string, optional) — New key prefix to scope the sync.
- `include_patterns` (list of string, optional) — Replacement include glob patterns.
- `exclude_patterns` (list of string, optional) — Replacement exclude glob patterns.
- `deletion_policy` (enum, optional) — New deletion-propagation policy.
  - Allowed values: `mirror`, `archive`, `ignore`
- `status` (enum, optional) — 'paused' stops syncing without deleting the sync; 'active' resumes.
  - Allowed values: `active`, `paused`
- `custom_metadata` (map from string to any, optional) — Replacement static metadata.
- `sync_interval_minutes` (integer, optional, nullable) — New cadence in minutes. MINIMUM 5 (below 5 clamps to 5; >=5 honored exactly). null = manual. Read the sync back for the effective value.
- `account_key` (string, optional, nullable) — Azure Blob syncs only: a new storage-account key (key1 or key2). Validated against the container before it replaces the stored key: the supported path for Azure key rotation. Rejected with 422 on non-Azure syncs. Never returned.

## Response

### 200

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
{
  "prefix": "knowledge-base/2024/",
  "include_patterns": [
    "*.pdf",
    "*.docx"
  ],
  "exclude_patterns": [
    "drafts/*"
  ],
  "deletion_policy": "mirror",
  "status": "active",
  "custom_metadata": {
    "team": "research"
  },
  "sync_interval_minutes": 30
}
```

**Response**

```json
{
  "sync_id": "sync_7e0abee6e110457db2c8",
  "collection_name": "company-knowledge",
  "bucket": "my-company-docs",
  "prefix": "knowledge-base/2024/",
  "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": 30,
  "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.captain.dev"
API_KEY = "your_api_key"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.patch(
    f"{BASE_URL}/v2/syncs/sync_7e0abee6e110457db2c8",
    headers=headers,
    json={
        "prefix": "knowledge-base/2024/",
        "include_patterns": [
            "*.pdf",
            "*.docx"
        ],
        "exclude_patterns": [
            "drafts/*"
        ],
        "deletion_policy": "mirror",
        "status": "active",
        "custom_metadata": {
            "team": "research"
        },
        "sync_interval_minutes": 30
    }
)

print(response.json())
```

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

const response = await fetch(
    `${BASE_URL}/v2/syncs/{sync_id}`,
    {
        method: "PATCH",
        headers: {
            "Authorization": `Bearer ${API_KEY}`,
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            prefix: "knowledge-base/2024/",
            include_patterns: ["*.pdf", "*.docx"],
            exclude_patterns: ["drafts/*"],
            deletion_policy: "mirror",
            status: "active",
            custom_metadata: {
                team: "research"
            },
            sync_interval_minutes: 30
        })
    }
);

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