Sync API Reference

Use the Done Bear sync transport for bootstrap, batch reads, delta polling, mutations, and WebSocket subscriptions.

The sync transport powers first-party clients and advanced integrations that need bootstraps, incremental deltas, mutation batches, and live updates. Use it only if REST and GraphQL do not cover your needs, because these endpoints are transport-shaped and closer to implementation details than the rest of the public API.

Support framing

Treat the sync surface as advanced. The routes are real and used in production, but they are not yet packaged as a beginner-friendly, versioned platform API.

`GET /sync/bootstrap`

Streams an NDJSON bootstrap for the authenticated user's sync groups.

Query parameters:

Parameter	Type	Notes
`onlyModels`	string	Optional comma-separated model list
`schemaHash`	string	Optional schema hash
`syncGroups`	string	Optional comma-separated group list

curl https://api.donebear.com/sync/bootstrap \
  -H "Authorization: Bearer <token>"

The response is application/x-ndjson and streams one JSON object per line.

`POST /sync/batch`

Loads a specific set of records as NDJSON.

Request body:

Field	Type	Notes
`requests`	array	Required
`firstSyncId`	string	Optional

Each request can be:

{ "modelName": "...", "indexedKey": "...", "keyValue": "..." }
{ "modelName": "...", "groupId": "..." }

curl https://api.donebear.com/sync/batch \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  --data '{
    "requests": [
      {
        "modelName": "Task",
        "indexedKey": "id",
        "keyValue": "6fd41760-f5ee-4f60-80a6-8d15aeb11043"
      }
    ]
  }'

`GET /sync/deltas`

Fetches ordered sync actions after a given sync ID.

Query parameters:

Parameter	Type	Notes
`after`	string	Optional numeric string
`limit`	string	Optional numeric string, clamped on the server

curl "https://api.donebear.com/sync/deltas?after=1200&limit=100" \
  -H "Authorization: Bearer <token>"

Typical response:

{
  "lastSyncId": "1300",
  "hasMore": false,
  "actions": [
    {
      "syncId": "1300",
      "modelName": "Task",
      "modelId": "6fd41760-f5ee-4f60-80a6-8d15aeb11043",
      "action": "UPDATE",
      "data": {},
      "groupId": "workspace-id",
      "clientTxId": "client-tx-id",
      "clientId": "client-id",
      "createdAt": "2026-03-11T20:30:32.000Z"
    }
  ]
}

`POST /sync/mutate`

Submits a mutation batch.

Request body:

Field	Type	Notes
`batchId`	string	Required
`transactions`	array	Required

Each transaction includes:

clientTxId
clientId
modelName
modelId as a UUID
action as INSERT, UPDATE, DELETE, ARCHIVE, or UNARCHIVE
payload as an object

curl https://api.donebear.com/sync/mutate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  --data '{
    "batchId": "batch-1",
    "transactions": [
      {
        "clientTxId": "tx-1",
        "clientId": "cli-example",
        "modelName": "Task",
        "modelId": "6fd41760-f5ee-4f60-80a6-8d15aeb11043",
        "action": "UPDATE",
        "payload": {
          "title": "Updated title"
        }
      }
    ]
  }'

`GET /sync/ws`

Opens a WebSocket for delta delivery.

The server requires a token in the query string during the initial upgrade and then expects a subscribe frame:

{
  "type": "subscribe",
  "afterSyncId": "0",
  "token": "<jwt>"
}

If subscription succeeds, the server replies with:

{
  "type": "subscribed",
  "afterSyncId": "0",
  "groups": ["user-id", "workspace-id"]
}

Delta frames arrive as:

{
  "type": "delta",
  "packet": {
    "lastSyncId": "1300",
    "actions": []
  }
}

Practical guidance

Start with REST or GraphQL unless you need sync semantics directly.
Expect NDJSON from bootstrap and batch endpoints.
Expect JSON from deltas and mutate.
Expect WebSocket frames for subscription and delta delivery.

Next steps

Read API overview if you need help choosing the right integration surface.
Use REST API reference or GraphQL reference for simpler integrations.

On this page