Use the versioned API
ChurchHub's canonical HTTP contract is under /api/v1/. New first-party clients and external integrations should use versioned endpoints so breaking contract changes can be introduced through a new API major version rather than silently changing existing integrations.
Legacy compatibility aliases
Older paths such as /api/core/, /api/auth/, /api/health/ and /api/rates/latest/ remain temporarily available for previously released clients. They are compatibility aliases, not the preferred contract.
Deprecation signals
Legacy API responses include a standards-based Deprecation response header and a link to this migration policy. Requests to /api/v1/ are not marked deprecated.
A deprecation signal means migrate to the equivalent /api/v1/ endpoint; it does not mean the legacy endpoint has already stopped working.
Sunset policy
ChurchHub does not publish a retirement timestamp until one has been explicitly approved. When a removal date is scheduled, legacy responses also include a Sunset header. Migration guidance and the replacement versioned path are published before removal.
What requires a new API version
An intentional breaking change to an existing request or response contract requires a new API major version. Additive response fields, new endpoints, new optional request fields and backward-compatible behavior changes remain within the current major version.
OpenAPI contract
Swagger and generated OpenAPI documentation describe only the canonical versioned API, preventing duplicate legacy paths from appearing in generated clients. Development Swagger is available from the backend documentation route.
Confirm the running release
Use /api/v1/version/ to confirm which ChurchHub release an environment is actually serving. The response includes the product version, API major, short commit SHA, environment and optional deployment metadata. It contains no secrets and is not cached, so support and rollout checks can use it to distinguish releases reliably.