Versioning & Changes

Versioning

The version lives in the path: every endpoint is under /v1/. A breaking change ships as a new version prefix, not as a silent change to v1.

What is not a breaking change

• Adding a new endpoint.
• Adding a new optional query parameter.
• Adding a new field to a response object.
• Adding a new value to an existing enum where the field already documents growth.
• Adding a new error_code for a condition that previously returned a more generic one.

Write your client so these are non-events: ignore unknown response fields, and treat an unrecognized error_code as a generic failure of its HTTP status class rather than crashing.

What is a breaking change

• Removing or renaming a field, parameter, or endpoint.
• Changing a field's type or an existing value's meaning.
• Tightening validation such that a previously accepted request is rejected.

These go to a new version, with advance notice and an overlap period during which both versions serve traffic.

The spec cannot drift

The OpenAPI document is verified against the running gateway by parity tests on every build — the route set and every resource's field list are checked. If the reference says a field exists, the API returns it.

Staying current

The exact OpenAPI document the reference renders from is published at https://www.moveitpro.com/openapi.yaml. Track it in your own repository and diff it on a schedule; it is the earliest and most precise signal of change. Product-level release notes are published on the changelog.