Versioning
How the Management API is versioned, what can change within v1, and how deprecations are announced.
The path is the version
https://portal.<domain>/api/v1/mgmtThe version is the path segment v1. There is no version header to send.
It follows the same stance as the Inference API: v1
until a breaking change forces v2.
What can change within v1
Only additive changes:
- new endpoints;
- new optional request parameters;
- new fields in response objects;
- new error codes and new values of
action; - new values in enumerated fields.
Your client must tolerate these: ignore unknown fields, and fall back on the
HTTP status and error.type for an error code it does not recognise.
These are breaking and only ever happen in a new version: removing or renaming a field or endpoint, making an optional parameter required, changing a default, or changing what an existing error code means. Error codes are never reused.
Security exceptions
A change that closes a security or privacy gap can narrow who may call an endpoint within v1. It never renames or removes a field for a caller who keeps access. Each one is listed here.
| Date | Change | Why |
|---|---|---|
| 2026-09-30 (0.16.0) | GET /billing/balance, /billing/grants, /billing/invoices and /billing/invoices/{id} need an Admin token owner; a member gets 403 insufficient_scope. | Organization billing is admin-only. |
| 2026-09-30 (0.16.0) | GET /org returns only the organization identity to a member. An Admin still gets the full record. GET /org/settings (Admin) is new. | Members must not read the organization's security settings. |
Deprecation policy
When a successor version ships:
- it is announced with at least 90 days' notice before the old version is retired;
- both versions run in parallel for at least six months;
- the old version keeps its behaviour unchanged for the whole period.
An API version is structure, not price: code has to be changed, tested and released on your schedule, not ours — hence the long window.
Request ids
Every response carries X-Request-Id. It is the correlation key for support
across both surfaces.