Create Save

Create the save once, then persist the returned saveId locally.

Public clients should create a save once, store the saveId they receive, and treat later load and sync calls as explicit saveId operations.

Request

POST /api/v1/saves

Use a stage or live runtime key as a Bearer token. state is required; externalUserId and metadata are optional.

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

{
  "externalUserId": "auth0|123",
  "metadata": {
    "characterName": "Ayla",
    "slot": 2
  },
  "state": {
    "gold": 100,
    "level": 1
  }
}

Response

201 Created

Persistly returns the canonical save envelope immediately. Persist save.saveId locally.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "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"
  }
}

Rules

Create is the only public operation that introduces a new saveId.

Persistly is a cloud save platform for games, not a real-time multiplayer backend.

Public clients create, load, and sync by explicit saveId only.

externalUserId is an optional developer-owned reference, not a public lookup key.

Trusted lookup, broad search, and operator workflows belong to the dashboard/admin side.