{ "openapi": "3.2.0", "info": { "title": "Persistly Runtime API", "summary": "Save-sync API for account-first, offline-first game persistence.", "description": "Persistly is a narrow save-sync and persistence layer for games.\nThe public runtime API is account-first: create an account, store the\naccountSessionToken, then sync accountData and one or more slot records.\nIt is designed for single-player, idle, incremental, async, and\ncross-device resume flows rather than real-time multiplayer state or\nauthoritative game simulation.\n", "contact": { "name": "Persistly Support", "url": "https://docs.persistly.app", "email": "support@persistly.app" }, "license": { "name": "Proprietary", "url": "https://persistly.app/terms" }, "version": "0.4.0" }, "servers": [ { "url": "https://api.persistly.app", "description": "Public production runtime API" } ], "tags": [ { "name": "Operations", "description": "Public operational endpoints for availability checks." }, { "name": "Accounts", "description": "Account sessions, accountData, slots, slotInfo, and slot data for player-owned save sync." }, { "name": "Account Auth", "description": "Provider-token exchange for account sessions." }, { "name": "Billing Webhooks", "description": "Provider webhook endpoints used by Persistly billing automation." } ], "paths": { "/healthz": { "get": { "operationId": "healthCheck", "tags": [ "Operations" ], "summary": "Health check", "description": "Lightweight readiness endpoint for uptime checks and deployment verification.", "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "examples": { "default": { "summary": "API is healthy", "value": { "ok": true } } } } } } } } }, "/api/v1/runtime-config": { "get": { "operationId": "getRuntimeConfig", "tags": [ "Accounts" ], "summary": "Get runtime config", "description": "Return SDK runtime configuration such as dashboard-controlled sync policy and the active environment game config.", "security": [ { "RuntimeKey": [] } ], "parameters": [ { "name": "gameConfigVersion", "in": "query", "required": false, "description": "Client's cached active game config version. When it matches, the response omits the config payload and marks it unchanged.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Runtime configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeConfigResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/accounts": { "post": { "operationId": "createAccount", "tags": [ "Accounts" ], "summary": "Create account", "description": "Create a runtime account and one account session token. A first slot can be created in the same request by sending the optional nested slot object.", "security": [ { "RuntimeKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountRequest" }, "examples": { "default": { "summary": "Create an account with an autosave slot", "value": { "playerRef": "player-184", "externalAccountRef": { "provider": "studio_account", "subject": "player-123" }, "accountData": { "diamonds": 1200, "settings": { "music": true } }, "slot": { "slotId": "autosave", "slotInfo": { "label": "Autosave", "level": 5, "location": "Crystal Vault" }, "data": { "checkpoint": "vault", "coins": 418 } } } } } } } }, "responses": { "201": { "description": "Account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountEnvelopeResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/accounts/auth/session": { "post": { "operationId": "exchangeAccountAuthSession", "tags": [ "Account Auth" ], "summary": "Exchange provider token for account session", "description": "Verify a configured Firebase Auth ID token, Supabase access token, or Auth0 token and return a normal Persistly account session.\nSDK helpers are preferred for most games. Direct HTTP is intended for custom engines,\ncustom SDKs, and advanced integrations that intentionally manage accountId and accountSessionToken.\n\nFree workspaces can test Auth Bridge with stage runtime keys. Production Auth Bridge\nrequires a paid workspace plan and returns auth_bridge_requires_paid_plan before provider\ntoken verification runs.\n\nTo link a verified identity to the current account, send both X-Persistly-Account-ID and\nX-Persistly-Account-Session headers. Do not send accountId or accountSessionToken in the JSON body.\n", "security": [ { "RuntimeKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/AccountIdHeader" }, { "$ref": "#/components/parameters/AccountSessionOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionRequest" }, "examples": { "firebase": { "summary": "Firebase Auth ID token exchange", "value": { "provider": "firebase", "token": "FIREBASE_ID_TOKEN_PLACEHOLDER", "deviceLabel": "iPhone" } }, "supabase": { "summary": "Supabase access token exchange", "value": { "provider": "supabase", "token": "SUPABASE_ACCESS_TOKEN_PLACEHOLDER", "deviceLabel": "Steam Deck" } }, "auth0": { "summary": "Auth0 token exchange", "value": { "provider": "auth0", "token": "AUTH0_TOKEN_PLACEHOLDER", "deviceLabel": "Browser" } } } } } }, "responses": { "200": { "description": "Account session issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponse" }, "examples": { "linked": { "summary": "Existing or newly linked account session", "value": { "accountId": "acc_01HXYZ", "accountSessionToken": "pst_01HSESSION", "isNewAccount": false, "linkedProvider": "firebase", "wasProviderNewForAccount": true, "syncPolicy": { "minRemoteSyncIntervalSeconds": 60, "forceSyncCooldownSeconds": 10 } } } } } } }, "400": { "description": "Invalid request or provider token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidProvider": { "summary": "Unknown provider key", "value": { "error": { "code": "provider_not_supported", "message": "Auth provider is not supported.", "details": { "field": "provider" } } } }, "invalidToken": { "summary": "Provider token failed verification", "value": { "error": { "code": "firebase_token_invalid", "message": "Firebase ID token is invalid." } } }, "projectMismatch": { "summary": "Provider project mismatch", "value": { "error": { "code": "supabase_project_mismatch", "message": "Supabase token was issued for a different project." } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "Production Auth Bridge requires a paid workspace plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "authBridgeRequiresPaidPlan": { "summary": "Free workspace using a production runtime key", "value": { "error": { "code": "auth_bridge_requires_paid_plan", "message": "Production Auth Bridge requires a paid workspace plan.", "details": { "environment": "prod", "plan": "free", "upgradePath": "https://dashboard.persistly.app/settings/billing#plans" } } } } } } } }, "409": { "description": "Auth provider is not ready or provider identity is already linked to another account", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/AccountAuthConflictResponse" } ] }, "examples": { "providerNotConfigured": { "summary": "Provider missing", "value": { "error": { "code": "provider_not_configured", "message": "Auth provider is not configured for this environment.", "details": { "provider": "firebase" } } } }, "providerNotEnabled": { "summary": "Provider disabled", "value": { "error": { "code": "provider_not_enabled", "message": "Auth provider is disabled for this environment." } } }, "authConflict": { "summary": "Provider identity belongs to another account", "value": { "error": { "code": "account_auth_conflict", "message": "Auth identity is already linked to another account." } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/accounts/auth/providers": { "get": { "operationId": "listAccountAuthProviders", "tags": [ "Account Auth" ], "summary": "List linked auth providers for the current account", "description": "Return safe provider metadata for the current Persistly account session.\nThe response excludes raw provider subjects, hashes, tokens, slot data, account data, and internal save ids.\n", "security": [ { "RuntimeKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/AccountIdHeader" }, { "$ref": "#/components/parameters/AccountSession" } ], "responses": { "200": { "description": "Linked providers", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedAuthProvider" } }, "examples": { "default": { "summary": "Linked Firebase provider", "value": [ { "provider": "firebase", "display": { "label": "Firebase", "emailHint": "p***@example.com" }, "linkedAt": "2026-06-06T12:00:00Z", "lastUsedAt": "2026-06-06T12:30:00Z" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/accounts/{accountId}": { "get": { "operationId": "loadAccount", "tags": [ "Accounts" ], "summary": "Load account", "description": "Load accountData and active slot summaries for an account session.", "security": [ { "RuntimeKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/AccountSession" } ], "responses": { "200": { "description": "Account loaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteAccount", "tags": [ "Accounts" ], "summary": "Delete account", "description": "Permanently delete an account, revoke its account sessions, and erase all attached slots.", "security": [ { "RuntimeKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/AccountSession" } ], "responses": { "200": { "description": "Account deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/accounts/{accountId}/data/sync": { "post": { "operationId": "syncAccountData", "tags": [ "Accounts" ], "summary": "Sync accountData", "description": "Replace or shallow-patch account-wide private gameplay data with optimistic concurrency.", "security": [ { "RuntimeKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/AccountSession" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncAccountDataRequest" } } } }, "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncAcceptedResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountConflictResponse" } } } }, "410": { "$ref": "#/components/responses/Gone" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/accounts/{accountId}/transfer-codes": { "post": { "operationId": "createAccountTransferCode", "tags": [ "Accounts" ], "summary": "Create transfer code", "description": "Create a short-lived, single-use transfer code from an existing account session so another device can attach the same account without public lookup.", "security": [ { "RuntimeKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/AccountSession" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransferCodeRequest" } } } }, "responses": { "201": { "description": "Transfer code created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransferCodeResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/account-transfer-codes/consume": { "post": { "operationId": "consumeAccountTransferCode", "tags": [ "Accounts" ], "summary": "Consume transfer code", "description": "Consume a short-lived account transfer code and issue a new account session token for the same account. This is not username, playerRef, or externalAccountRef lookup.", "security": [ { "RuntimeKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumeTransferCodeRequest" } } } }, "responses": { "200": { "description": "Transfer code consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountEnvelopeResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/accounts/{accountId}/slots": { "get": { "operationId": "listAccountSlots", "tags": [ "Accounts" ], "summary": "List active slots", "description": "Return active slot summaries for account selection screens. Full slot data is loaded from the slot route.", "security": [ { "RuntimeKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/AccountSession" } ], "responses": { "200": { "description": "Active slots", "content": { "application/json": { "schema": { "type": "object", "required": [ "accountId", "slots" ], "properties": { "accountId": { "type": "string", "pattern": "^acc_[A-Za-z0-9_.-]+$" }, "slots": { "type": "array", "items": { "$ref": "#/components/schemas/AccountSlotSummary" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createAccountSlot", "tags": [ "Accounts" ], "summary": "Create slot", "description": "Create a named active slot under an account. Archived slots do not reserve slotId values.", "security": [ { "RuntimeKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/AccountSession" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountSlotRequest" } } } }, "responses": { "201": { "description": "Slot created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlotResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/SlotAlreadyExists" }, "410": { "$ref": "#/components/responses/Gone" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/accounts/{accountId}/slots/{slotId}": { "get": { "operationId": "loadAccountSlot", "tags": [ "Accounts" ], "summary": "Load slot", "description": "Load one active slot's slotInfo and full playable data.", "security": [ { "RuntimeKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/SlotId" }, { "$ref": "#/components/parameters/AccountSession" } ], "responses": { "200": { "description": "Slot loaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlotResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteAccountSlot", "tags": [ "Accounts" ], "summary": "Delete slot", "description": "Permanently delete one slot under an account.", "security": [ { "RuntimeKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/SlotId" }, { "$ref": "#/components/parameters/AccountSession" } ], "responses": { "200": { "description": "Slot deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSlotResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/accounts/{accountId}/slots/{slotId}/sync": { "post": { "operationId": "syncAccountSlot", "tags": [ "Accounts" ], "summary": "Sync slot", "description": "Sync an active slot's slotInfo and data with optimistic concurrency.", "security": [ { "RuntimeKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/SlotId" }, { "$ref": "#/components/parameters/AccountSession" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncAccountSlotRequest" } } } }, "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncAcceptedResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Conflict or archived slot", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SlotConflictResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "archived": { "summary": "Archived slot cannot be synced", "value": { "error": { "code": "slot_archived", "message": "Archived slots cannot be synced.", "details": { "slotId": "autosave" } } } } } } } }, "410": { "$ref": "#/components/responses/Gone" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/v1/accounts/{accountId}/slots/{slotId}/archive": { "post": { "operationId": "archiveAccountSlot", "tags": [ "Accounts" ], "summary": "Archive slot", "description": "Retire one active slot. Archived slots are not returned by active slot routes and cannot be synced through the normal slot sync route.", "security": [ { "RuntimeKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/SlotId" }, { "$ref": "#/components/parameters/AccountSession" } ], "responses": { "200": { "description": "Slot archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/webhooks/stripe": { "post": { "operationId": "handleStripeWebhook", "tags": [ "Billing Webhooks" ], "summary": "Stripe webhook", "description": "Receives signed Stripe events and updates Persistly billing state and plan entitlements.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Event accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "received" ], "properties": { "received": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "securitySchemes": { "RuntimeKey": { "type": "http", "scheme": "bearer" } }, "parameters": { "AccountId": { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^acc_[A-Za-z0-9_.-]+$" } }, "SlotId": { "name": "slotId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,64}$" } }, "AccountSession": { "name": "X-Persistly-Account-Session", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Per-device account session token returned when an account is created." }, "AccountSessionOptional": { "name": "X-Persistly-Account-Session", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional current account session token. Use with X-Persistly-Account-ID when linking an auth identity to the current account." }, "AccountIdHeader": { "name": "X-Persistly-Account-ID", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^acc_[A-Za-z0-9_.-]+$" }, "description": "Optional current account id. Use with X-Persistly-Account-Session when linking an auth identity to the current account." } }, "schemas": { "HealthResponse": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "ExternalAccountRef": { "type": "object", "required": [ "provider", "subject" ], "description": "Optional non-authoritative identity reference stored for future trusted auth migration. It is not public lookup or proof of ownership.", "properties": { "provider": { "type": "string" }, "subject": { "type": "string" } } }, "SyncPolicy": { "type": "object", "required": [ "minRemoteSyncIntervalSeconds", "forceSyncCooldownSeconds", "syncOnAppBackground", "syncOnAppForeground", "syncOnReconnect", "maxQueuedLocalSnapshots" ], "properties": { "minRemoteSyncIntervalSeconds": { "type": "integer", "minimum": 1 }, "forceSyncCooldownSeconds": { "type": "integer", "minimum": 1 }, "syncOnAppBackground": { "type": "boolean" }, "syncOnAppForeground": { "type": "boolean" }, "syncOnReconnect": { "type": "boolean" }, "maxQueuedLocalSnapshots": { "type": "integer", "minimum": 1 } } }, "RuntimeConfigResponse": { "type": "object", "required": [ "syncPolicy" ], "properties": { "syncPolicy": { "$ref": "#/components/schemas/SyncPolicy" }, "gameConfig": { "$ref": "#/components/schemas/GameConfig" } } }, "GameConfig": { "type": "object", "required": [ "enabled", "version", "sizeBytes" ], "properties": { "enabled": { "type": "boolean" }, "unchanged": { "type": "boolean" }, "version": { "type": "integer", "minimum": 0 }, "checksum": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 }, "publishedAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true } } }, "CreateAccountRequest": { "type": "object", "properties": { "playerRef": { "type": "string", "description": "Optional non-secret developer reference. It is not public lookup or auth." }, "externalAccountRef": { "$ref": "#/components/schemas/ExternalAccountRef" }, "accountData": { "type": "object", "x-max-bytes": 262144, "additionalProperties": true }, "slot": { "$ref": "#/components/schemas/CreateAccountInitialSlot" } } }, "AuthProvider": { "type": "string", "enum": [ "firebase", "supabase", "auth0" ] }, "AuthSessionRequest": { "type": "object", "required": [ "provider", "token" ], "description": "Provider token exchange request. Do not include accountId or accountSessionToken in the JSON body; use headers for current account linking.", "properties": { "provider": { "$ref": "#/components/schemas/AuthProvider" }, "token": { "type": "string", "description": "Raw provider token, such as a Firebase ID token, Supabase access token, or Auth0 token. Never log or persist this value." }, "deviceLabel": { "type": "string", "maxLength": 80, "description": "Optional player-visible device label for the issued account session." } }, "additionalProperties": false }, "AuthSessionResponse": { "type": "object", "required": [ "accountId", "accountSessionToken", "isNewAccount", "linkedProvider", "wasProviderNewForAccount" ], "properties": { "accountId": { "type": "string", "pattern": "^acc_[A-Za-z0-9_.-]+$" }, "accountSessionToken": { "type": "string", "description": "Normal Persistly account session token for subsequent account/slot routes. Store locally; do not log it." }, "isNewAccount": { "type": "boolean", "description": "True when the exchange created a new account because there was no current valid account session and no existing identity link." }, "linkedProvider": { "$ref": "#/components/schemas/AuthProvider" }, "wasProviderNewForAccount": { "type": "boolean", "description": "True when this provider identity was newly linked to the returned account." } } }, "LinkedAuthProvider": { "type": "object", "required": [ "provider", "display", "linkedAt" ], "properties": { "provider": { "$ref": "#/components/schemas/AuthProvider" }, "display": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string" }, "emailHint": { "type": "string" } }, "additionalProperties": false }, "linkedAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": "string", "format": "date-time" } } }, "CreateAccountInitialSlot": { "type": "object", "required": [ "slotId", "data" ], "properties": { "slotId": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,64}$" }, "slotInfo": { "type": "object", "x-max-bytes": 16384, "additionalProperties": true }, "data": { "type": "object", "x-max-bytes": 262144, "additionalProperties": true } } }, "CreateAccountSlotRequest": { "type": "object", "required": [ "slotId", "data" ], "properties": { "slotId": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,64}$" }, "slotInfo": { "type": "object", "x-max-bytes": 16384, "additionalProperties": true }, "data": { "type": "object", "x-max-bytes": 262144, "additionalProperties": true } } }, "SyncAccountDataRequest": { "type": "object", "required": [ "baseVersion" ], "description": "Exactly one of accountData or accountDataPatch may be present.", "properties": { "baseVersion": { "type": "integer", "minimum": 1 }, "accountData": { "type": "object", "x-max-bytes": 262144, "additionalProperties": true }, "accountDataPatch": { "type": "object", "x-max-bytes": 262144, "description": "Shallow top-level patch. Null values remove top-level keys.", "additionalProperties": true } } }, "SyncAccountSlotRequest": { "type": "object", "required": [ "baseVersion", "data" ], "properties": { "baseVersion": { "type": "integer", "minimum": 1 }, "slotInfo": { "type": "object", "x-max-bytes": 16384, "additionalProperties": true }, "data": { "type": "object", "x-max-bytes": 262144, "additionalProperties": true } } }, "CreateTransferCodeRequest": { "type": "object", "properties": { "deviceLabel": { "type": "string", "maxLength": 80, "description": "Optional player-visible device label for activity/audit context. Do not send secrets." }, "ttlSeconds": { "type": "integer", "minimum": 60, "maximum": 1800, "description": "Optional requested expiry. Persistly may clamp this to the project default." } } }, "CreateTransferCodeResponse": { "type": "object", "required": [ "transferCode", "expiresAt", "expiresInSeconds" ], "properties": { "transferCode": { "type": "string", "description": "Short-lived one-time code. Show it to the player once; do not log it.", "example": "P7K2D-M9Q4R" }, "expiresAt": { "type": "string", "format": "date-time" }, "expiresInSeconds": { "type": "integer", "minimum": 1 } } }, "ConsumeTransferCodeRequest": { "type": "object", "required": [ "transferCode" ], "properties": { "transferCode": { "type": "string", "description": "Short-lived one-time code from the device that already has the account session.", "example": "P7K2D-M9Q4R" }, "deviceLabel": { "type": "string", "maxLength": 80, "description": "Optional player-visible label for the new device/session." } } }, "AccountSlotSummary": { "type": "object", "required": [ "slotId", "slotInfo", "version", "status", "updatedAt" ], "properties": { "slotId": { "type": "string" }, "slotInfo": { "type": "object", "additionalProperties": true }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "active" ] }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AccountResponse": { "type": "object", "required": [ "accountId", "accountData", "slots", "version" ], "properties": { "accountId": { "type": "string", "pattern": "^acc_[A-Za-z0-9_.-]+$" }, "accountData": { "type": "object", "additionalProperties": true }, "slots": { "type": "array", "items": { "$ref": "#/components/schemas/AccountSlotSummary" } }, "version": { "type": "integer", "minimum": 1 } } }, "SlotResponse": { "type": "object", "required": [ "slotId", "slotInfo", "data", "version", "status", "updatedAt" ], "properties": { "slotId": { "type": "string" }, "slotInfo": { "type": "object", "additionalProperties": true }, "data": { "type": "object", "additionalProperties": true }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "active" ] }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AccountEnvelopeResponse": { "type": "object", "required": [ "accountId", "accountSessionToken", "account", "syncPolicy" ], "properties": { "accountId": { "type": "string", "pattern": "^acc_[A-Za-z0-9_.-]+$" }, "accountSessionToken": { "type": "string", "description": "Returned only on account creation. Store locally; it authorizes access only to this account and its slots." }, "account": { "$ref": "#/components/schemas/AccountResponse" }, "slot": { "$ref": "#/components/schemas/SlotResponse" }, "syncPolicy": { "$ref": "#/components/schemas/SyncPolicy" } } }, "DeleteSlotResponse": { "type": "object", "required": [ "accountId", "slotId", "deletedAt", "alreadyDeleted", "cleanupQueued" ], "properties": { "accountId": { "type": "string" }, "slotId": { "type": "string" }, "deletedAt": { "type": "string", "format": "date-time" }, "alreadyDeleted": { "type": "boolean" }, "cleanupQueued": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/AccountResponse" } } }, "DeleteAccountResponse": { "type": "object", "required": [ "accountId", "deletedAt", "deletedSlotCount", "alreadyDeleted", "cleanupQueued" ], "properties": { "accountId": { "type": "string" }, "deletedAt": { "type": "string", "format": "date-time" }, "deletedSlotCount": { "type": "integer", "minimum": 0 }, "alreadyDeleted": { "type": "boolean" }, "cleanupQueued": { "type": "boolean" } } }, "SyncAcceptedResponse": { "type": "object", "required": [ "status", "version", "updatedAt", "historyRetained" ], "properties": { "status": { "type": "string", "enum": [ "accepted" ] }, "version": { "type": "integer", "minimum": 1 }, "updatedAt": { "type": "string", "format": "date-time" }, "historyRetained": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "AccountConflictResponse": { "type": "object", "required": [ "status", "account", "version", "updatedAt", "details" ], "properties": { "status": { "type": "string", "enum": [ "conflict" ] }, "account": { "$ref": "#/components/schemas/AccountResponse" }, "version": { "type": "integer", "minimum": 1 }, "updatedAt": { "type": "string", "format": "date-time" }, "details": { "$ref": "#/components/schemas/AccountConflictDetails" } } }, "SlotConflictResponse": { "type": "object", "required": [ "status", "slot", "version", "updatedAt", "details" ], "properties": { "status": { "type": "string", "enum": [ "conflict" ] }, "slot": { "$ref": "#/components/schemas/SlotResponse" }, "version": { "type": "integer", "minimum": 1 }, "updatedAt": { "type": "string", "format": "date-time" }, "details": { "$ref": "#/components/schemas/SlotConflictDetails" } } }, "AccountConflictDetails": { "type": "object", "required": [ "reason", "serverAccountData" ], "description": "Conflict branches for account-wide data. The client branch is either the submitted replacement object or the submitted patch.", "oneOf": [ { "required": [ "clientAccountData" ] }, { "required": [ "clientAccountDataPatch" ] } ], "properties": { "reason": { "type": "string", "enum": [ "base_version_mismatch" ] }, "serverAccountData": { "type": "object", "additionalProperties": true }, "clientAccountData": { "type": "object", "additionalProperties": true }, "clientAccountDataPatch": { "type": "object", "additionalProperties": true } } }, "SlotConflictDetails": { "type": "object", "required": [ "reason", "serverSlot", "clientSlot" ], "description": "Conflict branches for one slot. The server branch includes the current slot preview and full data; the client branch includes submitted data and optional slotInfo.", "properties": { "reason": { "type": "string", "enum": [ "base_version_mismatch" ] }, "serverSlot": { "$ref": "#/components/schemas/ServerSlotConflictBranch" }, "clientSlot": { "$ref": "#/components/schemas/ClientSlotConflictBranch" } } }, "ServerSlotConflictBranch": { "type": "object", "required": [ "slotInfo", "data" ], "properties": { "slotInfo": { "type": "object", "additionalProperties": true }, "data": { "type": "object", "additionalProperties": true } } }, "ClientSlotConflictBranch": { "type": "object", "required": [ "data" ], "properties": { "slotInfo": { "type": "object", "additionalProperties": true }, "data": { "type": "object", "additionalProperties": true } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "conflict", "slot_already_exists", "slot_archived", "account_deleted", "account_suspended", "slot_deleted", "transfer_code_invalid", "transfer_code_expired", "transfer_code_consumed", "transfer_code_rate_limited", "transfer_code_disabled", "invalid_account_session", "provider_not_supported", "provider_not_enabled", "provider_not_configured", "provider_config_invalid", "auth_bridge_requires_paid_plan", "firebase_project_id_required", "firebase_project_id_invalid", "firebase_token_missing", "firebase_token_invalid", "firebase_token_expired", "firebase_project_mismatch", "supabase_project_url_required", "supabase_project_url_invalid", "supabase_token_missing", "supabase_token_invalid", "supabase_token_expired", "supabase_project_mismatch", "supabase_audience_mismatch", "auth0_domain_required", "auth0_domain_invalid", "auth0_token_missing", "auth0_token_invalid", "auth0_token_expired", "auth0_issuer_mismatch", "auth0_audience_mismatch", "account_auth_conflict", "rate_limited", "monthly_quota_exceeded", "payload_too_large", "server_error" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } }, "AccountAuthConflictResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details" ], "properties": { "code": { "type": "string", "enum": [ "account_auth_conflict" ] }, "message": { "type": "string" }, "details": { "type": "object", "required": [ "summary" ], "properties": { "summary": { "$ref": "#/components/schemas/AccountAuthConflictSummary" } } } } } } }, "AccountAuthConflictSummary": { "type": "object", "required": [ "linkedProvider", "linkedProviderCount", "linkedAccount" ], "description": "Safe conflict summary. It intentionally excludes slotInfo, data, provider subject, subject hashes, raw tokens, and internal ids.", "properties": { "linkedProvider": { "$ref": "#/components/schemas/AuthProvider" }, "linkedProviderCount": { "type": "integer", "minimum": 1 }, "linkedAccount": { "type": "object", "required": [ "activeSlotCount" ], "properties": { "activeSlotCount": { "type": "integer", "minimum": 0 }, "lastActivityAt": { "type": "string", "format": "date-time" } } }, "firstLinkedAt": { "type": "string", "format": "date-time" }, "lastLinkedAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": "string", "format": "date-time" } } } }, "responses": { "InvalidRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Invalid request body", "value": { "error": { "code": "invalid_request", "message": "Request body is invalid." } } } } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Missing or invalid runtime key", "value": { "error": { "code": "unauthorized", "message": "Runtime key is invalid or missing." } } } } } } }, "NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Resource not found", "value": { "error": { "code": "not_found", "message": "Resource not found." } } } } } } }, "Forbidden": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Account session cannot access this resource", "value": { "error": { "code": "forbidden", "message": "Account session cannot access this resource." } } } } } } }, "AuthProviderNotConfigured": { "description": "Auth provider is not configured or not enabled for this runtime key environment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Provider missing or disabled", "value": { "error": { "code": "provider_not_configured", "message": "Auth provider is not configured for this environment.", "details": { "provider": "firebase" } } } } } } } }, "AccountAuthConflict": { "description": "Provider identity is already linked to a different account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountAuthConflictResponse" }, "examples": { "default": { "summary": "Identity linked to another account", "value": { "error": { "code": "account_auth_conflict", "message": "Auth identity is already linked to another account.", "details": { "summary": { "linkedProvider": "firebase", "linkedProviderCount": 1, "linkedAccount": { "activeSlotCount": 3, "lastActivityAt": "2026-06-06T12:30:00Z" }, "firstLinkedAt": "2026-06-06T12:00:00Z", "lastLinkedAt": "2026-06-06T12:00:00Z", "lastUsedAt": "2026-06-06T12:30:00Z" } } } } } } } } }, "Gone": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "accountDeleted": { "summary": "Account was deleted", "value": { "error": { "code": "account_deleted", "message": "Account was deleted.", "details": { "accountId": "acc_01HXYZ" } } } }, "slotDeleted": { "summary": "Slot was deleted", "value": { "error": { "code": "slot_deleted", "message": "Slot was deleted.", "details": { "slotId": "autosave" } } } } } } } }, "SlotAlreadyExists": { "description": "Slot already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Duplicate active slot", "value": { "error": { "code": "slot_already_exists", "message": "An active slot already exists for this slotId.", "details": { "slotId": "autosave" } } } } } } } }, "Conflict": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "slotArchived": { "summary": "Slot is archived", "value": { "error": { "code": "slot_archived", "message": "Slot is archived." } } } } } } }, "PayloadTooLarge": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Data exceeds size limit", "value": { "error": { "code": "payload_too_large", "message": "Data exceeds the maximum allowed size.", "details": { "field": "data", "maxBytes": 262144 } } } } } } } }, "PaymentRequired": { "description": "Monthly runtime quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "monthlyQuotaExceeded": { "summary": "Monthly runtime quota exceeded", "value": { "error": { "code": "monthly_quota_exceeded", "message": "Monthly runtime request quota exceeded.", "details": { "planTier": "free", "used": 100000, "limit": 100000 } } } } } } } }, "RateLimited": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Rate limit exceeded", "value": { "error": { "code": "rate_limited", "message": "Too many requests. Try again later." } } } } } } }, "ServerError": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Unexpected server error", "value": { "error": { "code": "server_error", "message": "Unexpected server error." } } } } } } } } } }