--- title: "Create Sync Configuration" method: POST path: "/v1/buckets/{bucket_id}/syncs" tags: ["Bucket Syncs"] --- # Create Sync Configuration `POST /v1/buckets/{bucket_id}/syncs` ## Request - Base URL: `https://api.mixpeek.com` - URL: `https://api.mixpeek.com/v1/buckets/{bucket_id}/syncs` - Auth: HTTP bearer and API key in header `X-Namespace` Create a sync configuration for automated storage ingestion. Establishes automated synchronization between an external storage provider and a Mixpeek bucket. The sync monitors the source path and ingests files according to the specified mode and filters. **Supported Providers:** google_drive, s3, snowflake, sharepoint, tigris **Built-in Robustness:** - Dead Letter Queue (DLQ): Failed objects tracked with 3 retries - Idempotent ingestion: Deduplication prevents duplicate objects - Distributed locking: Prevents concurrent sync execution - Rate limit handling: Automatic backoff on 429 responses - Metrics: Duration, files synced/failed, batches created **Sync Modes** (the request enum accepts exactly these two): - `initial_only`: Single bulk import, then sync stops - `continuous`: Polling-based monitoring (``polling_interval_seconds``, max 900) (Docstring previously advertised ``one_time``/``scheduled``, which the enum rejects with a 422 — modes here must match ``SyncCreateRequest``.) ## Path parameters - `bucket_id` string, required ## Request body - SyncCreateRequest: Request to create a bucket sync configuration. Establishes automated synchronization between a storage connection and a bucket. The sync monitors the source path for changes and ingests files according to the specified mode and filters. Supported Storage Providers: - google_drive: Google Drive and Workspace shared drives - s3: Amazon S3 and S3-compatible (MinIO, DigitalOcean Spaces, Wasabi) - snowflake: Snowflake data warehouse tables (rows become objects) - sharepoint: Microsoft SharePoint and OneDrive for Business - tigris: Tigris globally distributed object storage Robustness Features (built-in): - Dead Letter Queue (DLQ): Failed objects tracked with 3 retries before quarantine - Idempotent ingestion: Deduplication via (bucket_id, source_provider, source_object_id) - Distributed locking: Prevents concurrent execution of same sync config - Rate limit handling: Automatic backoff on provider 429 responses - Metrics: Duration, files synced/failed, batches created, rate limit hits Sync Modes (SyncMode has exactly two members): - continuous: Keeps monitoring the source; polling_interval_seconds is what makes it periodic, so recurring/scheduled imports are this mode - initial_only: Single import of what is already there, then stops Requirements: - connection_id: REQUIRED, must be an existing connection - source_path: REQUIRED, path must exist in the storage provider - sync_mode: OPTIONAL, defaults to 'continuous' - All other fields are OPTIONAL with sensible defaults - `connection_id` string, required: REQUIRED. Storage connection identifier to sync from. Must reference an existing connection created via POST /organizations/connections. The connection defines the storage provider and credentials. Supported providers: google_drive, s3, snowflake, sharepoint, tigris. - `source_path` string, nullable: REQUIRED unless provider_filters.use_search_api is true (search-API syncs don't traverse a path; defaults to '/'). Source path within the storage provider to monitor and sync. Path format varies by provider: - s3/tigris: 'bucket-name/prefix' or 'bucket-name'. - google_drive: folder ID or path like '/Marketing/Assets'. - sharepoint: '/sites/SiteName/Shared Documents/folder'. - snowflake: 'DATABASE.SCHEMA.TABLE' or just 'TABLE' if defaults set. - `sync_mode` 'initial_only' | 'continuous': Supported sync modes for external storage ingestion. - `file_filters` object, nullable: OPTIONAL. Filters to control which files are synced. When omitted, all files in source_path are synced. Supported filters: - include_patterns: Glob patterns to include (e.g., ['*.mp4', '*.mov']). - exclude_patterns: Glob patterns to exclude (e.g., ['*.tmp', '.DS_Store']). A pattern without '/' matches the file name in any folder; a pattern with '/' matches the path from the sync's source root. - extensions: File extensions to include (e.g., ['.mp4', '.jpg']). - min_size_bytes: Minimum file size in bytes. - max_size_bytes: Maximum file size in bytes. - modified_after: ISO datetime, only sync files modified after this time. - mime_types: List of MIME types to include (e.g., ['video/*', 'image/jpeg']). - `schema_mapping` SchemaMappingInput: Complete schema mapping configuration for a sync. Defines how source data (files, tags, metadata, columns) maps to the target bucket schema. Each key is a target field/blob name in the bucket. **Key Concepts:** - Keys are target bucket schema field names - Values define the source and extraction method - At least one blob mapping is typically required for file syncs - Field mappings extract metadata alongside the file content **Provider Examples:** **S3/Tigris Video Sync:** ```json { "content": { "target_type": "blob", "source": {"type": "file"}, "blob_type": "video" }, "category": { "target_type": "field", "source": {"type": "tag", "key": "category"} }, "source_bucket": { "target_type": "field", "source": {"type": "constant", "value": "production-videos"} } } ``` **Snowflake Customer Table Sync:** ```json { "customer_name": { "target_type": "field", "source": {"type": "column", "name": "NAME"} }, "profile_image": { "target_type": "blob", "source": {"type": "column", "name": "AVATAR_URL"}, "blob_type": "image" }, "segment": { "target_type": "field", "source": {"type": "column", "name": "CUSTOMER_SEGMENT"}, "transform": "lowercase" } } ``` **Google Drive with Folder Categories:** ```json { "content": { "target_type": "blob", "source": {"type": "file"}, "blob_type": "auto" }, "department": { "target_type": "field", "source": {"type": "folder_path", "segment": 0}, "transform": "lowercase" }, "description": { "target_type": "field", "source": {"type": "drive_property", "key": "description"} } } ``` Attributes: mappings: Dictionary mapping target field names to their source extractors - `mappings` object, required: Dictionary mapping target field names to their source extractors. Keys are bucket schema field names (e.g., 'content', 'category'). Values are mapping entries defining how to extract and store the data. At least one blob mapping (target_type='blob') is recommended for file syncs. - `polling_interval_seconds` integer: Interval in seconds between polling checks for new files. OPTIONAL. Defaults to 300 seconds (5 minutes). Must be between 30 and 86400 seconds (0.5 minutes to 1 day). Only applies to the 'continuous' sync mode. Lower values mean faster detection but higher API usage. - `batch_size` integer: Number of files to process in each batch during sync. OPTIONAL. Defaults to 50 files per batch. Must be between 1 and 100. Larger batches improve throughput but require more memory. Smaller batches provide more granular progress tracking. - `skip_batch_submission` boolean: 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. Useful for bulk data migration or when you want to manually control when processing occurs. While True, nothing this sync ingests is processed or searchable: objects keep arriving and no batch is ever created. OPTIONAL. Defaults to False (batches are created and submitted). - `batch_collection_ids` string[], nullable: Collections this sync's auto-batch processes, by id or name. OPTIONAL. When omitted, every enabled collection sourced from the bucket is auto-discovered, which is the default behaviour. Name a subset when another collection on the same bucket is fed some other way, for example one that only an alert's batch action writes to: without this the sync processes every synced object into it and the alert's selection stops meaning anything. Ignored when skip_batch_submission is True. - `ingest_filter` IngestFilter: A pinned saved retriever every candidate object runs through before commit. The filter matches a candidate when the retriever returns at least one document for it. The candidate is offered to the retriever as a seed document (its mapped fields at the root, the source record under ``source``) and as inputs (each declared input filled from the candidate field of the same name, and one media-typed input given the bytes as base64). - `retriever_id` string, required: The saved retriever every candidate object runs through. - `retriever_version` integer, nullable: The retriever version the filter runs. Pinned when the bucket or sync is written: omit it to pin the retriever's current version. A later edit to the retriever does not change the filter until this number changes. - `action` 'keep' | 'drop' | 'tag': What a match means for a candidate object. - `on_error` 'keep' | 'drop': What happens to a candidate the filter could not judge. - `timeout_seconds` integer: The longest one retriever run may take for one candidate. - `skip_duplicates` boolean: If True, skip files whose source ID already exists in the bucket. If False, replace existing objects when re-syncing. OPTIONAL. Defaults to True. - `reconcile` ReconcileSettings: Controls how Mixpeek reconciles objects when the source changes. - `on_delete` boolean: When a source asset is deleted, cascade-delete the corresponding Mixpeek objects (and their collection documents). Default True. - `on_update` boolean: When a source asset's metadata changes, propagate the update to the Mixpeek object and re-process it through connected collections. Default True. On an Iconik sync, True makes the per-asset Iconik calls for every listed asset on every walk. False lets the sync skip assets whose stored modified time matches the listing before it makes those calls, and metadata edits that leave the modified time unchanged are then not picked up. - `on_filter_drift` boolean: During reconciliation, remove objects whose source asset no longer matches the configured metadata_filters. Default True. - `re_extract_on_update` boolean: When on_update is True, also re-extract (rebatch) the object through its connected collections. Set to False to propagate metadata changes without triggering re-extraction. Default True. - `re_extract_fields` string[], nullable: When set, only re-extract if one of these specific fields changed. Field names are matched against the source metadata keys. If None (default), any metadata change triggers re-extraction (when re_extract_on_update is True). Example: ['title', 'description', 'media_type'] - `sync_from` string, date-time, nullable: OPTIONAL. Seed the incremental watermark: only assets modified after this timestamp are ingested — the historical backlog is skipped. Use for a 'freshness lane': a second config on an already-backfilling source (with a distinct source_path label) that keeps NEW uploads landing within minutes while the backfill config churns. Omit for a full sync from the beginning. - `provider_filters` object, nullable: OPTIONAL. Provider-specific pre-filters pushed down to the storage API call. Applied BEFORE file_filters (which are client-side). Each provider defines its own filter schema. Examples: - Iconik: {'collection_ids': ['col_abc']} - Google Drive: {'shared_drive_id': '0AH-Xabc123'} - S3: {'prefix': 'videos/'} - `description` string, nullable: OPTIONAL description of this sync configuration. PATCH accepted it before create did. - `max_objects_per_run` integer, nullable: OPTIONAL hard cap on objects processed per sync run (default 100000). PATCH accepted it before create did. - `sync_concurrency` integer, nullable: OPTIONAL per-sync override for concurrent object processing. Must be between 1 and 100 if provided. Defaults to the SYNC_OBJECT_CONCURRENCY worker env (8) when unset. - `metadata` object, nullable: Optional custom metadata to attach to the sync configuration. NOT REQUIRED. Arbitrary key-value pairs for tagging and organization. Common uses: project tags, environment labels, cost centers. Maximum 50 keys, values must be JSON-serializable. ## Response `200` Successful Response - SyncConfigurationModel: 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 - `sync_config_id` string: Unique identifier for the sync configuration. - `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'. - `file_filters` FileFilters: Filter rules controlling which files are synced from storage providers. All filters are optional and combined with AND logic. Files must pass ALL specified filters to be synced. **Pattern Matching:** Uses glob patterns (*, ?, [abc], etc.) **Size Filtering:** Bytes-based, inclusive bounds **Time Filtering:** ISO 8601 datetime, based on provider's modified timestamp - `include_patterns` string[], nullable: Glob patterns to include (e.g. ['*.mp4', '*.mov']). A pattern without '/' matches the file name in any folder; a pattern with '/' matches the path from the sync's source root (e.g. 'videos/*.mp4'). - `exclude_patterns` string[], nullable: Glob patterns to exclude (e.g. ['*/drafts/*', '*_temp.*']). Matched like include_patterns: without '/' against the file name, with '/' against the path from the sync's source root. - `min_size_bytes` integer, nullable: Minimum file size (bytes). Files smaller are skipped. - `max_size_bytes` integer, nullable: Maximum file size (bytes). Files larger are skipped. - `modified_after` string, date-time, nullable: Only sync files modified after this timestamp. - `modified_before` string, date-time, nullable: Only sync files modified before this timestamp. - `mime_types` string[], nullable: Optional list of MIME types to include. - `metadata_filters` MetadataFilter[], nullable: Filters applied to provider-specific metadata fields. All filters combined with AND logic. - `field` string, required - `operator` 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'gt' | 'lt' | 'gte' | 'lte' | 'exists' - `value` union - string - integer - number - boolean - `schema_mapping` SchemaMappingOutput: Complete schema mapping configuration for a sync. Defines how source data (files, tags, metadata, columns) maps to the target bucket schema. Each key is a target field/blob name in the bucket. **Key Concepts:** - Keys are target bucket schema field names - Values define the source and extraction method - At least one blob mapping is typically required for file syncs - Field mappings extract metadata alongside the file content **Provider Examples:** **S3/Tigris Video Sync:** ```json { "content": { "target_type": "blob", "source": {"type": "file"}, "blob_type": "video" }, "category": { "target_type": "field", "source": {"type": "tag", "key": "category"} }, "source_bucket": { "target_type": "field", "source": {"type": "constant", "value": "production-videos"} } } ``` **Snowflake Customer Table Sync:** ```json { "customer_name": { "target_type": "field", "source": {"type": "column", "name": "NAME"} }, "profile_image": { "target_type": "blob", "source": {"type": "column", "name": "AVATAR_URL"}, "blob_type": "image" }, "segment": { "target_type": "field", "source": {"type": "column", "name": "CUSTOMER_SEGMENT"}, "transform": "lowercase" } } ``` **Google Drive with Folder Categories:** ```json { "content": { "target_type": "blob", "source": {"type": "file"}, "blob_type": "auto" }, "department": { "target_type": "field", "source": {"type": "folder_path", "segment": 0}, "transform": "lowercase" }, "description": { "target_type": "field", "source": {"type": "drive_property", "key": "description"} } } ``` Attributes: mappings: Dictionary mapping target field names to their source extractors - `mappings` object, required: Dictionary mapping target field names to their source extractors. Keys are bucket schema field names (e.g., 'content', 'category'). Values are mapping entries defining how to extract and store the data. At least one blob mapping (target_type='blob') is recommended for file syncs. - `sync_mode` 'initial_only' | 'continuous': Supported sync modes for external storage ingestion. - `polling_interval_seconds` integer: Polling interval in seconds (continuous mode). Up to 86400 (1 day) — slow intervals are a legitimate ops throttle (e.g. deliberately deprioritizing freshness lanes during a backfill), and the read model must accept any value the platform itself may have stored. - `batch_size` integer: Number of files processed per sync batch. - `create_object_on_confirm` boolean: Whether objects should be created immediately after confirmation. - `skip_duplicates` boolean: Skip files whose hashes already exist in the bucket. - `skip_batch_submission` boolean: Sync-only mode: download and store files in the bucket without running them through the collection processing pipeline. Set to True during initial bulk ingestion, then flip to False to trigger processing once all files are synced. - `batch_collection_ids` string[], nullable: Collections this sync's auto-batch processes. None auto-discovers every enabled collection sourced from the bucket, which is the historical behaviour. Name a subset when a collection on the same bucket is fed some other way, for example a collection that only an alert's batch action writes to: without this the sync would process every synced object into it and the alert's selection would mean nothing. - `ingest_filter` IngestFilter: A pinned saved retriever every candidate object runs through before commit. The filter matches a candidate when the retriever returns at least one document for it. The candidate is offered to the retriever as a seed document (its mapped fields at the root, the source record under ``source``) and as inputs (each declared input filled from the candidate field of the same name, and one media-typed input given the bytes as base64). - `retriever_id` string, required: The saved retriever every candidate object runs through. - `retriever_version` integer, nullable: The retriever version the filter runs. Pinned when the bucket or sync is written: omit it to pin the retriever's current version. A later edit to the retriever does not change the filter until this number changes. - `action` 'keep' | 'drop' | 'tag': What a match means for a candidate object. - `on_error` 'keep' | 'drop': What happens to a candidate the filter could not judge. - `timeout_seconds` integer: The longest one retriever run may take for one candidate. - `reconcile` ReconcileSettings: Controls how Mixpeek reconciles objects when the source changes. - `on_delete` boolean: When a source asset is deleted, cascade-delete the corresponding Mixpeek objects (and their collection documents). Default True. - `on_update` boolean: When a source asset's metadata changes, propagate the update to the Mixpeek object and re-process it through connected collections. Default True. On an Iconik sync, True makes the per-asset Iconik calls for every listed asset on every walk. False lets the sync skip assets whose stored modified time matches the listing before it makes those calls, and metadata edits that leave the modified time unchanged are then not picked up. - `on_filter_drift` boolean: During reconciliation, remove objects whose source asset no longer matches the configured metadata_filters. Default True. - `re_extract_on_update` boolean: When on_update is True, also re-extract (rebatch) the object through its connected collections. Set to False to propagate metadata changes without triggering re-extraction. Default True. - `re_extract_fields` string[], nullable: When set, only re-extract if one of these specific fields changed. Field names are matched against the source metadata keys. If None (default), any metadata change triggers re-extraction (when re_extract_on_update is True). Example: ['title', 'description', 'media_type'] - `status` 'PENDING' | 'QUEUED' | 'IN_PROGRESS' | 'PROCESSING' | 'COMPLETED' | 'COMPLETED_WITH_ERRORS' | 'FAILED' | 'CANCELED' | 'INTERRUPTED' | 'UNKNOWN' | 'SKIPPED' | 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'SUSPENDED' | 'DEACTIVATED': 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, QUEUED, IN_PROGRESS, or PROCESSING states - Stop polling when task reaches COMPLETED, COMPLETED_WITH_ERRORS, FAILED, or CANCELED - Use exponential backoff (1s → 30s) when polling - `is_active` boolean: Convenience flag used for filtering active syncs. - `total_files_discovered` integer: Cumulative count of files found in source across all runs. - `total_files_synced` integer: Cumulative count of successfully synced files. - `total_files_failed` integer: Cumulative count of failed files (sent to DLQ after 3 retries). - `total_bytes_synced` integer: Cumulative bytes transferred across all runs. - `stats` SyncStatsModel: Throughput and volume metrics the sync pipeline aggregates on every run. Cumulative fields sum over all runs; last_run_* fields describe the most recent run only. Present once a run has completed. Every field is optional so a partial document still validates. - `total_objects_synced` integer: Objects successfully synced across all runs. - `total_objects_verified` integer: Objects verified across all runs. - `total_objects_failed` integer: Objects that failed across all runs. - `total_objects_discovered` integer: Objects discovered in source across all runs. - `total_objects_skipped` integer: Objects skipped (already synced) across all runs. - `total_bytes_synced` integer: Bytes transferred across all runs. - `total_duration_seconds` number: Summed run duration in seconds across all runs. - `total_runs_completed` integer: Runs that completed with no failures. - `total_runs_failed` integer: Runs that ended with at least one failure. - `peak_objects_per_min` number: Highest objects-per-minute rate seen in any run. - `last_run_objects_synced` integer: Objects synced in the most recent run. - `last_run_objects_verified` integer: Objects verified in the most recent run. - `last_run_objects_failed` integer: Objects that failed in the most recent run. - `last_run_objects_discovered` integer: Objects discovered in the most recent run. - `last_run_objects_skipped` integer: Objects skipped in the most recent run. - `last_run_bytes_synced` integer: Bytes transferred in the most recent run. - `last_run_duration_seconds` number: Duration of the most recent run in seconds. - `last_run_throughput_objects_per_min` number: Objects-per-minute rate of the most recent run. - `last_run_throughput_mbps` number: Throughput of the most recent run in MB/s. - `last_run_avg_object_size_bytes` integer: Average object size in the most recent run, in bytes. - `last_run_at` string, date-time, nullable: When the most recent run completed. - `updated_at` string, date-time, nullable: When these stats were last updated. - `created_at` string, date-time: When sync configuration was created. - `updated_at` string, date-time: Last modification timestamp. - `last_sync_at` string, date-time, nullable: When last successful sync completed. Used for incremental syncs. - `per_shard_last_sync_at` object: Per-shard last-sync timestamps keyed by shard value (e.g. collection_id). When a new shard is added, its absence here forces a full scan even if the global last_sync_at is set. - `next_sync_at` string, date-time, nullable: Scheduled time for next sync (continuous/scheduled modes). - `created_by_user_id` string, required: User identifier that created the sync configuration. - `last_error` string, nullable: Most recent error message if sync attempts failed. - `consecutive_failures` integer - `provider_filters` object: Provider-specific pre-filters pushed down to the API call. The sync engine passes these to iter_objects() without interpretation. Each provider defines its own schema. Applied BEFORE file_filters. Examples: Iconik {'collection_ids': [...]}, Google Drive {'shared_drive_id': '...'} - `source_type` string, nullable: Storage provider type for API progress views (for example: s3, google_drive, iconik). - `metadata` object: Arbitrary metadata supplied by the user. - `locked_by_worker_id` string, nullable: Worker ID that currently holds the lock for this sync - `locked_at` string, date-time, nullable: Timestamp when lock was acquired - `lock_expires_at` string, date-time, nullable: Timestamp when lock expires (for stale lock recovery) - `pending_full_sync` boolean: A full sweep was requested (trigger?full_sync=true) while a run held the lock. The finishing run dispatches it automatically on lock release. - `paused` boolean: Whether sync is currently paused (user-controlled) - `pause_reason` string, nullable: Reason for pause - `paused_at` string, date-time, nullable: Timestamp when paused - `paused_by_user_id` string, nullable: User who paused the sync - `description` string, nullable: Sync configuration description - `max_objects_per_run` integer: Hard cap on objects per sync run (prevents runaway syncs) - `max_batch_chunk_size` integer: Maximum objects per batch chunk - `batch_chunk_size` integer: Number of objects per batch chunk (for concurrent processing) - `sync_concurrency` integer, nullable: Per-sync override for concurrent object processing during a sync run. OPTIONAL. When unset, falls back to the SYNC_OBJECT_CONCURRENCY worker env default (8). - `current_sync_run_id` string, nullable: UUID for current/last sync run - `sync_run_counter` integer: Increments on each sync execution - `batch_ids` string[]: List of batch IDs created by this sync - `task_ids` string[]: List of task IDs for batches - `batches_created` integer: Total number of batches created - `resume_enabled` boolean: Whether resuming partial runs is enabled - `resume_cursor` string, nullable: Last page/cursor processed (for paginated APIs like Google Drive) - `resume_last_primary_key` string, nullable: Last primary key processed (for database syncs with stable ordering) - `resume_objects_processed` integer: Count of objects processed in current/last run - `resume_checkpoint_frequency` integer: How often to checkpoint (in objects). Default: every 1000 objects - `current_cursor` string, nullable: Convenience mirror of the current resume cursor for API progress views. - `sync_checkpoints` object: Per-(config, shard) high-water checkpoints keyed by shard key (e.g. collection_id for parallel fan-outs, 'pages_N_M' for page-range shards, '__default__' for unsharded runs). Each entry holds: pass_id (lexicographically-ordered pass marker), cursor (provider cursor, e.g. JSON-encoded Iconik search_after), objects_processed (forward-only progress guard), modified_since (incremental filter frozen at pass start), completed_at (set when the shard drained its source — the next cycle wraps around to a fresh full pass only after the polling cadence elapses), and updated_at. A NEW job resumes each shard from its checkpoint instead of re-walking from page 1 (2026-06-11 re-scan treadmill). - `schedule` object, nullable: Derived scheduling summary: mode, interval, next run, and last successful run. - `sync_progress` object: Derived progress summary for API observability. - `locked` boolean, required: Whether a worker currently holds this sync's run lock. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `422`: Unprocessable Entity - `429`: Too Many Requests - `500`: Internal Server Error - `503`: Service Unavailable ## Changes - **2026-10-12** `2e8a69f8c920`: 2 info - added the new optional request property `ingest_filter` - added the optional property `ingest_filter` to the response with the `200` status - **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info - removed the optional property `detail` from the response with the `422` status - added the non-success response with the status `429` - added the non-success response with the status `503` - added the optional property `success` to the response with the `422` status - …2 more - **2026-09-22** `ed5ff164de75`: 2 info - added the new optional request property `batch_collection_ids` - added the optional property `batch_collection_ids` to the response with the `200` status - **2026-09-19** `4bbfcce2371b`: 2 info - added the new optional request property `sync_concurrency` - added the optional property `sync_concurrency` to the response with the `200` status - **2026-09-11** `67333a479215`: 1 info - added the optional property `stats` to the response with the `200` status [Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/buckets/:bucket_id/syncs/post.md) --- [API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)