API Versioning
Contract v1, what counts as a breaking change, and how deprecations are communicated.
Current version: v1
This is the current and only public contract on api.<domain>/v1/*. There
is no rollout flag, no legacy compatibility mode, and no header-based version
selection — every request, in every environment, gets the behaviour documented
in these pages.
What can change without a new version
Adding a key to provider_metadata is a minor version bump of the contract
(announced, additive, opt-in to read). New endpoints and new optional request
fields are also additive changes.
What is a breaking change
Removing or renaming anything in a standard response body, changing a status
code, or changing the error envelope is a major version, tracked as a new
contract document revision — and it will not happen silently inside v1.
How deprecations are communicated
Model aliases (not the API itself) deprecate through a built-in lifecycle —
served normally with provider_metadata.deprecation +
X-TF-Deprecation inside the window, then 410 model_deprecated past
sunset. The full phase table:
Models & Aliases.
Machine-readable description: the OpenAPI 3.1 spec (inference-v1.yaml)
tracks this same surface and is validated in CI.