Skip to main content
API docs menu
← API reference

Versioning and stability

What may change inside v1, what may not, and where every change is written down.

What v1 means

The /v1/ in every path and contractVersion: "1" in every response name the shape of the contract. Within v1 an integration that works today keeps getting the same answer to the same request — the same keys in the same order, the same headers, the same error codes and statuses.

What may change within v1

  • A new endpoint.
  • A new optional request field, a new include token or another new accepted value in a request.
  • A new response field that appears only when the request asks for it, or only in a case that did not exist before.
  • A new header, or a new key inside details — treat unknown keys as informational.
  • Wording: message and warnings are for people. Branch on error, unplaced, guillotineValid and the metrics.

What does not ship within v1

A breaking change: a removed endpoint, field or enum value; a request validated more strictly (a field that becomes required, a narrower type, a tighter limit); a response that can carry a value it could not before (a wider type, a field that is no longer always sent). The OpenAPI document is recorded on every change, and our build refuses a change of this kind.

Fixes are the exception the changelog names: when the server already behaved one way and the document said another, the document is corrected to the behaviour.

Deprecation

A deprecated field is marked deprecated: true in the OpenAPI document, says what replaces it, and keeps working within v1. No removal date is set today.

Deprecated now: Part2D.grainGroup.

Better plans are not a new version

The engines are deterministic, but they improve. When an algorithm changes, the same request can return a better plan and engineVersion changes with it — the shape stays the same. To pin behaviour, send engine explicitly and watch engineVersion; see engines and determinism.

Where changes are written down

Every change to the document has a dated entry in the API changelog (also as RSS), under Added, Changed, Deprecated or Fixed. The current document is always at /engine/openapi.json.