Sync API

Get sync status

GET /api/sync/status

curl http://localhost:8000/api/sync/status

Response 200 OK

{
  "running": false,
  "last_run_at": "2026-04-03T10:00:00Z",
  "last_summary": {
    "synced": 42,
    "errors": 0,
    "conflicts": 2
  }
}

---

Run sync (background)

Starts a sync run in the background. Returns immediately.

POST /api/sync/run

curl -X POST http://localhost:8000/api/sync/run

Response 202 Accepted

{"message": "Sync started"}

Monitor progress via WebSocket at ws://localhost:8000/ws.

Errors

Code	Reason
409	A sync cycle is already running

---

Run sync (await)

Runs sync and waits for completion. Suitable for automation/cron.

POST /api/sync/run/await

curl -X POST http://localhost:8000/api/sync/run/await

Response 200 OK

{
  "summary": {
    "synced": 42,
    "errors": 0,
    "conflicts": 2
  }
}

Errors

Code	Reason
409	A sync cycle is already running
500	Sync engine error

---

## WebSocket events

Connect to `ws://localhost:8000/ws` to receive real-time events:

| Event | Payload |
|---|---|
| `sync_complete` | `{synced, errors, conflicts}` |
| `sync_error` | `{message}` |
| `conflict_resolved` | `{wcp_id, winner}` |
| `conflict_dismissed` | `{wcp_id}` |
| `scan_complete` | `{bindings_count}` |
| `link_deleted` | `{wcp_id}` |
| `ping` | *(keepalive, no payload)* |