OpenAPI And Contract

One runtime contract should feed the docs, SDKs, and examples.

Persistly keeps the public account/slot sync surface explicit. The docs should not reinterpret it differently from the SDK repos or the exported contract bundle.

Bundle Contents

These artifacts are the contract source of truth.

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

Docs Discipline

Write docs that point back to the contract instead of inventing their own layer.

The OpenAPI file defines the public account, slot, transfer-code, and sync operations.

The JSON examples mirror the same contract bundle instead of freehand docs prose.

SDKs should preserve the field names, statuses, and envelopes documented here exactly.

AI coding agents work better when these shapes stay explicit, repetitive, and stable.

Published Contract

The OpenAPI document should be public because it is for external tooling, not internal memory.

Use the public contract routes when generating clients, validating integrations, or giving AI agents a machine-readable API surface.

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

Public machine-readable routes are available at /openapi.yaml and /openapi.json.

Both routes are derived from the same canonical contract file, not hand-maintained duplicates.

External tools should consume the published routes instead of scraping docs prose.

The Go runtime does not auto-generate handlers from OpenAPI today; contract updates are still maintained intentionally in parallel with the API implementation.

Next Reads

Use the exact examples when implementing or generating code.

Account create, slot sync, transfer, conflict, and error examples are all documented as separate pages so agents and developers can lift one operation at a time.