Sync API#

Triggering a sync requires apps:manage. Reading its progress stream requires data:read.

Start a sync#

Accepts a sync request for the source and returns an asynchronous resource. Acceptance means the request is recorded, not that table commits have finished.

A paused or deleted source is refused. If the source already has live work, the response reports the conflict instead of starting a duplicate run.

Use an Idempotency-Key when retrying after a lost response. Bind the key to one source and request body.

Stream progress#

The Server-Sent Events stream reports progress and the durable sync outcome. Reconnect using Last-Event-ID when the transport closes. Treat the source resource's latest sync as the final authority after reconnecting.

Events can include table name, phase, completed and total counts, and terminal outcome. Clients must ignore additive event fields.

After completion#

A successful terminal event means the run's table commits finished. Related tables can complete at different times, so freshness-sensitive automation should inspect the committed _synced_at values or the catalog after terminal state.

Use source error logs when a run fails and Syncing for merge and delete semantics.