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

# Create Azure Sync

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

Create an Azure Blob Storage Sync for a collection and start the initial backfill. Azure authenticates with the storage account's name and account key (stored securely, never returned), so there is no region, endpoint_url, or assume-role; the container is echoed back as `bucket`. Returns the sync; indexing runs asynchronously.

Reference: https://docs.captain.dev/reference/sync/azure/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 an AzureSyncCreateRequestDocs.

- `container` (string, required) — Azure Blob container to keep in sync with the collection (3-63 chars, lowercase letters, digits, single hyphens). Echoed as `bucket` in sync responses.
- `account_name` (string, required) — Azure storage account name (the `<account>` in https\://\<account>.blob.core.windows.net; 3-24 lowercase letters and digits).
- `account_key` (string, required) — Storage account access key (key1 or key2) with read access to the container. Stored securely, never returned. Rotate later with PATCH /v2/syncs/\{sync\_id}.
- `processing_type` (enum, required) — Parsing tier. 'advanced' = full document understanding; 'basic' = faster/cheaper.
  - Allowed values: `advanced`, `basic`, `auto`
- `prefix` (string, optional, default: ) — Object-name prefix to scope the sync (e.g. 'docs/2024/'). Empty syncs the whole bucket.
- `include_patterns` (list of string, optional) — Glob patterns; only matching blob names are synced.
- `exclude_patterns` (list of string, optional) — Glob patterns; matching blob names are excluded.
- `deletion_policy` (enum, optional, default: mirror) — How to propagate blobs removed from Azure: `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`
- `metadata_mapping` (map from string to string, optional, nullable) — Maps an Azure blob metadata key to a Captain metadata field name.
- `custom_metadata` (AzureSyncCreateRequestDocsCustomMetadata, optional, nullable) — Static metadata applied to every synced document.
- `sync_interval_minutes` (integer, optional, nullable, default: 60) — Scheduled reconcile cadence in minutes (minimum 5; below 5 clamps to 5). Defaults to 60 for Azure so reconcile backstops any missed Event Grid delivery; null = manual (no scheduled reconcile).

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

## Types

### AzureSyncCreateRequestDocsCustomMetadata

Static metadata applied to every synced document.

## Examples

**Request**

```json
{
  "container": "policy-documents",
  "account_name": "contosodocs",
  "account_key": "<storage account key1 or key2>",
  "processing_type": "advanced",
  "prefix": "docs/",
  "include_patterns": [
    "*.pdf",
    "*.docx"
  ],
  "exclude_patterns": [
    "drafts/*"
  ],
  "deletion_policy": "mirror",
  "custom_metadata": {
    "team": "research",
    "source": "azure"
  },
  "sync_interval_minutes": 60
}
```

**Response**

```json
{
  "sync_id": "sync_7e0abee6e110457db2c8",
  "collection_name": "company-knowledge",
  "bucket": "policy-documents",
  "prefix": "docs/",
  "region": "",
  "storage_type": "azure",
  "auth_method": "account_key",
  "account_name": "contosodocs",
  "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": 60,
  "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"
}

payload = {
    "container": "policy-documents",
    "account_name": "contosodocs",
    "account_key": "<storage account key1 or key2>",
    "prefix": "docs/",
    "processing_type": "advanced",
    "deletion_policy": "mirror",
    "sync_interval_minutes": 60
}

resp = requests.post(
    f"{BASE_URL}/v2/collections/company-knowledge/sync/azure",
    headers=headers,
    json=payload,
)
print(resp.json())

```

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

const resp = await fetch(
  `${BASE_URL}/v2/collections/company-knowledge/sync/azure`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      container: "policy-documents",
      account_name: "contosodocs",
      account_key: "<storage account key1 or key2>",
      prefix: "docs/",
      processing_type: "advanced",
      deletion_policy: "mirror",
      sync_interval_minutes: 60,
    }),
  },
);
console.log(await resp.json());

```