API Deprecation Policy
Version 1.0 — June 8, 2026
Introduction
On occasion, Qmatic may choose to retire or replace endpoints in the Orchestra Platform API. This may be because the future roadmap requires breaking changes (demanding a new version), or because the endpoint depends on product capabilities that are being retired or redesigned.
This document describes how APIs are deprecated, maintained, and eventually removed. The goal is to ensure a predictable, safe, and transparent lifecycle for all Orchestra API consumers.
Classification of Changes
| Type | Description |
|---|---|
| Minor change | Backward compatible — no deprecation required |
| Deprecation | API remains available but is scheduled for removal |
| Retirement | API is no longer available |
Backward Compatible Changes
The following changes are considered safe and backward compatible. Clients should not need to make any changes when these are introduced:
- Adding new API endpoints or resources
- Adding new optional request parameters or headers to existing methods
- Adding new optional properties to existing API response objects
- Changing the length or format of opaque strings (e.g. object IDs, error messages, human-readable labels)
- Changing error message text or resource descriptions in API responses
- Increasing the scope of error message IDs
- Adding new event types
- Adding rate-limit headers or errors
Breaking Changes
The following changes require a new version with a prior deprecation notice:
- Removing or renaming an API endpoint or resource
- Removing or renaming Enum values
- Changing the type of an existing field
- Changing the observable behaviour of an existing request
- Removing required request parameters
Deprecation Policy
Once an endpoint is marked deprecated, it will remain fully supported through the next minor version following the deprecation announcement and will be removed in the subsequent minor version.
Example: An endpoint deprecated in v7.1 will continue to be supported in v7.2 and removed in v7.3.
An endpoint that has not been explicitly deprecated cannot be silently removed when a new major version is released. Any endpoint absent from a major version must have gone through the standard N+1 deprecation cycle first — the major version boundary does not bypass this requirement.
When a new replacement endpoint is introduced, the old endpoint must remain available for at least one additional minor version after the replacement is released before deprecation can be announced.
In rare cases (security vulnerabilities, compliance requirements), an API may be retired immediately. In such cases, Qmatic will notify customers as soon as possible.
Orchestra Platform Versioning Model
Orchestra follows semantic versioning: major.minor.patch.
| Version Type | Example | Meaning |
|---|---|---|
| Major | 7.0 → 8.0 | Breaking changes permitted; new major version guarantees apply |
| Minor | 7.5 → 7.6 | New features introduced; deprecations may be announced |
| Patch | 7.5.0 → 7.5.1 | Bug fixes only; no deprecations or breaking changes |
Notice of Deprecation
Deprecation notices are issued through internal and external channels at the time of the deprecation announcement. Each notice includes:
- The deprecated endpoint(s) and the version in which deprecation was announced
- The Orchestra Platform version in which the endpoint will be removed
- A migration guide to the replacement endpoint(s)
After the removal version is released, the retired endpoint will no longer be accessible and support will no longer be provided. Any attempt to call it will fail.
Change Logs
A changelog is maintained on the Developer Portal listing all endpoint additions, changes, and deprecations in chronological order. Development partners and integrators can subscribe to receive notifications through the portal.
Partner Support During Deprecation
To help supply partners and external integrators migrate without disruption, Qmatic provides access to a shared hosted environment configured with the target version. This allows partners to validate their integrations against new endpoints before the removal version is released.
This environment is provisioned with a temporary license valid for the duration of the deprecation window. Partners can request access through the standard partner onboarding process.
In addition, Qmatic offers support resources to help users adapt to new API endpoints and newly introduced workflows.