Versioning

The Novantra public API is versioned in the URL path: /api/v1/.... Everything described under “v1” in these docs belongs to the v1 contract. v1 stays callable and stable for as long as it’s published.

What v1 promises

A v1 endpoint will not:

Remove fields from response bodies that clients rely on.
Add required fields to request bodies.
Change the meaning of an existing field’s values.
Remove valid enum values from a response field.
Reorder path or query parameters.
Change error envelope shape.

A v1 endpoint may:

Add new optional fields to response bodies. Clients that ignore unknown fields keep working.
Add new optional fields to request bodies with safe defaults.
Add new valid enum values. Clients should treat unknown enum values gracefully (typically: ignore the record or log and skip).
Add entirely new endpoints, including new resources and new verbs on existing resources.
Loosen validation (e.g., accept a longer string).

These rules apply to the public v1 contract documented in the reference pages.

What triggers a new version

When the v1 contract genuinely can’t satisfy a change (a field needs to be removed, an existing field’s meaning needs to change, a required field needs to be added), Novantra ships a new major version /api/v2/.... v1 and v2 then run side by side.

When this happens:

v2 is announced through the changelog and emailed to service-account contact addresses on file.
v1 enters a documented deprecation window.
v1 stays callable throughout the deprecation window. No silent breakage.

Deprecation policy

The default deprecation policy is:

Stage	Duration	What happens
Announced	Notice given.	Documentation marks v1 as deprecated. Email goes to service-account contacts.
Deprecation window	12 months minimum from announcement.	v1 continues to function. Responses include a `Deprecation` and `Sunset` header indicating the scheduled end-of-life date.
Sunset	After the window expires.	v1 endpoints start returning `410 Gone`.

12 months is the floor; complex enterprise migrations get more.

Customer-impacting deprecations are coordinated with enterprise accounts individually. If a scheduled sunset would land in the middle of an audit cycle or a regulator deadline, account teams negotiate the timing.

Endpoint lifecycle

Every endpoint in the Governance reference is part of the public v1 contract. Additive changes are recorded in the changelog. Deprecations follow the policy above and are never silent.

OpenAPI as source of truth

The v1 OpenAPI spec is the authoritative contract. Generate typed clients from it. Schema validation against the spec is reliable; manual parsing against documentation prose is not.

Changelog

The API changelog records every backward-compatible addition to v1 plus every deprecation announcement.

Reading the headers

Helpful response headers related to versioning:

Header	Meaning
`API-Version: v1`	Confirms the version that served this response. Always present.
`Deprecation: true`	Present on any response from a deprecated endpoint. Pair with `Sunset`.
`Sunset: <RFC 7231 date>`	The date after which the deprecated endpoint stops working.
`Link: <...>; rel="alternate"`	When a replacement endpoint exists, this points to it.

If you see Deprecation: true in production, surface it in your monitoring and migrate before the Sunset date.

What this is not

Not semver in the URL. v1 covers the entire v1 contract regardless of additive changes. There is no /api/v1.2/.
Not Accept-header versioning. Version is in the URL only; the Accept header doesn’t pick the contract.
Not date-based versioning. Novantra does not publish dated revisions (?api_version=2026-05-01); major-version pinning in the URL is the model.

Errors - error envelope and status codes.
Webhooks - event subscriptions and signature verification.