Camunda 8.10 APIs & Tools migration guide

Learn how to migrate your API integrations, SDKs, and generated clients to Camunda 8.10.

About

This guide details the API and SDK changes introduced in Camunda 8.10 that require customer action, including breaking changes, deprecations, and step-by-step migration actions.

Details are provided for each integration type, including what changed, why, and what action you must take.

Integration type	Description
Official SDK users	Java client, TypeScript SDK, Python SDK, and C# SDK.
Generated-client users	Clients generated from the Camunda OpenAPI specification.
Custom integrations	Custom code that calls the Camunda REST API directly.

Upgrade steps

Complete the following steps in this guide:

1. Upgrade to the latest official Camunda SDK versions.
2. If you generate clients from OpenAPI, regenerate them from the 8.10 specification.
3. Re-run compilation/type checks and address any errors.
4. Review and apply fixes for the breaking changes, deprecations, and supported environment changes below.

API and SDK changes to migrate before Camunda 8.10

If you did not already migrate to the following APIs and SDKs during your 8.8 or 8.9 upgrade, Camunda recommends you perform these migrations before you upgrade to 8.10.

If you already performed these migrations, proceed to Camunda 8.10 breaking changes, deprecations, and supported environment changes.

8.9 status	Component/Use	Migrate to	Migrate by
Deprecated	V1 component APIs	Orchestration Cluster API	Before Camunda 8.10
Deprecated	ZeebeClient	Camunda Java Client	Before Camunda 8.10
Deprecated	Spring Zeebe SDK	Camunda Spring Boot Starter	Before Camunda 8.10
Deprecated	Zeebe Process Test (ZPT)	Camunda Process Test (CPT)	Before Camunda 8.10
Deprecated	Job-based user tasks	Camunda user tasks	Before Camunda 8.10

tip

Learn more about API changes in the blog post Upcoming API Changes in Camunda 8: A Unified and Streamlined Experience.

Camunda 8.10 breaking changes, deprecations, and supported environment changes

Review the actions required for the following 8.10 changes:

Type	Change
Breaking change	Search filters: UserTaskFilter process filters converted into advanced search filters
Breaking change	POST /v2/message-subscriptions/search returns start event subscriptions
Breaking change	Administration API (Self-Managed) migrated
Behavioral change	Element instance search: advanced filters on elementId / elementName and $or support
Behavioral change	Resource API now uses eventual consistency
Behavioral change	Deleting a process definition with running instances defers history deletion
Deprecated	Deprecated: GET resource content API

Breaking changes

Review actions required for the following breaking changes:

Search filters: UserTaskFilter process filters converted into advanced search filters

Change

The search filter criteria for processDefinitionKey, processInstanceKey, and bpmnProcessId in UserTaskFilter have been converted into advanced search filters.

Why

As a result of the V1 API removal, advanced process filtering for user tasks was no longer supported. These changes let you use advanced process filters with the V2 User Tasks API again.

Impact

This affects the Java client because io.camunda.client.api.search.filter.UserTaskFilter now accepts advanced filters for processDefinitionKey, processInstanceKey, and bpmnProcessId.

Action

Official SDK users

Update to the latest SDK version. The new SDK version includes advanced filters for processDefinitionKey, processInstanceKey, and bpmnProcessId in UserTaskFilter.

Generated-client users

Regenerate your client.

Custom integrations

No change is needed if your code already uses the exact-match filters for processDefinitionKey, processInstanceKey, and bpmnProcessId in UserTaskFilter.

POST /v2/message-subscriptions/search returns start event subscriptions

Change

The POST /v2/message-subscriptions/search endpoint now returns both start event and intermediate event message subscriptions. Previously, only intermediate event subscriptions were returned.

Why

This change provides complete visibility into all active message subscriptions for a process, including start event subscriptions that were previously excluded.

New field

Each result includes a new messageSubscriptionType enum field:

Value	Description
START_EVENT	A start event message subscription.
PROCESS_EVENT	An intermediate catch event message subscription.

In existing legacy data, this field is NULL.

Impact

Integrations that consume results from POST /v2/message-subscriptions/search will now receive start event subscriptions in addition to intermediate event subscriptions. Code that assumes only intermediate events may produce unexpected behavior.

Action

Official SDK users

Update to the latest SDK version. If your code relies on the endpoint returning only intermediate event subscriptions, add a filter to exclude start events when constructing your search query.

Generated-client users

Regenerate your client from the 8.10 OpenAPI specification to include the new messageSubscriptionType field. If your code expects only intermediate event subscriptions, add the filter shown in the Custom integrations tab to your request payload.

Custom integrations

If your code relies on the endpoint returning only intermediate event subscriptions, add the following filter to restore the previous behavior:

Before (no filter needed — endpoint returned only intermediate events)

{
  "filter": {}
}

After (filter required to exclude start events)

{
  "filter": {
    "messageSubscriptionType": { "$neq": "START_EVENT" }
  }
}

This filter works correctly for both new data and legacy data (which has NULL in the messageSubscriptionType field).

Administration API (Self-Managed) migrated

The Administration API endpoints for Self-Managed have been migrated to the now-deprecated Web Modeler API v1:

Admin API (Self-Managed)	Web Modeler API v1
GET /admin-api/usage-metrics	GET /api/v1/clusters/usage-metrics
GET /admin-api/clusters	GET /api/v1/clusters

For both endpoints, you need a token with read permissions.

These endpoints return the same data as the original Administration APIs, but the response format matches the other Web Modeler APIs.

Behavioral changes

Element instance search: advanced filters on elementId / elementName and $or support

Change

The element instance search endpoint (POST /v2/element-instances/search) gained two filtering capabilities:

• The elementId and elementName filter fields now accept advanced search filter objects in addition to plain string equality. Supported operators: $eq, $neq, $exists, $in, $notIn, $like (wildcard pattern with * and ?).
• The request body's filter object now accepts a top-level $or property that takes an array of alternative filter groups combined with OR logic. Top-level filter fields and $or are combined with AND logic.

Why

These additions let you express the queries the user interface (UI) needs (for example, "match any element whose name or ID contains a substring") in a single request, avoiding multiple round trips and client-side merging.

Impact

The change is additive and backward compatible — existing exact-match requests continue to work unchanged. New requests can now use advanced operators and $or to express richer queries:

{
  "filter": {
    "processInstanceKey": "2251799813685323",
    "$or": [
      { "elementName": { "$like": "*Order*" } },
      { "elementId": { "$like": "*Order*" } }
    ]
  }
}

The example matches element instances where processInstanceKey equals the given value AND either elementName or elementId contains the substring Order.

note

Complex $or conditions may impact performance in high-volume environments; use them with care.

The elementName filter only matches instances created in 8.8 or later, since earlier runtimes did not persist this field on element instances.

Action

Official SDK users

Update to the latest SDK version. The new SDK exposes advanced filters for elementId and elementName, and the $or filter on ElementInstanceFilter.

Generated-client users

Regenerate your client from the 8.10 OpenAPI specification to pick up the advanced filter and $or types on ElementInstanceFilter.

Custom integrations

No change is needed for existing requests. To use the new operators, send advanced filter objects on elementId / elementName, or a top-level $or array, as shown above.

Resource API now uses eventual consistency

The Get resource and Get resource content APIs now retrieve from secondary storage, resulting in eventual consistency. After a resource is deployed, there may be a brief delay before it becomes retrievable via these endpoints.

If your application assumes immediate resource retrieval after deployment, add retry logic or a short delay before querying resources.

Deleting a process definition with running instances defers history deletion

The delete resource endpoint now accepts process definition deletion when the definition still has running instances. Instead of rejecting the request or waiting for physical removal, the definition drains: new instances are blocked immediately, running instances continue to completion, and the definition is removed automatically afterwards.

As a result, when deleteHistory is true, the batchOperation field in the response is null for such a definition. Its history is removed as part of the draining lifecycle rather than through an immediately-returned batch operation. The field is still populated for decision requirements definitions and for process definitions that are already fully deleted from the runtime state.

If you read batchOperation from the delete response to track history deletion, handle a null value: the definition is draining. Track progress through the process definition state (DRAINING) or the zeebe_process_definitions_draining_count metric instead.

Deprecations

Review the actions required for the following deprecations:

Deprecated: GET resource content API

The Get resource content endpoint is deprecated. Use Get resource content binary instead, which provides the same functionality and also returns generic resources.

Next steps

Once you have completed the upgrade steps in this guide, you should:

1. Re-compile and run your test suite against the 8.10 API.