Versioning and compatibility

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

The current references published in this site are:

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

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.

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.

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.

• Changelog
• API reference overview
• Current limitations
• Best practices