Migrate to the Orchestration Cluster API

Migrate from Camunda V1 component REST APIs to the V2 Orchestration Cluster REST API.

About this guide

This guide covers how to migrate to the V2 Orchestration Cluster REST API, and what to consider when migrating. It covers all public endpoints in the component REST APIs and their Orchestration Cluster API counterparts or required migration changes.

• Camunda is streamlining the developer experience by creating a unified REST API for Zeebe, Operate, Tasklist, and the Identity components with endpoint parity. This is the single Orchestration Cluster REST API.
• Individual component APIs (starting with the former Operate and Tasklist APIs) are being deprecated over time. These will continue to be in the product in the short-term, but Camunda recommends you begin the adoption of the new API.
• In addition, several Zeebe gPRC endpoints will begin to be deprecated.

info

To learn more about the unified REST API, see the official blog announcement.

note

The Administration and Web Modeler APIs are not part of the Orchestration Cluster REST API, as these are platform APIs outside the cluster’s scope.

Migration steps

To successfully migrate to the V2 Orchestration Cluster API, perform the following steps:

1. Identify your current V1 endpoints: Audit your application to catalog all V1 API calls currently in use.
2. Map V1 endpoints to V2 equivalents: Use the tables in this guide to find the corresponding V2 endpoints for each request.
3. Update request and response structure: Adapt your code to handle the new formats, renamed attributes, and data type changes as outlined in this guide.
4. Update pagination logic: Replace old pagination parameters with the new page object structure and cursor-based navigation.

General endpoint changes

All endpoints

• The new API can be found at <cluster>/v2/…> instead of <cluster>/v1/…>.
• All endpoints are no longer separated by component concerns and all endpoints receive similar support. For example, process definitions, user tasks, and user authorizations were previously spread across separate Tasklist, Operate, and Identity APIs.
• Naming, response codes, and type handling have been streamlined for all endpoints to provide a consistent UX.
• Endpoints with similar concerns (variable search, for example) have been consolidated into single endpoints.
• The request and response payload of every new endpoint might contain new attributes that are not necessarily needed for a migration from a V1 endpoint to V2 but might still be useful. Please consult the V2 API guides for access to all new attributes.

Endpoints querying for data

• Unified search request structure.

  • Attributes filter, page, and sort on root level.
  • Endpoint-specific filter attributes in the filter object, not at the root level.
  • Pagination information in the page object. For example, the attributes from, limit, before, and after.
  • Sorting configuration in sort object array, each object containing the field name and order (descending or ascending).

• Unified search response structure.

  • Attributes items and page on root level.
  • List of endpoint-specific response items in items attribute.
  • Page information in page attribute, for example the attributes totalItems, startCursor, and endCursor to use in before and after in follow-up requests.

Name changes and mappings

The following table shows key attribute name changes from V1 to V2:

V1	V2	Notes
id	[entity]Id	Keys now include entity prefix (for example, userTaskKey, processDefinitionId).
key	[entity]Key	Converted from int64 to string with entity prefix.
bpmnProcessId	processDefinitionId	Unified naming convention.
processName	processDefinitionId	Unified naming convention.
decisionKey	decisionDefinitionKey	Unified naming convention.
dmnDecisionKey	decisionDefinitionKey	Unified naming convention.
decisionId	decisionDefinitionId	Unified naming convention.
dmnDecisionId	decisionDefinitionId	Unified naming convention.

General naming conventions:

• Keys and IDs contain the full entity name as prefix to avoid confusion (for example, processDefinitionKey instead of processKey).
• Entity attributes have no prefix within their own entity, but use prefixes when referenced from other entities.
• All key fields are now string type instead of int64.

Tasklist REST API

Form

Get a form

V1	V2
GET /v1/forms/{formId}	GET /v2/user-tasks/{userTaskKey}/form GET /v2/process-definitions/{processDefinitionKey}/form

Input adjustments

• You cannot fetch forms directly anymore. Instead, fetch them by user task or process definition to get the respective form data.
• The respective endpoint only takes the key of the resource the form is related to as input parameter.

Output adjustments

Embedded forms are no longer returned as Camunda user tasks don't support them.

Field	Change Type	Notes
id	Renamed	Now formKey (unique system identifier of the form).
title	Renamed	Now formId (aligns with form schema attribute).
isDeleted	Removed	No longer provided by endpoint.
processDefinitionKey	Removed	Can be identified from endpoint resource and key parameter.

Task

Save task draft variables

V1	V2
POST /v1/tasks/{taskId}/variables	This feature is not supported in V2 anymore. Use setting variables as local to the user task's elementInstanceKey as a replacement.

Search task variables

V1	V2
POST /v1/tasks/{taskId}/variables/search	POST /v2/user-tasks/{userTaskKey}/variables/search

Input adjustments

Request structure changes as outlined in general changes.

Field	Change Type	Notes
variableNames	Renamed	Now name in filter object (plain string or { "$in": [ "xyz", ... ] }).
includeVariables	Removed	Endpoint returns all variables associated with the user task.

Output adjustments

Response structure changes as outlined in general changes.

Field	Change Type	Notes
id	Renamed	Now variableKey (unique system identifier of the variable).
previewValue	Renamed	Now value (always represents variable value, may be truncated).
isValueTruncated	Renamed	Now isTruncated (see get variable endpoint for full value if needed).
draft	Removed	Draft variables not supported in V2 (see save draft variables endpoint).

Search tasks

V1	V2
POST /v1/tasks/search	POST /v2/user-tasks/search

Input adjustments

Request structure changes as outlined in general changes.

Field	Change Type	Notes
pageSize	Renamed	Now limit in the page object.
searchAfter	Renamed	Now after in the page object.
searchBefore	Renamed	Now before in the page object.
taskDefinitionId	Renamed	Now elementId (user-provided identifier of the BPMN element).
assigned	Renamed	Now assignee with { "$exists": false }.
assignees	Renamed	Now assignee with { "$in": [ "xyz", ... ] }.
candidateGroups	Renamed	Now candidateGroup with { "$in": [ "xyz", ... ] }.
candidateUsers	Renamed	Now candidateUser with { "$in": [ "xyz", ... ] }.
tenantIds	Renamed	Now tenantId with { "$in": [ "xyz", ... ] }.
followUpDate, dueDate	Changed	Use $gte and $lte instead of from and to.
priority	Changed	Filter keys need $ prefix, supports new comparison options.
taskVariables	Split	Now localVariables and processInstanceVariables.
searchAfterOrEqual	Removed	No longer supported.
searchBeforeOrEqual	Removed	No longer supported.
includeVariables	Removed	Use separate search task variables endpoint.
implementation	Removed	V2 API supports only Camunda user tasks.

Output adjustments

Response structure changes as outlined in general changes.

Field	Change Type	Notes
sortValues	Removed	No longer exist per result item - use startCursor and endCursor in page object.
id	Renamed	Now userTaskKey (unique system identifier of the user task).
taskDefinitionId	Renamed	Now elementId (user-provided identifier of the BPMN element).
taskState	Renamed	Now state (user task's current state).
processName	Renamed	Now processDefinitionId (user-provided identifier of the process).
formKey	Changed	Now unique system identifier referencing linked Camunda form in specific version.
isFirst	Removed	No longer identifies if task was first in process.
variables	Removed	Use search user task variables endpoint.
implementation	Removed	V2 API supports only Camunda user tasks.
isFormEmbedded	Removed	V2 API does not support embedded forms.
formVersion	Removed	Use get user task form endpoint.
formId	Removed	Use get user task form endpoint.

Unassign a task

V1	V2
PATCH /v1/tasks/{taskId}/unassign	DELETE /v2/user-tasks/{userTaskKey}/assignee

Input adjustments

• No input adjustments.

Output adjustments

• Response object removed - The V2 API returns a 204 status, indicating that the task was unassigned. Fetching the updated data of the user task should be done through the respective API since the data can change concurrently at any time.

Complete a task

V1	V2
PATCH /v1/tasks/{taskId}/complete	POST /v2/user-tasks/{userTaskKey}/completion

Input adjustments

• Adjusted attributes
  • variables - Provide the variables as a proper JSON object instead of an array of objects with a name and a serialized JSON string value.

Output adjustments

• Response object removed - The V2 API returns a 204 status, indicating that the task was completed. Fetching the updated data of the user task should be done through the respective API since the data can change concurrently at any time.

Assign a task

V1	V2
PATCH /v1/tasks/{taskId}/assign	POST /v2/user-tasks/{userTaskKey}/assignment

Input adjustments

• Renamed attributes
  • allowOverrideAssignment - Use allowOverride, this still refers to allowing to override any existing assignee.

Output adjustments

• Response object removed - The V2 API returns a 204 status, indicating that the task was assigned. Fetching the updated data of the user task should be done through the respective API since the data can change concurrently at any time.

Get a task

V1	V2
GET /v1/tasks/{taskId}	GET /v2/user-tasks/{userTaskKey}

Input adjustments

• No input adjustments.

Output adjustments

• Except for the response structure changes, all adjustments from search tasks apply.

Variables

Get a variable

V1	V2
GET /v1/variables/{variableId}	GET /v2/variables/{variableKey}

Input adjustments

• variableId - Use variableKey as this refers to the unique system identifier of the variable.

Output adjustments

• Renamed attributes
  • id - Use variableKey as this refers to the unique system identifier of the variable.
• Removed attributes
  • draft - Draft variables are not supported in V2 anymore, see also the save draft variables endpoint for further details.

Operate REST API

Decision definition

Search decision definitions

V1	V2
POST /v1/decision-definitions/search	POST /v2/decision-definitions/search

Input adjustments

Request structure changes as outlined in general changes.

Field	Change Type	Notes
searchAfter	Renamed	Now after in the page object.
size	Renamed	Now limit in the page object.
id	Renamed	Now decisionDefinitionKey in filter object.
key	Renamed	Now decisionDefinitionKey (changed from int64 to string).
decisionId	Renamed	Now decisionDefinitionId in filter object.
decisionRequirementsKey	Changed	Now string type instead of int64.
decisionRequirementsName	Removed	Can no longer be used for filtering.
decisionRequirementsVersion	Removed	Can no longer be used for filtering.

Output adjustments

Response structure changes as outlined in general changes.

Field	Change Type	Notes
total	Moved	Now totalItems in page object.
sortValues	Replaced	Now use endCursor in page object.
id	Renamed	Now decisionDefinitionKey.
key	Renamed	Now decisionDefinitionKey (changed from int64 to string).
decisionId	Renamed	Now decisionDefinitionId.
decisionRequirementsKey	Changed	Now string type instead of int64.
decisionRequirementsName	Removed	Fetch using get decision requirements endpoint.
decisionRequirementsVersion	Removed	Fetch using get decision requirements endpoint.

Get decision definition by key

V1	V2
GET /v1/decision-definitions/{key}	GET /v2/decision-definitions/{decisionDefinitionKey}

Input adjustments

• No input adjustments.

Output adjustments

• Except for the response structure changes, all adjustments from search decision definitions apply.

Search decision instances

V1	V2
POST /v1/decision-instances/search	POST /v2/decision-instances/search

Input adjustments

Request structure changes as outlined in general changes.

Field	Change Type	Notes
searchAfter	Renamed	Now after in the page object.
size	Renamed	Now limit in the page object.
id	Renamed	Now decisionInstanceId in filter object.
key	Renamed	Now decisionInstanceKey (changed from int64 to string).
processDefinitionKey	Changed	Now string type instead of int64.
processInstanceKey	Changed	Now string type instead of int64.
decisionId	Renamed	Now decisionDefinitionId.
decisionName	Renamed	Now decisionDefinitionName.
decisionVersion	Renamed	Now decisionDefinitionVersion.
decisionType	Renamed	Now decisionDefinitionType.
result	Removed	Can no longer be used for filtering.
evaluatedInputs	Removed	Can no longer be used for filtering.
evaluatedOutputs	Removed	Can no longer be used for filtering.

Output adjustments

Response structure changes as outlined in general changes.

Field	Change Type	Notes
total	Moved	Now totalItems in page object.
sortValues	Replaced	Now use endCursor in page object.
id	Renamed	Now decisionInstanceId.
key	Renamed	Now decisionInstanceKey (changed from int64 to string).
processDefinitionKey	Changed	Now string type instead of int64.
processInstanceKey	Changed	Now string type instead of int64.
decisionId	Renamed	Now decisionDefinitionId.
decisionName	Renamed	Now decisionDefinitionName.
decisionVersion	Renamed	Now decisionDefinitionVersion.
decisionType	Renamed	Now decisionDefinitionType.
evaluatedInputs	Removed	No longer provided by endpoint.
evaluatedOutputs	Removed	No longer provided by endpoint.

Get decision instance by id

V1	V2
GET /v1/decision-instances/{id}	GET /v2/decision-instances/{decisionInstanceId}

Input adjustments

• No input adjustments.

Output adjustments

The adjustments from search decision instances apply, with the following exceptions: evaluatedInputs and evaluatedOutputs are present in the response payload (with evaluatedOutputs moved under matchedRules).

Field	Change Type	Notes
evaluatedInputs object
id	Renamed	Now inputId.
name	Renamed	Now inputName.
value	Renamed	Now inputValue.
evaluatedOutputs object
id	Renamed	Now outputId.
name	Renamed	Now outputName.
value	Renamed	Now outputValue.
ruleId	Moved	Now under matchedRules array objects.
ruleIndex	Moved	Now under matchedRules array objects.

Search decision requirements

V1	V2
POST /v1/drd/search	POST /v2/decision-requirements/search

Input adjustments

Request structure changes as outlined in general changes.

Field	Change Type	Notes
searchAfter	Renamed	Now after in the page object.
size	Renamed	Now limit in the page object.
id	Renamed	Now decisionRequirementsKey in filter object.
key	Renamed	Now decisionRequirementsKey (changed from int64 to string).
name	Renamed	Now decisionRequirementsName.

Output adjustments

Response structure changes as outlined in general changes.

Field	Change Type	Notes
total	Moved	Now totalItems in page object.
sortValues	Replaced	Now use endCursor in page object.
id	Renamed	Now decisionRequirementsKey.
key	Renamed	Now decisionRequirementsKey (changed from int64 to string).
name	Renamed	Now decisionRequirementsName.

Get decision requirements by key

V1	V2
GET /v1/drd/{key}	GET /v2/decision-requirements/{decisionRequirementsKey}

Input adjustments

• No input adjustments.

Output adjustments

• Except for the response structure changes, all adjustments from search decision requirements apply.

Get decision requirements as XML by key

V1	V2
GET /v1/drd/{key}/xml	GET /v2/decision-requirements/{decisionRequirementsKey}/xml

Input adjustments

• No input adjustments.

Output adjustments

• No output adjustments.

Variable

Search variables for process instances

V1	V2
POST /v1/variables/search	POST /v2/variables/search

Input adjustments

Request structure changes as outlined in general changes.

Field	Change Type	Notes
searchAfter	Renamed	Now after in the page object.
size	Renamed	Now limit in the page object.
key	Renamed	Now variableKey (changed from int64 to string).
processInstanceKey	Changed	Now string type instead of int64.
scopeKey	Changed	Now string type instead of int64.
truncated	Renamed	Now isTruncated.

Output adjustments

Response structure changes as outlined in general changes.

Field	Change Type	Notes
total	Moved	Now totalItems in page object.
sortValues	Replaced	Now use endCursor in page object.
key	Renamed	Now variableKey (changed from int64 to string).
processInstanceKey	Changed	Now string type instead of int64.
scopeKey	Changed	Now string type instead of int64.
truncated	Renamed	Now isTruncated.

Get variable by key

V1	V2
GET /v1/variables/{key}	GET /v2/variables/{variableKey}

Input adjustments

• No input adjustments.

Output adjustments

• All adjustments from search variables for process instances apply, with the following exceptions:
  • Response structure changes.
  • truncated is removed because this endpoint always returns the full variable value.

Process definition

Search process definitions

V1	V2
POST /v1/process-definitions/search	POST /v2/process-definitions/search

Input adjustments

Request structure changes as outlined in general changes.

Field	Change Type	Notes
searchAfter	Renamed	Now after in the page object.
size	Renamed	Now limit in the page object.
key	Renamed	Now processDefinitionKey (changed from int64 to string).
bpmnProcessId	Renamed	Now processDefinitionId.

Output adjustments

Response structure changes as outlined in general changes.

Field	Change Type	Notes
total	Moved	Now totalItems in page object.
sortValues	Replaced	Now use endCursor in page object.
key	Renamed	Now processDefinitionKey (changed from int64 to string).
bpmnProcessId	Renamed	Now processDefinitionId.

Get process definition by key

V1	V2
GET /v1/process-definitions/{key}	GET /v2/process-definitions/{processDefinitionKey}

Input adjustments

• No input adjustments.

Output adjustments

• Except for the response structure changes, all adjustments from search process definitions apply.

Get process definition as XML by key

V1	V2
GET /v1/process-definitions/{key}/xml	GET /v2/process-definitions/{processDefinitionKey}/xml

Input adjustments

• No input adjustments.

Output adjustments

• No output adjustments.

Process instance

Search process instances

V1	V2
POST /v1/process-instances/search	POST /v2/process-instances/search

Input adjustments

Request structure changes as outlined in general changes.

Field	Change Type	Notes
searchAfter	Renamed	Now after in the page object.
size	Renamed	Now limit in the page object.
key	Renamed	Now processInstanceKey (changed from int64 to string).
processVersion	Renamed	Now processDefinitionVersion.
processVersionTag	Renamed	Now processDefinitionVersionTag.
bpmnProcessId	Renamed	Now processDefinitionId.
parentFlowNodeInstanceKey	Renamed	Now parentElementInstanceKey (changed to string).
parentKey	Renamed	Now parentProcessInstanceKey (changed to string).
state	Changed	Use TERMINATED instead of CANCELED.
incident	Renamed	Now hasIncident.
parentProcessInstanceKey	Changed	Now string type instead of int64.
processDefinitionKey	Changed	Now string type instead of int64.

Output adjustments

Response structure changes as outlined in general changes.

Field	Change Type	Notes
total	Moved	Now totalItems in page object.
sortValues	Replaced	Now use endCursor in page object.
key	Renamed	Now processInstanceKey (changed from int64 to string).
processVersion	Renamed	Now processDefinitionVersion.
processVersionTag	Renamed	Now processDefinitionVersionTag.
bpmnProcessId	Renamed	Now processDefinitionId.
parentFlowNodeInstanceKey	Renamed	Now parentElementInstanceKey (changed to string).
parentKey	Renamed	Now parentProcessInstanceKey (changed to string).
state	Changed	Use TERMINATED instead of CANCELED.
incident	Renamed	Now hasIncident.
parentProcessInstanceKey	Changed	Now string type instead of int64.
processDefinitionKey	Changed	Now string type instead of int64.

Get process instance by key

V1	V2
GET /v1/process-instances/{key}	GET /v2/process-instances/{processInstanceKey}

Input adjustments

• No input adjustments.

Output adjustments

• Except for the response structure changes, all adjustments from search process instances apply.

Delete process instance and all dependant data by key

V1	V2
DELETE /v1/process-instances/{key}	This feature is not yet available in V2. It will be added in a future version.

Get flow node statistic by process instance key

V1	V2
GET /v1/process-instances/{key}/statistics	GET /v2/process-instances/{processInstanceKey}/statistics/element-instances

Input adjustments

• No input adjustments.

Output adjustments

Response structure changes.

Field	Change Type	Notes
Response items	Moved	Now under items array
activityId	Renamed	Now elementId

Get sequence flows of process instance by key

V1	V2
GET /v1/process-instances/{key}/sequence-flows	GET /v2/process-instances/{processInstanceKey}/sequence-flows

Input adjustments

• No input adjustments.

Output adjustments

Response structure changes.

Field	Change Type	Notes
Response items	Changed	Now type object instead of string.
Response items	Moved	Now under items array.
V1 recreation	Info	Collect sequenceFlowId of type string from all objects to recreate V1 result.

Flownode instances

Search flownode instances

V1	V2
POST /v1/flownode-instances/search	POST /v2/element-instances/search

Input adjustments

Request structure changes as outlined in general changes.

Field	Change Type	Notes
searchAfter	Renamed	Now after in the page object.
size	Renamed	Now limit in the page object.
key	Renamed	Now elementInstanceKey (changed from int64 to string).
flowNodeId	Renamed	Now elementId.
flowNodeName	Renamed	Now elementName.
incident	Renamed	Now hasIncident.
processInstanceKey	Changed	Now string type instead of int64.
processDefinitionKey	Changed	Now string type instead of int64.
incidentKey	Changed	Now string type instead of int64.
startDate	Removed	Can no longer be used for filtering.
endDate	Removed	Can no longer be used for filtering.

Output adjustments

Response structure changes as outlined in general changes.

Field	Change Type	Notes
total	Moved	Now totalItems in page object.
sortValues	Replaced	Now use endCursor in page object.
key	Renamed	Now elementInstanceKey (changed from int64 to string).
flowNodeId	Renamed	Now elementId.
flowNodeName	Renamed	Now elementName.
incident	Renamed	Now hasIncident.
processInstanceKey	Changed	Now string type instead of int64.
processDefinitionKey	Changed	Now string type instead of int64.
incidentKey	Changed	Now string type instead of int64.

Get flownode instance by key

V1	V2
GET /v1/flownode-instances/{key}	GET /v2/element-instances/{elementInstanceKey}

Input adjustments

• No input adjustments.

Output adjustments

• Except for the response structure changes, all adjustments from search flownode instances apply.

Incidents

Search incidents

V1	V2
POST /v1/incidents/search	POST /v2/incidents/search

Input adjustments

Request structure changes as outlined in general changes.

Field	Change Type	Notes
searchAfter	Renamed	Now after in the page object.
size	Renamed	Now limit in the page object.
key	Renamed	Now incidentKey (changed from int64 to string).
type	Renamed	Now errorType.
message	Renamed	Now errorMessage.
processInstanceKey	Changed	Now string type instead of int64.
processDefinitionKey	Changed	Now string type instead of int64.
jobKey	Changed	Now string type instead of int64.

Output adjustments

Response structure changes as outlined in general changes.

Field	Change Type	Notes
total	Moved	Now totalItems in page object.
sortValues	Replaced	Now use endCursor in page object.
key	Renamed	Now incidentKey (changed from int64 to string).
type	Renamed	Now errorType.
message	Renamed	Now errorMessage.
processInstanceKey	Changed	Now string type instead of int64.
processDefinitionKey	Changed	Now string type instead of int64.
jobKey	Changed	Now string type instead of int64.

Get incident by key

V1	V2
GET /v1/incidents/{key}	GET /v2/incidents/{incidentKey}

Input adjustments

• No input adjustments.

Output adjustments

• Except for the response structure changes, all adjustments from search incidents apply.