API Contract

API contract

• The OpenAPI document generated from the code (chronexus-server openapi) is the contract. api/openapi.json and api/types.ts are generated by python3 scripts/contract.py and checked with --check; a drift fails the check.
• GET /api/v1/meta reports the API version and capabilities; clients refuse servers that lack what they need (for example incremental-sync).
• Human-readable reference: docs/API.md. The desktop client's view of the same contract: the app's docs/SYNC_API.md.

Compatibility rules

• Add, do not break: new fields are optional, new behaviour is announced by a capability.
• Requests reject unknown fields, so clients must not send fields the server does not document.
• Status codes carry meaning the client relies on: 401 sign in again, 403/404 on a campaign read means access is gone, 409 conflict (with the current revision), 410 expired invitation or stale cursor, 429 slow down.