Storage flows

Objects live at (owner, collection, key) and hold one JSON value (usually an object): save slots, settings, inventories. Players only ever see their own objects.

Versions. Every write bumps the object's version (1 for a new object).

You want	Send
last write wins	`PUT` `{"value":…}`
create only if it does not exist	`PUT` `{"value":…, "if_version":0}`
overwrite only the version you loaded	`PUT` `{"value":…, "if_version":<version you read>}`
delete only the version you loaded	`DELETE …?if_version=<version>`

On a mismatch the answer is 409 version_conflict with {"current_version":N} (absent when the object does not exist) and nothing changes. Of several simultaneous conditional writes exactly one wins.

Save-game flow (two devices safe):

GET /v1/storage/saves/slot-1 → {"value":{…},"version":3,…} (404: no save yet; treat as version 0).
The player plays; the client keeps version = 3.
PUT /v1/storage/saves/slot-1 {"value":{…new…},"if_version":3} → {"version":4,…}; keep 4.
On 409: another device saved meanwhile. GET again, let the player choose (or merge), then PUT with the new if_version.

Listing. GET /v1/storage/saves returns StorageObjectInfo items (key, version, size, time, no values) ordered by key: use it for a "load game" screen, then GET the chosen object or POST /v1/storage/_batch/get several at once.

Batches. POST /v1/storage/_batch/put writes up to 16 objects in one transaction: either every write happens or none (the error's details.index names the failing item).

Server-locked objects. Objects with "write":"server" and everything in server-owned collections (default: server and server.*) are written only by server code and admins. A player can read them; writing, creating or deleting them answers 403 forbidden.

Binary data (images, compressed saves): encode it as a string yourself (for example base64, +33 %, which counts against the 256 KiB value limit).

Generated from API.md (repository commit e25edb9, file sha256 3db87f7bba70).