Runtime API

Public client traffic stays constrained and explicit.

Persistly’s public runtime surface is intentionally small: create, load, and sync around known save IDs. Trusted lookup flows are separate.

Endpoints

The public runtime contract is intentionally small.

GET/healthz

Lightweight operational health endpoint for uptime checks and deployment verification.

200 OK
POST/api/v1/saves

Create a save record and receive the canonical save payload immediately.

201 Created400 Bad Request401 Unauthorized413 Payload Too Large429 Too Many Requests
GET/api/v1/saves/{saveId}

Load the canonical current save for a known save ID.

200 OK401 Unauthorized404 Not Found429 Too Many Requests
POST/api/v1/saves/{saveId}/sync

Submit state + metadata with a baseVersion and receive accepted or conflict semantics.

200 OK409 Conflict400 Bad Request401 Unauthorized404 Not Found413 Payload Too Large429 Too Many Requests

Exact Examples

Use operation-specific example pages when you need copy-pasteable request and response shapes.

These pages exist so developers and coding agents can implement one operation at a time without inferring missing fields or statuses.

Create save

Exact POST request and 201 response with a Bearer runtime key.

Load save

Exact GET request by saveId and the canonical save envelope response.

Sync save

Exact POST sync request with baseVersion and the accepted response shape.

409 conflict

Exact conflict response body so SDKs and agents can recover intentionally.

Error response

Shared error envelope with HTTP status, code, message, and optional details.

Auth Boundary

The public runtime is intentionally smaller than the operator/admin surface.

The API is permanent and public-facing for SDK traffic, but that does not mean every operation belongs in the public client path.

Runtime keys identify the environment for SDK traffic. They are not privileged admin credentials.

Clients should never use runtime keys to discover arbitrary player saves by externalUserId.

Trusted lookup and admin actions belong to the dashboard or future server-side operator flows.

Operational Limits

Payload caps and auth rules are part of the contract, not just suggestions.

State payload256 KB
Metadata payload16 KB
Conflict modelOptimistic concurrency
Runtime authBearer runtime key

Errors

Clients should treat HTTP status and error code as one contract.

HTTP 400invalid_request

The request body, parameters, or payload shape is invalid for the runtime contract.

HTTP 401unauthorized

The runtime key is missing, malformed, revoked, or does not belong to the target environment.

HTTP 404not_found

The referenced saveId does not exist in the environment identified by the runtime key.

HTTP 409conflict

The submitted baseVersion is stale. Persistly returns the canonical current save so the client can reconcile.

HTTP 413payload_too_large

The metadata or state payload exceeds Persistly's documented byte limits.

HTTP 429rate_limited

The client exceeded allowed request volume for the current environment or plan.

HTTP 500server_error

Persistly failed internally and the operation result should be treated as unknown.