Skip to main content

​
Versioning

The API is versioned in the URL path: /api/v1/… and /api/v2/…. The version prefix is part of the contract — endpoints documented on this site are stable within their major version:
  • No breaking changes within a version. Fields may be added to responses; existing fields keep their names and types. Treat unknown response fields as forward-compatible additions.
  • Breaking changes ship as a new path version. The old version keeps working through its deprecation window.
  • Undocumented /api/* endpoints belong to the Dexi app’s own session-authenticated API and carry no stability promise — build only against what’s documented here and in the OpenAPI spec.

​
Deprecation policy

When a documented endpoint is scheduled for removal:
  1. Its responses gain a Deprecation header, and a Sunset header (RFC 8594) with the removal date — at least 6 months out.
  2. This page lists the deprecation, its replacement, and a migration note.
  3. After the sunset date the endpoint returns 410 Gone with a JSON detail pointing at the replacement.
Nothing is currently deprecated.

​
Rate limits

Rate-limited endpoints return the draft-RFC rate-limit headers (draft-ietf-httpapi-ratelimit-headers) on every response, so clients can self-throttle instead of discovering limits by hitting them: Exceeding a limit returns 429 with a Retry-After header (seconds) and a JSON body:
Wait Retry-After seconds before retrying; don’t retry in a tight loop.

​
Errors

All errors are JSON with a top-level detail — a plain string on simple errors, or a structured object with a machine-readable code, human-readable message, and context fields:
Known codes: not_found, rate_limited, and note_limit (see Save a bookmark for the note_limit shape). Validation failures return 422 with FastAPI’s standard detail array. The full error model is typed in the OpenAPI spec.