Update Sync Configuration

curl --request PATCH \
  --url https://api.mixpeek.com/v1/buckets/{bucket_id}/syncs/{sync_config_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "Daily video ingestion from production bucket",
  "metadata": {
    "environment": "production",
    "project": "video-pipeline"
  },
  "status": "pending",
  "is_active": true,
  "polling_interval_seconds": 60,
  "batch_size": 10,
  "schema_mapping": {
    "mappings": {}
  },
  "skip_batch_submission": false
}
'

{
  "bucket_id": "<string>",
  "connection_id": "<string>",
  "internal_id": "<string>",
  "namespace_id": "<string>",
  "source_path": "<string>",
  "created_by_user_id": "<string>",
  "sync_config_id": "<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>"
    ]
  },
  "schema_mapping": {
    "mappings": {}
  },
  "sync_mode": "continuous",
  "polling_interval_seconds": 300,
  "batch_size": 50,
  "create_object_on_confirm": true,
  "skip_duplicates": true,
  "skip_batch_submission": false,
  "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",
  "last_error": "<string>",
  "consecutive_failures": 0,
  "metadata": {},
  "locked_by_worker_id": "<string>",
  "locked_at": "2023-11-07T05:31:56Z",
  "lock_expires_at": "2023-11-07T05:31:56Z",
  "paused": false,
  "pause_reason": "<string>",
  "paused_at": "2023-11-07T05:31:56Z",
  "paused_by_user_id": "<string>",
  "max_objects_per_run": 100000,
  "max_batch_chunk_size": 1000,
  "batch_chunk_size": 100,
  "current_sync_run_id": "<string>",
  "sync_run_counter": 0,
  "batch_ids": [
    "<string>"
  ],
  "task_ids": [
    "<string>"
  ],
  "batches_created": 0,
  "resume_enabled": true,
  "resume_cursor": "<string>",
  "resume_last_primary_key": "<string>",
  "resume_objects_processed": 0,
  "resume_checkpoint_frequency": 1000
}

PATCH

buckets

{bucket_id}

syncs

{sync_config_id}

Update Sync Configuration

curl --request PATCH \
  --url https://api.mixpeek.com/v1/buckets/{bucket_id}/syncs/{sync_config_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "Daily video ingestion from production bucket",
  "metadata": {
    "environment": "production",
    "project": "video-pipeline"
  },
  "status": "pending",
  "is_active": true,
  "polling_interval_seconds": 60,
  "batch_size": 10,
  "schema_mapping": {
    "mappings": {}
  },
  "skip_batch_submission": false
}
'

{
  "bucket_id": "<string>",
  "connection_id": "<string>",
  "internal_id": "<string>",
  "namespace_id": "<string>",
  "source_path": "<string>",
  "created_by_user_id": "<string>",
  "sync_config_id": "<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>"
    ]
  },
  "schema_mapping": {
    "mappings": {}
  },
  "sync_mode": "continuous",
  "polling_interval_seconds": 300,
  "batch_size": 50,
  "create_object_on_confirm": true,
  "skip_duplicates": true,
  "skip_batch_submission": false,
  "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",
  "last_error": "<string>",
  "consecutive_failures": 0,
  "metadata": {},
  "locked_by_worker_id": "<string>",
  "locked_at": "2023-11-07T05:31:56Z",
  "lock_expires_at": "2023-11-07T05:31:56Z",
  "paused": false,
  "pause_reason": "<string>",
  "paused_at": "2023-11-07T05:31:56Z",
  "paused_by_user_id": "<string>",
  "max_objects_per_run": 100000,
  "max_batch_chunk_size": 1000,
  "batch_chunk_size": 100,
  "current_sync_run_id": "<string>",
  "sync_run_counter": 0,
  "batch_ids": [
    "<string>"
  ],
  "task_ids": [
    "<string>"
  ],
  "batches_created": 0,
  "resume_enabled": true,
  "resume_cursor": "<string>",
  "resume_last_primary_key": "<string>",
  "resume_objects_processed": 0,
  "resume_checkpoint_frequency": 1000
}

Headers

Authorization

string

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 YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

X-Namespace

string

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

sync_config_id

string

required

Body

application/json

Request to update an existing sync configuration.

Allows partial updates to sync settings without recreating the configuration. All fields are optional - only provided fields will be updated.

Use Cases: - Pause/resume syncs by toggling is_active - Adjust polling intervals based on activity patterns - Update batch sizes for performance tuning - Add metadata tags for organization

Requirements: - All fields are OPTIONAL - At least one field should be provided for the update - Changes take effect on the next sync cycle

description

string | null

Optional human-readable description of the sync configuration. NOT REQUIRED. Used for documentation and UI display. Maximum 500 characters.

Example:

"Daily video ingestion from production bucket"

metadata

Metadata · object

Optional custom metadata to replace existing metadata. NOT REQUIRED. Completely replaces existing metadata (not merged). Use for tagging, categorization, or custom attributes. Maximum 50 keys, values must be JSON-serializable.

Example:

{
  "environment": "production",
  "project": "video-pipeline"
}

status

enum<string> | null

Optional status to set for the sync configuration. NOT REQUIRED. Valid values: 'pending', 'processing', 'completed', 'failed', 'paused'. Typically managed automatically but can be manually overridden. Use pause/resume endpoints instead for active control.

Available options:

PENDING,

IN_PROGRESS,

PROCESSING,

COMPLETED,

COMPLETED_WITH_ERRORS,

FAILED,

CANCELED,

UNKNOWN,

SKIPPED,

DRAFT,

ACTIVE,

ARCHIVED,

SUSPENDED

Example:

"pending"

is_active

boolean | null

Optional flag to enable or disable the sync configuration. NOT REQUIRED. When False, sync will not process new files. Prefer using the /pause and /resume endpoints for clarity. Changes take effect immediately.

Example:

true

polling_interval_seconds

integer | null

Optional new polling interval in seconds. NOT REQUIRED. Must be between 30 and 900 seconds if provided. Only applies to 'continuous' and 'scheduled' sync modes. Lower values increase responsiveness but API usage.

Required range: 30 <= x <= 900

Example:

60

batch_size

integer | null

Optional new batch size for file processing. NOT REQUIRED. Must be between 1 and 100 if provided. Larger batches improve throughput but use more memory. Changes apply to subsequent batches only.

Required range: 1 <= x <= 100

Example:

10

schema_mapping

SchemaMapping · object

Optional schema mapping to replace existing mapping. NOT REQUIRED. Completely replaces existing schema_mapping (not merged). Defines how source data maps to bucket schema fields and blobs. See SyncCreateRequest.schema_mapping for detailed documentation.

Show child attributes

skip_batch_submission

boolean | null

If True, sync objects to the bucket without creating or submitting batches for collection processing. Objects are created in the bucket but no tier processing is triggered. NOT REQUIRED. When omitted, existing value is preserved.

Example:

false

Response

Successful Response

Bucket-scoped configuration for automated storage synchronization.

Defines how files are synced from external storage providers to a Mixpeek bucket. Includes configuration, status, metrics, and robustness control fields.

Supported Providers: google_drive, s3, snowflake, sharepoint, tigris

Built-in Robustness:

Distributed locking (locked_by_worker_id, lock_expires_at)
Pause/resume control (paused, pause_reason, paused_at)
Safety limits (max_objects_per_run, batch_chunk_size)
Resume checkpointing (resume_cursor, resume_objects_processed)
Batch tracking (batch_ids, task_ids, batches_created)

Metrics Fields:

total_files_discovered: Files found in source
total_files_synced: Successfully synced files
total_files_failed: Files that failed (check DLQ)
total_bytes_synced: Total data transferred
consecutive_failures: Failure count for auto-suspend

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. Format varies by provider: s3/tigris='bucket/prefix', google_drive='folder_id', sharepoint='/sites/Name/Documents', snowflake='DB.SCHEMA.TABLE'.

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

FileFilters · object

Optional filter rules limiting which files are synced.

Show child attributes

schema_mapping

SchemaMapping · object

Schema mapping defining how source data maps to bucket schema fields. Maps external storage attributes (tags, metadata, columns, filenames) to bucket schema fields and blob properties. When provided, enables structured extraction of metadata from the sync source. See SchemaMapping for detailed configuration options.

Show child attributes

sync_mode

enum<string>

default:continuous

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.

skip_batch_submission

boolean

default:false

If True, sync objects to the bucket without creating/submitting batches for processing.

status

enum<string>

default:PENDING

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,

COMPLETED_WITH_ERRORS,

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

Cumulative count of files found in source across all runs.

Required range: x >= 0

total_files_synced

integer

default:0

Cumulative count of successfully synced files.

Required range: x >= 0

total_files_failed

integer

default:0

Cumulative count of failed files (sent to DLQ after 3 retries).

Required range: x >= 0

total_bytes_synced

integer

default:0

Cumulative bytes transferred across all runs.

Required range: x >= 0

created_at

string<date-time>

When sync configuration was created.

updated_at

string<date-time>

Last modification timestamp.

last_sync_at

string<date-time> | null

When last successful sync completed. Used for incremental syncs.

next_sync_at

string<date-time> | null

Scheduled time for next sync (continuous/scheduled modes).

last_error

string | null

Most recent error message if sync attempts failed.

Maximum string length: 1000

consecutive_failures

integer

default:0

Required range: x >= 0

metadata

Metadata · object

Arbitrary metadata supplied by the user.

locked_by_worker_id

string | null

Worker ID that currently holds the lock for this sync

locked_at

string<date-time> | null

Timestamp when lock was acquired

lock_expires_at

string<date-time> | null

Timestamp when lock expires (for stale lock recovery)

paused

boolean

default:false

Whether sync is currently paused (user-controlled)

pause_reason

string | null

Reason for pause

paused_at

string<date-time> | null

Timestamp when paused

paused_by_user_id

string | null

User who paused the sync

max_objects_per_run

integer

default:100000

Hard cap on objects per sync run (prevents runaway syncs)

Required range: x >= 1

max_batch_chunk_size

integer

default:1000

Maximum objects per batch chunk

Required range: 1 <= x <= 1000

batch_chunk_size

integer

default:100

Number of objects per batch chunk (for concurrent processing)

Required range: 1 <= x <= 1000

current_sync_run_id

string | null

UUID for current/last sync run

sync_run_counter

integer

default:0

Increments on each sync execution

Required range: x >= 0

batch_ids

string[]

List of batch IDs created by this sync

task_ids

string[]

List of task IDs for batches

batches_created

integer

default:0

Total number of batches created

Required range: x >= 0

resume_enabled

boolean

default:true

Whether resuming partial runs is enabled

resume_cursor

string | null

Last page/cursor processed (for paginated APIs like Google Drive)

resume_last_primary_key

string | null

Last primary key processed (for database syncs with stable ordering)

resume_objects_processed

integer

default:0

Count of objects processed in current/last run

Required range: x >= 0

resume_checkpoint_frequency

integer

default:1000

How often to checkpoint (in objects). Default: every 1000 objects

Required range: 100 <= x <= 10000

Get Sync Configuration Pause Sync Configuration

⌘I

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Templates

Manifest

Resource Search

Inference

Tasks

Webhooks

Update Sync Configuration

Headers

Path Parameters

Body

Response