Sync Save

Sync local changes with baseVersion, not blind overwrite.

Persistly uses optimistic concurrency. Clients send the version they last loaded and replace local canonical state with the returned response.

Request

POST /api/v1/saves/{saveId}/sync

baseVersion is required. Persistly uses it to decide whether the write is accepted or conflicts.

POST https://api.persistly.app/api/v1/saves/sv_01HXYZ/sync
Authorization: Bearer ps_test_your_runtime_key
Content-Type: application/json

{
  "baseVersion": 3,
  "metadata": {
    "characterName": "Ayla",
    "slot": 2
  },
  "state": {
    "gold": 120,
    "level": 2
  }
}

Response

200 OK

Accepted writes return status=accepted and the new canonical save envelope.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "accepted",
  "save": {
    "saveId": "sv_01HXYZ",
    "externalUserId": "auth0|123",
    "metadata": {
      "characterName": "Ayla",
      "slot": 2
    },
    "state": {
      "gold": 120,
      "level": 2
    },
    "version": 4,
    "createdAt": "2026-04-09T10:00:00Z",
    "updatedAt": "2026-04-09T10:05:00Z"
  }
}

Concurrency

Accepted syncs and conflicted syncs both return canonical save state.

Persistly uses optimistic concurrency with baseVersion.

The server returns explicit conflict semantics instead of silently overwriting state.

Sync responses always return the canonical current save payload.