Versioning
The version lives in the URL: /api/public/v1. Every response also reports the
exact build in X-Novex-API-Version — currently 2026-08-04-preview.
Preview
v1 is Preview. It is real, credentialed, and safe to build against, but we have not yet frozen the shape. We will not remove or rename anything silently; if something must change during Preview you will hear about it first.
We would rather label it honestly than ship “stable” and break it.
What we can change without warning
- Adding a new endpoint
- Adding a new optional query parameter
- Adding a new field to a response
- Adding a new value to a field documented as open-ended
⚠️ Your client must tolerate unknown fields. This is the other half of the bargain — it is what makes “adding a field is not a breaking change” fair. Do not use a strict validator that rejects unrecognised properties, and do not assume the field list is exhaustive. Our OpenAPI schemas are deliberately open for this reason.
What requires a new version
- Removing or renaming a field or an endpoint
- Changing a field’s type or its meaning
- Making an optional parameter required
- Tightening validation on an existing parameter
- Changing default sort order or pagination behaviour
- Removing a value from an enum
Deprecation
If we supersede a version:
- It stays supported for at least 12 months.
- Every response from it carries
DeprecationandSunsetheaders. - We email the admins of any workspace whose keys have actually called it in the last 90 days.
Nothing is ever removed silently.