Versioning
The API version is in the path: every endpoint lives under /v1. The
OpenAPI specification is the canonical description of the
current contract, and the API reference is rendered from
that exact file.
What can change without notice
Additive changes ship on /v1 silently. Your client must tolerate all of
these:
- A new optional field appearing in a response — ignore fields you do not recognise; never fail on an unknown key.
- A new optional query parameter.
- A new endpoint.
- A new error
typein the catalog.
Treat enum-like string fields the same way where their documentation says so
(for example an asset type or a threat module you have not seen before):
handle unknown values gracefully rather than rejecting the record.
What never changes on /v1
Breaking changes get a new major version (/v2), and /v1 keeps
serving. Breaking means any of:
| Category | Examples |
|---|---|
| Removing or renaming | A response field, an endpoint |
| Changing meaning | A field's type, an enum's value domain |
| Narrowing input | Rejecting a request /v1 used to accept |
| Reordering | Changing the default sort of a list endpoint |
| Errors | Changing an existing error type URI |
Field names are part of the contract — a rename is a breaking change and will
never happen on /v1.
Practical guidance
- Pin your integration to
/v1in configuration, not code, so a future migration is an edit rather than a release. - Generate clients from openapi.json — regenerating against the latest spec is always safe within a major version.
- Deprecations, if any, will be announced with a migration window before a
/v1sunset date is ever set.