Update Sync Configuration

curl --request PATCH \
  --url https://api.mixpeek.com/v1/buckets/{bucket_id}/syncs/{sync_config_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '{
  "description": "Pause sync temporarily",
  "is_active": false
}'

{
  "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": {}
}

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 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '{
  "description": "Pause sync temporarily",
  "is_active": false
}'

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

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.

Examples:

"Daily video ingestion from production bucket"

metadata

object | null

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.

Examples:

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

{
  "last_updated": "2025-11-01",
  "owner": "data-team"
}

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. Enumeration of task statuses for tracking asynchronous operations.

Task statuses indicate the current state of asynchronous operations like batch processing, object ingestion, clustering, and taxonomy execution.

Status Categories: Operation Statuses: Track progress of async operations Lifecycle Statuses: Track entity state (buckets, collections, namespaces)

Values: PENDING: Task is queued but has not started processing yet IN_PROGRESS: Task is currently being executed PROCESSING: Task is actively processing data (similar to IN_PROGRESS) COMPLETED: Task finished successfully with no errors COMPLETED_WITH_ERRORS: Task finished but some items failed (partial success) FAILED: Task encountered an error and could not complete CANCELED: Task was manually canceled by a user or system UNKNOWN: Task status could not be determined SKIPPED: Task was intentionally skipped DRAFT: Task is in draft state and not yet submitted

ACTIVE: Entity is active and operational (for buckets, collections, etc.)
ARCHIVED: Entity has been archived
SUSPENDED: Entity has been temporarily suspended

Terminal Statuses: COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED are terminal statuses. Once a task reaches these states, it will not transition to another state.

Partial Success Handling: COMPLETED_WITH_ERRORS indicates that the operation completed but some documents/items failed. The task result includes: - List of successful items - List of failed items with error details - Success rate percentage This allows clients to handle partial success scenarios appropriately.

Polling Guidance: - Poll tasks in PENDING, IN_PROGRESS, or PROCESSING states - Stop polling when task reaches COMPLETED, COMPLETED_WITH_ERRORS, FAILED, or CANCELED - Use exponential backoff (1s → 30s) when polling

Available options:

PENDING,

IN_PROGRESS,

PROCESSING,

COMPLETED,

COMPLETED_WITH_ERRORS,

FAILED,

CANCELED,

UNKNOWN,

SKIPPED,

DRAFT,

ACTIVE,

ARCHIVED,

SUSPENDED

Examples:

"pending"

"processing"

"completed"

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.

Examples:

true

false

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

Examples:

60

300

600

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

Examples:

10

50

100

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.

Show child attributes

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,

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

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.

Get Sync Configuration Pause Sync Configuration

⌘I

Health

Organizations

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Analytics

Tasks

Webhooks

Update Sync Configuration

Authorizations

Headers

Path Parameters

Body

Response