Skip to main content
POST
/
v1
/
buckets
/
{bucket_id}
/
syncs
Create Sync Configuration
curl --request POST \
  --url https://api.mixpeek.com/v1/buckets/{bucket_id}/syncs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '{
  "connection_id": "<string>",
  "source_path": "<string>",
  "sync_mode": "continuous",
  "file_filters": {},
  "polling_interval_seconds": 300,
  "batch_size": 50,
  "metadata": {}
}'
{
  "sync_config_id": "<string>",
  "bucket_id": "<string>",
  "connection_id": "<string>",
  "internal_id": "<string>",
  "namespace_id": "<string>",
  "source_path": "<string>",
  "file_filters": {
    "include_patterns": [
      "<string>"
    ],
    "exclude_patterns": [
      "<string>"
    ],
    "min_size_bytes": 1,
    "max_size_bytes": 1,
    "modified_after": "2023-11-07T05:31:56Z",
    "modified_before": "2023-11-07T05:31:56Z",
    "mime_types": [
      "<string>"
    ]
  },
  "sync_mode": "continuous",
  "polling_interval_seconds": 300,
  "batch_size": 50,
  "create_object_on_confirm": true,
  "skip_duplicates": true,
  "status": "PENDING",
  "is_active": true,
  "total_files_discovered": 0,
  "total_files_synced": 0,
  "total_files_failed": 0,
  "total_bytes_synced": 0,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "last_sync_at": "2023-11-07T05:31:56Z",
  "next_sync_at": "2023-11-07T05:31:56Z",
  "created_by_user_id": "<string>",
  "last_error": "<string>",
  "consecutive_failures": 0,
  "metadata": {}
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

​
Authorization
string
required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

​
X-Namespace
string
required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Path Parameters

​
bucket_id
string
required

Body

application/json

Request payload for creating a bucket sync configuration.

​
connection_id
string
required

Storage connection identifier

​
source_path
string
required

Source path within the storage provider

​
sync_mode
enum<string>

Supported sync modes for external storage ingestion.

Available options:
initial_only,
continuous
​
file_filters
object | null
​
polling_interval_seconds
integer
default:300
Required range: 30 <= x <= 900
​
batch_size
integer
default:50
Required range: 1 <= x <= 100
​
metadata
object | null

Response

Successful Response

Bucket-scoped configuration describing how to sync external files.

​
bucket_id
string
required

Target bucket identifier (e.g. 'bkt_marketing_assets').

​
connection_id
string
required

Storage connection identifier (e.g. 'conn_abc123').

​
internal_id
string
required

Organization internal identifier (multi-tenancy scope).

​
namespace_id
string
required

Namespace identifier owning the bucket.

​
source_path
string
required

Source path in the external storage provider.

​
created_by_user_id
string
required

User identifier that created the sync configuration.

​
sync_config_id
string

Unique identifier for the sync configuration.

​
file_filters
object | null

Optional filter rules limiting which files are synced. Filter rules controlling which files are synced from providers.

​
sync_mode
enum<string>

Sync mode controlling lifecycle (initial_only or continuous).

Available options:
initial_only,
continuous
​
polling_interval_seconds
integer
default:300

Polling interval in seconds (continuous mode).

Required range: 30 <= x <= 900
​
batch_size
integer
default:50

Number of files processed per sync batch.

Required range: 1 <= x <= 100
​
create_object_on_confirm
boolean
default:true

Whether objects should be created immediately after confirmation.

​
skip_duplicates
boolean
default:true

Skip files whose hashes already exist in the bucket.

​
status
enum<string>

Current lifecycle status for the sync configuration. PENDING: Not yet started. ACTIVE: Currently running/polling. SUSPENDED: Temporarily paused. COMPLETED: Initial sync completed (for initial_only mode). FAILED: Sync encountered errors.

Available options:
PENDING,
IN_PROGRESS,
PROCESSING,
COMPLETED,
FAILED,
CANCELED,
UNKNOWN,
SKIPPED,
DRAFT,
ACTIVE,
ARCHIVED,
SUSPENDED
​
is_active
boolean
default:true

Convenience flag used for filtering active syncs.

​
total_files_discovered
integer
default:0
Required range: x >= 0
​
total_files_synced
integer
default:0
Required range: x >= 0
​
total_files_failed
integer
default:0
Required range: x >= 0
​
total_bytes_synced
integer
default:0
Required range: x >= 0
​
created_at
string<date-time>
​
updated_at
string<date-time>
​
last_sync_at
string<date-time> | null
​
next_sync_at
string<date-time> | null
​
last_error
string | null

Most recent error message if sync attempts failed.

Maximum length: 1000
​
consecutive_failures
integer
default:0
Required range: x >= 0
​
metadata
object

Arbitrary metadata supplied by the user.