The version is in the path: every endpoint lives under /v1. Within a version, changes are additive; a change that would break an existing client ships as a new version while the old one keeps working.
What ships within a version
- New endpoints.
- New optional request fields, and new option tokens on existing fields.
- New response fields, and new models in the catalog.
- New error codes.
What waits for a new version
- Removing or renaming a field, an endpoint, or a status.
- Changing a field’s type or meaning.
- Tightening validation so that a request that was accepted is refused.
What a client must tolerate
- Ignore response fields you do not know.
- Treat an error code you do not know by its HTTP status.
- Expect the catalog to change: models appear when they launch, and a retired one answers
410 architecture_retired.
- The set of statuses is fixed within a version.
Deprecation
When a version is scheduled to retire, its responses carry Deprecation and Sunset headers for at least six months before the date, and the date is announced in the release notes. Nothing is deprecated today. Last modified on September 17, 2026
