docs(apis): add client and API compatibility section

docs/apis-tools/working-with-apis-tools.md

@@ -58,6 +58,12 @@ Use Camunda Process Test to test your process definitions and automations with a
 
 <p class="link-arrow">[Camunda Process Test](/apis-tools/testing/getting-started.md)</p>
 
+## Client and API compatibility
+
+Camunda clients and SDKs are **forward-compatible** and **backward-compatible** with the Orchestration Cluster, meaning you can upgrade the cluster and clients independently. The Orchestration Cluster REST API is backward-compatible, ensuring no breaking changes to existing endpoints across versions.
+
+<p class="link-arrow">[Learn more about compatibility guarantees](/reference/public-api.md#client-and-api-compatibility)</p>
+
 ## Upgrade to Camunda 8.9
 
 If you are migrating from Camunda 7 or from v1 component REST APIs, see the migration guide for guidance.

docs/reference/announcements-release-notes/890/890-announcements.md

@@ -148,6 +148,10 @@ Camunda 8.9 now supports Elasticsearch 9.2+ and OpenSearch 3.4+, allowing you to
 :::info 8.9 APIs & Tools migration guide
 Migrate your API integrations, SDKs, and generated clients to Camunda 8.9 using the [8.9 APIs & Tools migration guide](/apis-tools/migration-manuals/migrate-to-89.md).
 :::
+
+:::tip Client and API compatibility
+Camunda clients (Java client, Spring SDK, Node.js SDK) and Camunda Process Test are **forward-compatible** and **backward-compatible** with the Orchestration Cluster. This means you can upgrade the cluster and clients independently — for example, running a client on 8.8 against a cluster on 8.9, or upgrading the client to 8.9 without code changes. See [Client and API compatibility](/reference/public-api.md#client-and-api-compatibility) for details.
+:::
 <br/>
 
 <div className="release-announcement-row">

docs/reference/public-api.md

@@ -69,3 +69,48 @@ Though not covered by the public API contract, we aim to provide a consistent ex
 - Avoiding breaking changes to configuration, endpoints, or backup-related features within the same minor release range.
 
 This balance allows continuous improvement to tools like Web Modeler and Console, while preserving stability for orchestration logic.
+
+## Client and API compatibility
+
+Public API components follow strict compatibility guarantees so you can upgrade clients and clusters independently.
+
+| Component                                                                                                               | Forward-compatible | Backward-compatible |
+| ----------------------------------------------------------------------------------------------------------------------- | :----------------: | :-----------------: |
+| [Camunda Java client](/apis-tools/java-client/getting-started.md)                                                       |         ✅         |         ✅          |
+| [Spring SDK](/apis-tools/camunda-spring-boot-starter/getting-started.md)                                                |         ✅         |         ✅          |
+| [Node.js SDK](https://github.com/camunda/camunda-nodejs-sdk)                                                            |         ✅         |         ✅          |
+| [Camunda Process Test](/apis-tools/testing/getting-started.md)                                                          |         ✅         |         ✅          |
+| [Orchestration Cluster REST API](/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview.md) |         —          |         ✅          |
+
+- **Forward-compatible** means a client can work with a _newer_ version of the Orchestration Cluster than the client version.
+- **Backward-compatible** means a client can be upgraded to a _newer_ version without requiring changes to your application code.
+
+### Clients and SDKs
+
+The Camunda Java client, Spring SDK, Node.js SDK, and Camunda Process Test (CPT) are both **forward-compatible** and **backward-compatible** with the Orchestration Cluster.
+
+**Forward compatibility** means your application can use an older client version and still work correctly against a newer cluster. For example, an application using Camunda Java client **8.8.3** works against an Orchestration Cluster running **8.9.1**. This allows you to upgrade the Orchestration Cluster first without immediately updating your client libraries.
+
+**Backward compatibility** means that when you upgrade the client or SDK version in your application, no code changes are required. New minor and patch versions of the clients do not introduce breaking changes. For example, upgrading the Spring SDK dependency from **8.8.x** to **8.9.x** does not require changes to your application code.
+
+### Camunda Process Test (CPT)
+
+CPT is both forward-compatible and backward-compatible with the Orchestration Cluster and Connectors runtime:
+
+- **Forward-compatible**: You can change the version of the Orchestration Cluster/Connectors bundle in your tests to a newer version without any changes.
+- **Backward-compatible**: Upgrading the CPT dependency version does not require changes to your existing tests.
+
+### REST APIs
+
+The [Orchestration Cluster REST API](/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview.md) is **backward-compatible**. No breaking changes are introduced to existing endpoints in newer versions of the Orchestration Cluster. For example, if you build a custom client implementation against the **8.8** REST APIs, it continues to work against a newer Orchestration Cluster version such as **8.9**.
+
+:::note
+Because REST API endpoints are part of the Orchestration Cluster itself, forward compatibility does not apply — your cluster version determines which endpoints are available.
+:::
+
+### Recommended upgrade order
+
+When upgrading across minor versions, the recommended approach is:
+
+1. **Upgrade the Orchestration Cluster first.** Forward compatibility of clients ensures your existing applications continue to work.
+2. **Upgrade your client libraries.** Backward compatibility of clients ensures no code changes are needed.