Versioning

The API is versioned in the URL path. Every endpoint is prefixed with its version, for example POST v2/assets. The version you call is the version you get, so an integration built against v2 keeps behaving the same way until you choose to move.

What you can rely on

Within a version, changes are additive and backwards-compatible. We may:

• add new endpoints;
• add new optional fields to a request or response;
• add new values to an open-ended list.

So these additions never break you, build a tolerant client:

• Ignore fields you don’t recognise in responses rather than failing on them.
• Don’t depend on the order of fields, or on a list being exhaustive.
• Treat new optional request fields as opt-in; you’re never required to send them.

What counts as a breaking change

Anything that could break a well-behaved existing integration is a breaking change. It would ship under a new version (for example v3), not silently within v2. That includes:

• removing or renaming an endpoint, field, or accepted value;
• making a previously optional request field required;
• changing the type or meaning of an existing field;
• tightening validation so payloads that used to be accepted are now rejected.

When a new version ships, the previous version keeps working, so you migrate on your own schedule.

Staying on a version

Because the version is in the path, you “pin” simply by calling the same prefix. There’s nothing to negotiate via headers. Keep the v2 prefix in your base paths and you’ll stay on v2.