Versioning and compatibility

There is one version, v1, and it only changes in compatible ways. This is what you can rely on, and what your client has to tolerate.

​

What doesn’t change within v1

• The paths and methods of the five operations.
• The required fields of every request and response: they aren’t removed and don’t change type.
• The six moments (surface) and the seven signal types.
• The common error shape: type, title, status, detail, code, request_id, with extensions at the root level.
• The id prefixes.

​

What can change without notice

The SDK already does this: its types let unknown fields through, CrossUpApiError keeps what it doesn’t know in extensions, and reason_codes is string[].

​

What would break, and how it’s announced

Removing a field, changing a type, a path or the meaning of a value. None of that goes into v1. If it’s needed, it ships as v2 on another path, v1 stays alive, and the change is announced in Changelog before it ships.

​

Which contract version you’re looking at

This reference is generated from the OpenAPI 3.1 contract, and every change is logged in the Changelog with its date and the operation it touched.