Skip to Content
Versioning & Changelog

Versioning & Changelog

Versioning policy

  • Path-based versioning. Every endpoint lives under a version prefix: today that is /api/v1. The version is part of the URL, never a header.
  • Strict version routing. A request targeting an unsupported version is rejected with UNSUPPORTED_VERSION (HTTP 400). It is never rerouted to a different version.
  • Current version: v1.

Non-breaking (additive) changes

These can happen within v1 without a new version:

  • Adding a new endpoint or optional query parameter.
  • Adding a new field to a response projection.
  • Adding a new scope or a new error code.
  • Relaxing a validation constraint.

Design your integration to tolerate additive changes: ignore unknown response fields and branch on error.code rather than message text.

Breaking changes

Introduced under a new version path (e.g. /api/v2); v1 continues to be served during any announced deprecation window:

  • Removing or renaming an endpoint, field, or scope.
  • Changing a field’s type or meaning.
  • Tightening validation that rejects previously valid requests.
  • Changing the required scope for an existing endpoint.

Changelog

v1 — initial release

  • Versioned, modular, consent-gated API under /api/v1.
  • 13 read scopes, one per data domain.
  • OAuth2 authorization-code and client-credentials flows; SHA-256-only secret and token storage; per-grant revocation cascade.
  • Per-clientId rate limiting (600/min) additional to the global 2000/min/IP limit.
  • Append-only audit logging of consent changes and PHI access.
  • Read-only surface (no write scopes in v1).
OpenAPI Spec