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

# Create GCS Sync

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

Create a Google Cloud Storage Sync for a collection and start the initial backfill. GCS authenticates with a service-account JSON (stored in Secrets Manager, never returned), so there is no region, endpoint_url, or access-key pair. Returns the sync; indexing runs asynchronously.

Reference: https://docs.filesearch.dev/reference/sync/gcs/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 GCSSyncCreateRequestDocs.

- `bucket` (string, required) — GCS bucket to keep in sync with the collection.
- `service_account_json` (string, required) — Google service-account key JSON (type='service_account') with read access to the bucket (roles/storage.objectViewer). Stored securely in Secrets Manager, never returned.
- `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 object names are synced.
- `exclude_patterns` (list of string, optional) — Glob patterns; matching object names are excluded.
- `deletion_policy` (enum, optional, default: mirror) — How to propagate objects removed from GCS: `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 a GCS object metadata key to a Captain metadata field name.
- `custom_metadata` (GcsSyncCreateRequestDocsCustomMetadata, optional, nullable) — Static metadata applied to every synced document.
- `sync_interval_minutes` (integer, optional, nullable) — Scheduled reconcile cadence in minutes (minimum 5; below 5 clamps to 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)

## Types

### GcsSyncCreateRequestDocsCustomMetadata

Static metadata applied to every synced document.

## Examples

**Request**

```json
{
  "bucket": "my-bucket",
  "service_account_json": "{\"type\": \"service_account\", \"project_id\": \"my-project\", \"private_key_id\": \"...\", \"private_key\": \"-----BEGIN PRIVATE KEY-----\\n...\", \"client_email\": \"captain-reader@my-project.iam.gserviceaccount.com\"}",
  "processing_type": "advanced",
  "prefix": "docs/",
  "include_patterns": [
    "*.pdf",
    "*.docx"
  ],
  "exclude_patterns": [
    "drafts/*"
  ],
  "deletion_policy": "mirror",
  "custom_metadata": {
    "team": "research",
    "source": "gcs"
  },
  "sync_interval_minutes": 15
}
```

**Response**

```json
{
  "sync_id": "sync_7e0abee6e110457db2c8",
  "collection_name": "company-knowledge",
  "bucket": "my-bucket",
  "prefix": "docs/",
  "region": "",
  "auth_method": "service_account",
  "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
import json

BASE_URL = "https://api.filesearch.dev"
API_KEY = "your_api_key"

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

with open("service-account.json") as f:
    sa_json = f.read()

response = requests.post(
    f"{BASE_URL}/v2/collections/company-knowledge/sync/gcs",
    headers=headers,
    json={
        "bucket": "my-bucket",
        "prefix": "docs/",
        "service_account_json": sa_json,
        "processing_type": "advanced",
        "deletion_policy": "mirror",
        "sync_interval_minutes": 15
    }
)

print(response.json())
```

```typescript TypeScript REST
import { readFileSync } from "node:fs";

const BASE_URL = "https://api.filesearch.dev";
const API_KEY = "your_api_key";

const saJson = readFileSync("service-account.json", "utf8");

const response = await fetch(
    `${BASE_URL}/v2/collections/company-knowledge/sync/gcs`,
    {
        method: "POST",
        headers: {
            "Authorization": `Bearer ${API_KEY}`,
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            bucket: "my-bucket",
            prefix: "docs/",
            service_account_json: saJson,
            processing_type: "advanced",
            deletion_policy: "mirror",
            sync_interval_minutes: 15
        })
    }
);

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