Skip to Content

Versioning

What may change within v1, and how removals are announced.

Every path starts with /v1. Within v1 changes are additive only: new operations, new optional fields and new response fields can appear, so ignore fields you do not know. Fields such as a cluster's state or provider can also gain new values.

Deprecations

A path, operation or field is only removed or renamed after it has been deprecated for at least six months. A deprecated operation is marked deprecated in the spec and answers with these headers:

  • Deprecation: true
  • Sunset: <date>, the date it stops working.

No v1 operation is deprecated today.

The spec

The OpenAPI document of v1 is served at /v1/openapi.json and /v1/openapi.yaml. The reference on this site is generated from it. The interactive view at /docs has a version selector over every version's spec.

On this page