OpenAPI file: persistly-api.yaml
OpenAPI And Contract
One runtime contract should feed the docs, SDKs, and examples.
Persistly keeps the public save-sync surface intentionally small. 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.
Stable error envelope: error.code, error.message, error.details
Canonical save envelope: save.saveId, metadata, state, version, timestamps
Published examples for create, save envelope, 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 create, load, 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.
Public machine-readable routes: /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.
Create, load, sync, conflict, and error examples are all documented as separate pages so agents and developers can lift one operation at a time.