Versioning & stability
Every path is served under /v1. That prefix is your stability contract: within it, the API only grows in compatible ways.
What stays stable
Within /v1, changes are additive. We may:
- add new capabilities, endpoints, and optional request fields;
- add new fields to responses.
We won't remove a field, rename one, or change its type under /v1 without versioning the change. Treat unknown response fields leniently — new ones can appear — and never depend on field order.
Your tenant's surface is the source of truth
The set of endpoints you can call depends on which Apps are installed in your tenant. The authoritative, always-current description of your surface is the OpenAPI document the gateway serves — explore it interactively in the API Explorer:
curl https://api.revenexx.com/v1/openapi.json \
-H "X-Revenexx-Tenant: <TENANT_SLUG>" \
-H "X-Revenexx-Api-Key: rvxk_..."
Generate typed clients from it with the CLI (revenexx types / revenexx generate) so your code tracks the contract.
What counts as a break
Most changes never reach you as work, because they are additive. A change is breaking only if an integration written against the old contract could notice it:
- a field or endpoint removed or renamed;
- a field's type, unit, or meaning changed;
- a new required request field;
- a different status code for behaviour you already rely on;
- a changed error shape, or changed authentication requirements;
- a change to how pagination works.
The retirement path
A breaking change never lands in place. It lands beside the behaviour it replaces, and the old behaviour is retired through every stage in turn:
| Stage | What it means for you |
|---|---|
| Current | Fully supported, and still gaining features and fixes. |
| Deprecated | Works exactly as before. A replacement exists, and a removal date is published. |
| Sunset | Still answering, but past its published date. Migrate now. |
| Removed | Gone. The path answers 404 or 410. |
You get at least four weeks between the announcement and the removal, and nothing is announced without a migration path published alongside it.
How the notice reaches you
Deprecations and breaking changes are announced on the Changelog before they take effect. That is the channel to watch — subscribe to it rather than polling for changes.