API versioning
Today /api/v1/ is the only public surface. We do not use a version header, there are no parallel versions and we have not yet published a formal deprecation policy.
Summary
Versioning lives in the URL. Every call starts with /api/v1/<resource>; there is no Accept-Version, no query params for versioning and no feature flags visible from the API. The body and response shape is stable within the major version.
/api/v1/ is the only public surface
If an endpoint or field does not appear under /api/v1/, do not treat it as a contract. Internal routes (for example, /api/ApiToken/*, /api/Webhook/*, /api/enfc/*) cover app functionality and may change without notice. When one of those routes is promoted to a public surface, it appears under /api/v1/ and enters this documentation.
Compatible vs. major changes
Your integration must tolerate compatible changes without new code. Major changes are never made on the current version.
Compatible changes (no new version)
- Adding a new resource or endpoint.
- Adding an optional field to a request or response DTO.
- Adding a new value to an enum (as long as the client treats unknowns as 'other').
- Adding an optional header to the response.
- Adding a new event to the webhook catalog.
Major changes (would go to /api/v2/)
- Renaming an existing field or changing its type.
- Removing a resource, endpoint, field or event.
- Changing the shape of PagedResult or the error envelope.
- Reassigning the meaning of an HTTP code on a specific endpoint.
How we announce changes
When a v2 exists, it will appear at /api/v2/ and we will maintain /api/v1/ with prior notice. The support period duration is pending definition with the platform team; when published, this page will document it in a table with absolute dates.