API Examples

Exact request and response payloads for direct runtime work.

Use these examples when you are implementing a wrapper, testing OpenAPI parity, or debugging account-scoped HTTP behavior below the SDK facade.

account pathslot synctransfer codes
Create account exampleRuntime/API reference

Account-Scoped Examples

Start with the exact payloads that match the recommended runtime model.

These examples preserve the existing operation routes and show the request, response, conflict, and error envelopes directly.

Account path

POST /api/v1/accounts

Create account

Exact request and response with accountId, accountSessionToken, syncPolicy, account data, and first slot.

Preview reference

Slot sync

POST /accounts/{accountId}/slots/{slotId}/sync

Sync slot

Exact account-scoped slot sync request using X-Persistly-Account-Session.

Preview reference

Transfer

POST /account-transfer-codes/consume

Transfer code

Exact create and consume requests for short-lived anonymous account transfer.

Preview reference

Conflict

409 response

Conflict response

Exact 409 response and recovery model for retrying from the canonical server version.

Preview reference

Errors

error envelope

Error response

Exact structured error envelope with HTTP status, error.code, message, and details.

Preview reference

Contract Source

These pages are derived from the same OpenAPI-backed contract the SDKs follow.

Persistly keeps one public runtime surface. The docs examples, SDK types, and validation logic should all match the same contract bundle.

OpenAPI YAML

/openapi.yaml

Human-readable OpenAPI contract for SDK authors, code generation, and direct API review.

Open contract

OpenAPI JSON

/openapi.json

Machine-readable OpenAPI contract for tooling, generated clients, and direct API review.

Open contract

OpenAPI routes: /openapi.yaml and /openapi.json

Stable error envelope: error.code, error.message, error.details

Account envelope: accountId, optional accountSessionToken, account data, slots, syncPolicy

Slot envelope: slotId, slotInfo, data, version, status, and updatedAt

Published examples for account creation, slot sync, conflict, and error responses