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.

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
Behavioral change	Element instance search: advanced filters on elementId / elementName and $or support
Behavioral change	Resource API now uses eventual consistency
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).

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.

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.