API version policy
The commitments below are contractual and are not settings a cell can lower (versioning.min_support_years, versioning.min_notice_months).
- The public path prefix is
/v1for every version and does not change. A/v2would exist only if the resource model itself were replaced, which needs an ADR. - A version is a date (
Hive-Version: 2026-11-01). The first version,2026-11-01, was fixed at first general availability. A new dated version is created only when at least one breaking change is released, and the target is at most two new versions a year. - Your tenant is pinned to one version, set when its first credential was created, to the newest version at that moment. We never change your pin, not when a newer version is released and not at sunset. A tenant administrator changes it with
POST /v1/api-versions/pin(permissionapi_version.update, a person, not a service account);dry_run: truelists the changes and the calls of the last 30 days that the change would affect. A change takes effect within 60 seconds and is audited. - A request may override the pin with the header
Hive-Version. Every response carriesHive-Versionwith the version that was applied. An unknown, retired or future version is400 unsupported_versionwith the list of supported versions; a malformed one is400 invalid_request. - A released version is supported for at least 5 years after its successor is released. A version is removed only after a sunset date that lies at least 24 months after the announcement and at least 5 years after the successor's release, whichever is later.
- From the announcement every response served at the deprecated version carries
Deprecation,SunsetandLink: <...>; rel="deprecation". Tenant owners and administrators are told at the announcement and 12 months, 6 months, 90 days, 30 days and 7 days before the sunset, with the credentials of their tenant that still call the version. A tenant that is still pinned to a version after its sunset date is not moved; retirement is a recorded decision (an ADR) after the notice schedule is complete. - Adding a response field, an endpoint, an optional request field or parameter, an event type, an enum value to an enum that is not a state machine, a new error code for a new situation, or loosening a validation is not breaking and appears in every version at once. Everything else is breaking and ships only in a new dated version, with a transformer so that older versions keep working.
- A security fix may break a contract without the 24 months' notice only when a vulnerability cannot otherwise be closed. Each exception is announced within 24 hours, listed in the changelog as a "security exception" and approved by the security lead.
- Features marked preview (
Hive-Preview: <slug>) carry no stability promise.
How a change is made: changing-the-api. The versions and their status: API versions.