We release a new API version when we need to introduce a backward-incompatible
change. The current version is v1.
Versioning is path-based. The version appears directly in the request URL:
For example, if a future v2 is released, upgrading would mean changing your
requests from:
to:
If you do not upgrade the version in your request path, your integration will
continue using the behavior of the version you are calling.
Designing for compatibility
Your integration should be written defensively so it remains compatible with
non-breaking API improvements. In practice, this means:
- Treating response object property order as insignificant
- Handling unknown enum-like string values gracefully
- Accepting that arrays may grow over time
- Avoiding assumptions about the length or format of opaque IDs and error strings
Unless an endpoint explicitly documents array ordering semantics, you should not
depend on the order of array items.
Non-breaking changes
The following changes do not require a new API version:
- Adding new API resources, paths, or methods
- Adding new optional request parameters or headers to existing endpoints
- Expanding accepted values for an existing request parameter or header
- Adding new attributes to existing API responses
- Expanding the possible values of an existing response attribute
- Adding new items to array responses
- Reordering object properties in API responses
- Reordering array items when ordering is not explicitly documented as part of the contract
- Changing the length or format of opaque strings such as object IDs, request IDs, and error messages
Your integration should gracefully handle unknown string values in responses.
Do not treat enum-like fields as permanently fixed unless the documentation
explicitly guarantees that behavior.
Breaking changes
The following changes are considered backward-incompatible and require a new API
version:
- Removing or renaming an existing endpoint
- Removing or renaming an existing request parameter or header
- Removing support for a previously accepted request parameter or header value
- Adding a new required request parameter or header to an existing endpoint
- Adding a new validation that causes previously documented, valid requests to be rejected during normal use
- Removing or renaming an existing response attribute
- Changing the type of an existing response attribute
- Changing the meaning of an existing request field, header, or response value
- Changing the expected success or error status code for a documented scenario, except when the previous response was a
404 or 5xx
In short, if an existing integration that follows the documentation would need
to change its request or response handling to continue working, that change is
breaking and belongs in a new API version.
Practical guidance
- Pin your integration to the API version you have tested
- Upgrade versions deliberately instead of assuming automatic compatibility
- Review the documentation for the target version before upgrading
- Build clients that ignore unknown response fields instead of failing on them
This approach gives you control over when your integration adopts breaking
changes. 
