Sync protocol
Version vectors, conflict resolution, and offline-first sync for sessions
This endpoint reconciles changes made to the same session from more than one place — for example an offline client that edited messages while the server moved on. Reach for it when you support offline-first or multi-device editing and need to push accumulated changes, pull what you missed, and let the server detect and resolve any conflicts. It builds on the sessions you create in Manage sessions; if a sync goes the wrong way, Checkpoints let you roll back.
Sync Protocol
Request
POST /api/v1/sessions/:sessionId/sync.
clientIdstringrequiredClient identifier for version vector attribution
localVersionnumberrequiredThe session version the client last saw
localVectorVersionVectorrequiredThe client's current version vector
localChangesSessionChange[]Changes made on the client since the last sync
modestringdefault: mergeSync strategy: merge (default), force_local, or force_remote
A request missing clientId, localVersion or localVector returns 400.
Example Request
Response
Every successful call returns 200 with a SyncResponse:
| Field | Meaning |
|---|---|
status | success or conflict |
newVersion | The session version after the sync |
newVector | The server's version vector after the sync |
remoteChanges | Changes for the client to apply (currently always []) |
conflicts | Present when status is conflict |
fullState | The server's full SessionState when the client should replace its copy |
Version Vectors
Each session carries a version vector: a map from clientId to the latest version that client wrote. Comparing two vectors shows whether one side has changes the other has not seen.
Comparison
compareVectors returns the relationship between two vectors, and the route branches on it:
| Result | Meaning | What the route does |
|---|---|---|
equal | Neither side has unseen changes | Returns success with no changes |
a_dominates | The client is ahead | Applies localChanges |
b_dominates | The server is ahead | Returns fullState for the client to adopt |
concurrent | Both sides have unseen changes | Checks for conflicts, then applies last-writer-wins |
Available Sync Functions
SessionChange
Changes are the units of sync. Each change targets one entity type with one operation.
Conflict Resolution
Conflict detection covers message changes with operation: "update" only, and runs when the vectors are concurrent.
- If an updated message differs between client and server, the route returns
status: "conflict"with the conflicting paths and applies nothing. Resolve on the client and sync again. - Otherwise the route applies last-writer-wins on time: if the client's first change is newer than the session's
updatedAt, the client's changes are applied and the vectors merged; if not, the server wins and the response carriesfullState.
Sync Modes
| Mode | Behavior |
|---|---|
merge | Default. Compare vectors and act as described above |
force_local | Apply the client's changes over the server state |
force_remote | Discard the client's changes and return the server state |
Offline Workflow
- The client works offline, recording changes with local timestamps.
- On reconnect, it calls
POST /syncwithlocalVectorandlocalChanges. - The server compares vectors to find concurrent edits.
- A conflicting message edit comes back as
status: "conflict"; otherwise the newer side wins. - The client adopts
newVector, andfullStatewhen it is present.
Read next
- Manage sessions — session management
- Message execution — SSE streaming
- Checkpoints — rollback if sync goes wrong
Was this page helpful?