Skip to main content

Versioning

The API version is the first path segment: /v1. Integrations built against /v1 keep working.

The stability commitment​

Within /v1, changes are additive only:

What will not change within /v1:

  • Existing fields don't change meaning or type; required request fields are not added to existing operations.
  • Existing error and warning codes keep their meaning.
  • The coordinate contract and validation semantics stay fixed.
  • Published template versions are immutable: the same version with the same data keeps rendering the same document (Templates and versions).

A breaking change would ship as /v2 alongside /v1, with a documented migration path and deprecation timeline, never as an in-place change.

What this asks of your integration​

Additive evolution only works if clients are tolerant readers:

  • Ignore unknown response fields rather than failing on them.
  • Branch on known codes, default on the class: an unrecognized error_code should fall back to handling by HTTP status class; an unrecognized warning code should be logged, not crash a parser.
  • Don't enumerate enums exhaustively: merge_tags[].type, field type, job status, and similar sets may grow.

Spec-first​

The OpenAPI 3.1 specification is the contract this API is built against. The reference and these guides are generated from and checked against it. Pin your client generation to the spec version you tested, and diff the spec on upgrade to see exactly what was added.