Versioning and compatibility

This page explains how to read API versions, compatibility expectations, and changelog entries in this documentation.

Current documented versions

The current references published in this site are:

Use the API overview pages for functional context and the OpenAPI references for endpoint-level details.

Compatibility expectations

Versioned references describe the API behavior documented for that version.

Changes are usually considered compatible when they add functionality without requiring existing clients to change. Examples include:

• Adding a new endpoint.
• Adding an optional request field.
• Adding a response field that clients can safely ignore.
• Adding a new documented status code for a behavior that already existed.
• Improving examples or descriptions without changing API behavior.

Changes may require integration review when they affect existing requests or assumptions. Examples include:

• Removing or renaming an endpoint.
• Removing or renaming a request or response field.
• Changing required fields.
• Changing validation rules for existing fields.
• Changing pagination, filtering, or sorting behavior.

Client recommendations

Build integrations so they tolerate compatible additions:

• Ignore unknown response fields unless your workflow explicitly needs them.
• Validate only the fields your integration depends on.
• Store API version assumptions in integration documentation.
• Monitor the Changelog before updating generated clients or request mappings.
• Test critical workflows against the OpenAPI reference before releasing integration changes.

Changelog usage

Use the changelog to understand documented changes over time.

For each new version, review:

• Added, changed, or removed endpoints.
• Status code changes.
• Request and response schema changes.
• Validation behavior.
• Documentation corrections that affect implementation.