Sync API

The Sync API provides RESTful document management with automatic revision tracking. Documents are stored in RedisJSON and organized by service namespace.

Create Document

POST /api/sync/:service/documents

Request Body:

{
  "id": "optional-custom-id",
  "data": { "status": "active", "participantCount": 0 },
  "expiresAt": 1710100000000
}

All fields except data are optional. If id is omitted, a unique prefixed ID is generated automatically.

Response: 201 Created

{
  "service": "session",
  "id": "doc_a1b2c3d4",
  "revision": 1,
  "data": { "status": "active", "participantCount": 0 },
  "createdAt": 1710000000000,
  "updatedAt": 1710000000000
}

Get Document

GET /api/sync/:service/documents/:id

Response:

{
  "service": "session",
  "id": "doc_a1b2c3d4",
  "revision": 3,
  "data": { "status": "active", "participantCount": 5 },
  "createdAt": 1710000000000,
  "updatedAt": 1710001000000
}

Replace Document

Replace the entire document data. Increments revision.

PUT /api/sync/:service/documents/:id

Request Body:

{
  "data": { "status": "ended", "endedAt": 1710002000000 },
  "expectedRevision": 3
}

The optional expectedRevision enables optimistic concurrency — if the document's current revision doesn't match, a 409 Conflict is returned.

Merge Document

Deep merge partial data into the existing document.

PATCH /api/sync/:service/documents/:id/merge

Request Body:

{
  "data": { "notes": "Session completed" },
  "expectedRevision": 3
}

Only the specified fields are updated; all other fields remain unchanged.

Mutate Document

Apply structured mutations to the document.

POST /api/sync/:service/documents/:id/mutate

Request Body:

{
  "mutations": [
    { "op": "set", "path": "/status", "value": "ended" },
    { "op": "increment", "path": "/participantCount", "value": -1 }
  ],
  "expectedRevision": 4
}

Delete Document

Soft-delete a document (sets deleted: true).

DELETE /api/sync/:service/documents/:id

Response: 200 OK

Error Responses

Status	Meaning
`404`	Document not found
`409`	Revision conflict (expectedRevision mismatch)
`400`	Invalid request body