Cloud Saves

Cloud Saves (Object Storage)

Object storage is a per-player JSON store for saves, settings, and other small state. Each object has a string key, a JSON value, and an integer version that ggscale bumps on every write. Calls live under /v1/storage/objects and need the API key and the session token.

• PUT /v1/storage/objects/{key} writes an object.
• GET /v1/storage/objects/{key} reads one.
• DELETE /v1/storage/objects/{key} removes one.
• GET /v1/storage/objects lists keys with a cursor.

Optimistic concurrency

To avoid clobbering a newer save, send the version you last read in an If-Match header. The write lands only if the stored version still matches. A mismatch returns 412 Precondition Failed. Leave If-Match off to write unconditionally.

Example

curl -s -X PUT http://localhost:8080/v1/storage/objects/save-slot-1 \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Session-Token: <access_token>" \
  -H "If-Match: 3" \
  -H "Content-Type: application/json" \
  -d '{"value":{"level":7,"coins":420}}'

A read returns the value with its current version:

{"key":"save-slot-1","value":{"level":7,"coins":420},"version":4,"updated_at":"2026-07-31T12:00:00Z"}

Common errors

• 412 Precondition Failed means someone wrote a newer version. Re-read, merge, and retry.
• 400 Bad Request means the If-Match header was not an integer version.

Full reference: the /v1/storage/objects operations.