API changes

We design our APIs to evolve while minimising disruption to existing integrations. Wherever possible, changes to published APIs will be backwards compatible and existing integrations should continue to function without modification.

Backwards-compatible changes

We may introduce backwards-compatible changes without creating a new API version. These may include:

Adding new endpoints.
Adding new optional request parameters.
Adding new fields to response objects.
Adding new capabilities while preserving existing behaviour.
Introducing replacement fields or parameters while continuing to support existing ones.
Adding new values to extensible response types, such as @type.

Clients should be designed to tolerate these changes. In particular, integrations should ignore response fields they do not recognise rather than treating their presence as an error.

Extensible values

Some values returned by the API are designed to be extensible. For example, the set of supported message body @type values may grow as new message capabilities are introduced.

Clients must not assume that the currently documented set of values is exhaustive. An integration receiving an unknown value should handle it gracefully rather than failing the entire request or response.

New values may be introduced without creating a new API version.

Breaking changes

We consider a change breaking when an existing integration that correctly implements the documented API contract can no longer continue to operate as expected.

We aim to avoid breaking changes through careful API design and backwards-compatible evolution. Where existing behaviour can reasonably be maintained, we will favour preserving it while introducing new functionality.

Examples of changes that may be considered breaking include:

Removing existing functionality that clients depend on.
Removing support for previously accepted request values.
Changing the fundamental type or meaning of an existing field.
Introducing new mandatory behaviour where backwards-compatible behaviour cannot reasonably be provided.
Making material changes to the semantics of an existing operation.

Deprecation

As the API evolves, functionality may occasionally be superseded by newer capabilities.

Where practical, deprecated functionality will continue to operate for a migration period. Deprecations and any required migration steps will be communicated through our API documentation.

Clients should migrate away from deprecated functionality within the communicated migration period, as deprecated functionality may eventually be removed.

Designing resilient integrations

To minimise the impact of API evolution, integrations should:

Ignore response fields they do not recognise.
Gracefully handle unknown values for extensible fields such as @type.
Avoid relying on undocumented fields, behaviours, ordering, or implementation details.
Handle API errors using documented HTTP status codes and error responses rather than relying on specific error message text.
Monitor API documentation for deprecations and changes that may require migration.

These principles allow us to continue improving the API while maintaining a stable contract for existing integrations.