Clock backing SDK-internal cadence. The injected one when supplied, else the live clock.
Internal accessor for support logger (no public API commitment yet).
Internal invocation helper to apply global backpressure gating + retry + normalization
Activate activities within an ad-hoc sub-process
Activates selected activities within an ad-hoc sub-process identified by element ID. The provided element IDs must exist within the ad-hoc sub-process instance identified by the provided adHocSubProcessInstanceKey.
Optionaloptions: OperationOptionsasync function activateAdHocSubProcessActivitiesExample(
adHocSubProcessInstanceKey: ElementInstanceKey,
elementId: ElementId
) {
const camunda = createCamundaClient();
await camunda.activateAdHocSubProcessActivities({
adHocSubProcessInstanceKey,
elements: [{ elementId }],
});
}
Activate jobs
Iterate through all known partitions and activate jobs up to the requested maximum.
Optionaloptions: OperationOptionsasync function activateJobsExample() {
const camunda = createCamundaClient();
const result = await camunda.activateJobs({
type: 'payment-processing',
timeout: 30000,
maxJobsToActivate: 5,
});
for (const job of result.jobs) {
console.log(`Job ${job.jobKey}: ${job.type}`);
// Each enriched job has helper methods
await job.complete({ paymentId: 'PAY-123' });
}
}
Activate jobs
Iterate through all known partitions and activate jobs up to the requested maximum.
Optionaloptions: OperationOptionsasync function activateJobsExample() {
const camunda = createCamundaClient();
const result = await camunda.activateJobs({
type: 'payment-processing',
timeout: 30000,
maxJobsToActivate: 5,
});
for (const job of result.jobs) {
console.log(`Job ${job.jobKey}: ${job.type}`);
// Each enriched job has helper methods
await job.complete({ paymentId: 'PAY-123' });
}
}
Activate jobs
Iterate through all known partitions and activate jobs up to the requested maximum.
Optionaloptions: OperationOptionsasync function activateJobsExample() {
const camunda = createCamundaClient();
const result = await camunda.activateJobs({
type: 'payment-processing',
timeout: 30000,
maxJobsToActivate: 5,
});
for (const job of result.jobs) {
console.log(`Job ${job.jobKey}: ${job.type}`);
// Each enriched job has helper methods
await job.complete({ paymentId: 'PAY-123' });
}
}
Assign a client to a group
Assigns a client to a group, making it a member of the group. Members of the group inherit the group authorizations, roles, and tenant assignments.
Optionaloptions: OperationOptionsAssign a client to a tenant
Assign the client to the specified tenant. The client can then access tenant data and perform authorized actions.
Optionaloptions: OperationOptionsAssign a group to a tenant
Assigns a group to a specified tenant. Group members (users, clients) can then access tenant data and perform authorized actions.
Optionaloptions: OperationOptionsAssign a mapping rule to a group
Assigns a mapping rule to a group. *
Optionaloptions: OperationOptionsAssign a mapping rule to a tenant
Assign a single mapping rule to a specified tenant. *
Optionaloptions: OperationOptionsAssign business id to process instance
Assigns a business id to an already-running process instance that currently has none.
The assignment is single and irreversible: only artifacts created after the assignment (for example future jobs, user tasks, decision instances, and message subscriptions) carry the business id, while existing artifacts are not retroactively enriched. Re-sending the same business id succeeds as a no-op. This endpoint is only useful while business id uniqueness enforcement is disabled; when it is enabled, the request is rejected with a 409 response.
Optionaloptions: OperationOptionsAssign a role to a client
Assigns the specified role to the client. The client will inherit the authorizations associated with this role. *
Optionaloptions: OperationOptionsAssign a role to a group
Assigns the specified role to the group. Every member of the group (user or client) will inherit the authorizations associated with this role. *
Optionaloptions: OperationOptionsAssign a role to a mapping rule
Assigns a role to a mapping rule. *
Optionaloptions: OperationOptionsAssign a role to a tenant
Assigns a role to a specified tenant. Users, Clients or Groups, that have the role assigned, will get access to the tenant's data and can perform actions according to their authorizations.
Optionaloptions: OperationOptionsAssign a role to a user
Assigns the specified role to the user. The user will inherit the authorizations associated with this role. *
Optionaloptions: OperationOptionsAssign user task
Assigns a user task with the given key to the given assignee. Assignment waits for blocking task listeners on this lifecycle transition. If listener processing is delayed beyond the request timeout, this endpoint can return 504. Other gateway timeout causes are also possible. Retry with backoff and inspect listener worker availability and logs when this repeats.
Optionaloptions: OperationOptionsAssign a user to a group
Assigns a user to a group, making the user a member of the group. Group members inherit the group authorizations, roles, and tenant assignments.
Optionaloptions: OperationOptionsAssign a user to a tenant
Assign a single user to a specified tenant. The user can then access tenant data and perform authorized actions. *
Optionaloptions: OperationOptionsBroadcast signal
Broadcasts a signal. *
Optionaloptions: OperationOptionsCancel Batch operation
Cancels a running batch operation. This is done asynchronously, the progress can be tracked using the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Optionaloptions: OperationOptionsStop the running rebalance
Asks the running rebalance to stop once the transfer in flight has finished. Partitions already transferred keep their new leaders, and those the rebalance had not yet reached keep their current ones.
Cancellation requests are idempotent and always accepted. The wasRunning response field can be used to distinguish a cancellation that found a running rebalance from one that did not.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here.
*
Optionaloptions: OperationOptionsCancel process instance
Cancels a running process instance. As a cancellation includes more than just the removal of the process instance resource, the cancellation resource must be posted. Cancellation can wait on listener-related processing; when that processing does not complete in time, this endpoint can return 504. Other gateway timeout causes are also possible. Retry with backoff and inspect listener worker availability and logs when this repeats.
Optionaloptions: OperationOptionsasync function cancelProcessInstanceExample(processDefinitionId: ProcessDefinitionId) {
const camunda = createCamundaClient();
// Create a process instance and get its key from the response
const created = await camunda.createProcessInstance({
processDefinitionId,
});
// Cancel the process instance using the key from the creation response
await camunda.cancelProcessInstance({
processInstanceKey: created.processInstanceKey,
});
}
Cancel process instances (batch)
Cancels multiple active or suspended process instances.
Only ACTIVE and SUSPENDED root instances can be cancelled. A state filter narrows the batch
to the given states. Requesting any state other than ACTIVE or SUSPENDED through the $eq or
$in operators is rejected. Other state operators ($neq, $exists, $like) are applied as
given, and the batch remains limited to ACTIVE and SUSPENDED instances. Without a state filter,
both ACTIVE and SUSPENDED instances are selected. Any given filter for parentProcessInstanceKey
is ignored and overridden during this batch operation.
This is done asynchronously, the progress can be tracked using the batchOperationKey from the response and the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Optionaloptions: OperationOptionsasync function cancelProcessInstancesBatchOperationExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const result = await camunda.cancelProcessInstancesBatchOperation({
filter: {
processDefinitionKey,
},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Change cluster mode
Transitions the cluster between processing and recovery mode. This is a non-blocking operation: the request is acknowledged once the change has been accepted, before the transition itself has completed. Entering recovery mode deactivates all partitions so that only a restricted set of read-only operations remains available; exiting recovery mode returns the cluster to normal processing. Returns the planned cluster change so its progress can be monitored via the topology. *
Optionaloptions: OperationOptionsasync function changeClusterModeExample() {
const camunda = createCamundaClient();
// Transition the cluster into recovery mode. Pass `dryRun: true` to validate
// the request and inspect the resulting plan without applying it. Omit it (or
// set it to false) to actually trigger the transition.
const change = await camunda.changeClusterMode({
mode: 'RECOVERING',
dryRun: true,
});
// Operations are grouped by physical tenant; a null tenant means the operation
// is not scoped to one, such as a broker lifecycle operation.
console.log(`Cluster change ${change.changeId}:`);
for (const group of change.plannedChanges) {
console.log(` ${group.physicalTenantId ?? 'cluster-wide'}:`);
for (const op of group.operations) {
console.log(` ${op.operation}${op.mode ? ` -> ${op.mode}` : ''}`);
}
}
}
Change the cluster mode of one or every physical tenant
Transitions physical tenants between processing and recovery mode.
If the physicalTenantId parameter is not provided, all available physical tenants are transitioned individually.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here.
*
Optionaloptions: OperationOptionsasync function changeClusterModeAsClusterAdminExample() {
const camunda = createCamundaClient();
// The cluster-admin variant can target a single physical tenant. Omit
// `physicalTenantId` to apply the change to every physical tenant.
const change = await camunda.changeClusterModeAsClusterAdmin({
mode: 'RECOVERING',
physicalTenantId: 'default',
dryRun: true,
});
console.log(`Cluster change ${change.changeId}:`);
for (const group of change.plannedChanges) {
console.log(` ${group.physicalTenantId ?? 'cluster-wide'}:`);
for (const op of group.operations) {
console.log(` ${op.operation}${op.mode ? ` -> ${op.mode}` : ''}`);
}
}
}
Optionalopts: { disk?: boolean; memory?: boolean }Complete job
Complete a job with the given payload, which allows completing the associated service task.
Optionaloptions: OperationOptionsComplete user task
Completes a user task with the given key. Completion waits for blocking task listeners on this lifecycle transition. If listener processing is delayed beyond the request timeout, this endpoint can return 504. Other gateway timeout causes are also possible. Retry with backoff and inspect listener worker availability and logs when this repeats.
Optionaloptions: OperationOptionsCorrelate message
Publishes a message and correlates it to a subscription. If correlation is successful it will return the first process instance key the message correlated with. The message is not buffered. Use the publish message endpoint to send messages that can be buffered.
Optionaloptions: OperationOptionsasync function correlateMessageExample() {
const camunda = createCamundaClient();
const result = await camunda.correlateMessage({
name: 'order-payment-received',
correlationKey: 'ORD-12345',
variables: {
paymentId: 'PAY-123',
amount: 99.95,
},
});
console.log(`Message correlated to: ${result.processInstanceKey}`);
}
Create admin user
Creates a new user and assigns the admin role to it. This endpoint is only usable when users are managed in the Orchestration Cluster and while no user is assigned to the admin role. *
Optionaloptions: OperationOptionsasync function createAdminUserExample(username: Username) {
const camunda = createCamundaClient();
const result = await camunda.createAdminUser({
username,
name: 'Admin User',
email: 'admin@example.com',
password: 'admin-password-123',
});
console.log(`Created admin user: ${result.username}`);
}
Create agent instance
Creates a new agent instance. The returned key identifies the instance and must be used in subsequent update and query calls.
Optionaloptions: OperationOptionsasync function createAgentInstanceExample(
elementInstanceKey: ElementInstanceKey,
jobKey: JobKey,
jobLeaseToken: JobLeaseToken
) {
const camunda = createCamundaClient();
// The batch must open with a CONFIGURATION item; it establishes the model,
// provider and system prompt for the instance.
const result = await camunda.createAgentInstance({
elementInstanceKey,
jobKey,
jobLeaseToken,
history: [
{
historyItemId: HistoryItemId.assumeExists('configuration-1'),
loopIteration: 1,
role: 'CONFIGURATION',
content: [],
producedAt: new Date().toISOString(),
model: 'gpt-4o',
provider: 'openai',
systemPrompt: [{ contentType: 'TEXT', text: 'You are a helpful assistant.' }],
},
],
});
console.log(`Created agent instance: ${result.agentInstanceKey}`);
}
Create authorization
Create the authorization. *
Optionaloptions: OperationOptionsasync function createAuthorizationExample() {
const camunda = createCamundaClient();
const result = await camunda.createAuthorization({
ownerId: 'user-123',
ownerType: 'USER',
resourceId: 'order-process',
resourceType: 'PROCESS_DEFINITION',
permissionTypes: ['CREATE_PROCESS_INSTANCE', 'READ_PROCESS_INSTANCE'],
});
console.log(`Authorization key: ${result.authorizationKey}`);
}
Deploy resources
Deploys one or more resources, including BPMN processes, DMN decision models, forms, RPA resources, and generic files. A deployment can contain any file type. Files that are not interpreted as BPMN, DMN, form, or RPA resources are stored as deployable generic resources in the engine. This is an atomic call, i.e. either all resources are deployed or none of them are.
Optionaloptions: OperationOptionsEnriched deployment result with typed arrays (processes, decisions, decisionRequirements, forms, resources).
async function deployResourcesFromFilesExample() {
const camunda = createCamundaClient();
// Node.js only: deploy directly from file paths
const result = await camunda.deployResourcesFromFiles(['./process.bpmn', './decision.dmn']);
console.log(`Deployment key: ${result.deploymentKey}`);
}
Upload document
Upload a document to the Camunda 8 cluster.
Note that this is currently supported for document stores of type: AWS, Azure, GCP, in-memory (non-production), local (non-production)
Optionaloptions: OperationOptionsasync function createDocumentExample() {
const camunda = createCamundaClient();
const file = new Blob(['Hello, world!'], { type: 'text/plain' });
const result = await camunda.createDocument({
file,
metadata: { fileName: 'hello.txt' },
});
console.log(`Document ID: ${result.documentId}`);
}
Create document link
Create a link to a document in the Camunda 8 cluster.
Note that this is currently supported for document stores of type: AWS, Azure, GCP
Optionaloptions: OperationOptionsUpload multiple documents
Upload multiple documents to the Camunda 8 cluster.
The caller must provide a file name for each document, which will be used in case of a multi-status response
to identify which documents failed to upload. The file name can be provided in the Content-Disposition header
of the file part or in the fileName field of the metadata. You can add a parallel array of metadata objects. These
are matched with the files based on index, and must have the same length as the files array.
To pass homogenous metadata for all files, spread the metadata over the metadata array.
A filename value provided explicitly via the metadata array in the request overrides the Content-Disposition header
of the file part.
In case of a multi-status response, the response body will contain a list of DocumentBatchProblemDetail objects,
each of which contains the file name of the document that failed to upload and the reason for the failure.
The client can choose to retry the whole batch or individual documents based on the response.
Note that this is currently supported for document stores of type: AWS, Azure, GCP, in-memory (non-production), local (non-production)
Optionaloptions: OperationOptionsasync function createDocumentsExample() {
const camunda = createCamundaClient();
const file1 = new Blob(['File one'], { type: 'text/plain' });
const file2 = new Blob(['File two'], { type: 'text/plain' });
const result = await camunda.createDocuments({
files: [file1, file2],
metadataList: [{ fileName: 'one.txt' }, { fileName: 'two.txt' }],
});
for (const doc of result.createdDocuments ?? []) {
console.log(`Created: ${doc.documentId}`);
}
}
Update element instance variables
Updates all the variables of a particular scope (for example, process instance, element instance) with the given variable data.
Specify the element instance in the elementInstanceKey parameter.
Variable updates can be delayed by listener-related processing; if processing exceeds the
request timeout, this endpoint can return 504. Other gateway timeout causes are also
possible. Retry with backoff and inspect listener worker availability and logs when this
repeats.
Optionaloptions: OperationOptionsasync function createElementInstanceVariablesExample(elementInstanceKey: ElementInstanceKey) {
const camunda = createCamundaClient();
await camunda.createElementInstanceVariables({
elementInstanceKey,
variables: { orderId: 'ORD-12345', status: 'processing' },
});
}
Create a global-scoped cluster variable
Create a global-scoped cluster variable. *
Optionaloptions: OperationOptionsCreate global user task listener
Create a new global user task listener. *
Optionaloptions: OperationOptionsasync function createGlobalTaskListenerExample(id: GlobalListenerId) {
const camunda = createCamundaClient();
const result = await camunda.createGlobalTaskListener({
id,
eventTypes: ['completing'],
type: 'audit-log-listener',
});
console.log(`Created listener: ${result.id}`);
}
Create group
Create a new group.
The supplied groupId is validated against ^[a-zA-Z0-9_~@.+-]+$
(max 256 characters) by IdentifierValidator.validateId in the
runtime. This strict validation applies wherever the Groups API
is available: in OIDC deployments that set
camunda.security.authentication.oidc.groupsClaim the Groups
API (including this endpoint) is disabled entirely, so group
CRUD never sees externally-minted IdP IDs. The BYOG relaxation
only loosens validation when a group is referenced as a member
of a role or tenant (assignRoleToGroup,
assignGroupToTenant); group CRUD itself always uses the strict
default-id regex. The constraint is not advertised on the
GroupId schema so that the same schema can be reused at
member-reference sites without falsely rejecting
externally-minted IdP group IDs there.
Optionaloptions: OperationOptionsCreate a job worker that activates and processes jobs of the given type.
Worker configuration fields inherit global defaults resolved via the
unified configuration (environment variables or equivalent CAMUNDA_WORKER_*
keys provided via CamundaOptions.config) when not explicitly set on the
config object.
Worker configuration
async function createJobWorkerExample() {
const camunda = createCamundaClient();
const _worker = camunda.createJobWorker({
jobType: 'payment-processing',
jobTimeoutMs: 30000,
maxParallelJobs: 5,
jobHandler: async (job): Promise<JobActionReceipt> => {
console.log(`Processing job ${job.jobKey}`);
return job.complete({ processed: true });
},
});
// Workers run continuously until closed
// worker.close();
}
async function jobWorkerWithErrorHandlingExample() {
const camunda = createCamundaClient();
const worker = camunda.createJobWorker({
jobType: 'email-sending',
jobTimeoutMs: 60000,
maxParallelJobs: 10,
pollIntervalMs: 300,
jobHandler: async (job): Promise<JobActionReceipt> => {
try {
console.log(`Sending email for job ${job.jobKey}`);
return job.complete({ sent: true });
} catch (err) {
return job.fail({
errorMessage: String(err),
retries: (job.retries ?? 1) - 1,
});
}
},
});
void worker;
}
Create mapping rule
Create a new mapping rule
Optionaloptions: OperationOptionsasync function createMappingRuleExample(mappingRuleId: MappingRuleId) {
const camunda = createCamundaClient();
const result = await camunda.createMappingRule({
mappingRuleId,
name: 'LDAP Group Mapping',
claimName: 'groups',
claimValue: 'engineering',
});
console.log(`Created mapping rule: ${result.mappingRuleId}`);
}
Create process instance
Creates and starts an instance of the specified process. The process definition to use to create the instance can be specified either using its unique key (as returned by Deploy resources), or using the BPMN process id and a version. If only the process definition id is given, the latest ACTIVE version is used. If no ACTIVE version exists, the request is rejected as not found.
Waits for the completion of the process instance before returning a result when awaitCompletion is enabled.
Optionaloptions: OperationOptionsasync function createProcessInstanceByIdExample(processDefinitionId: ProcessDefinitionId) {
const camunda = createCamundaClient();
const result = await camunda.createProcessInstance({
processDefinitionId,
variables: {
orderId: 'ORD-12345',
amount: 99.95,
},
});
console.log(`Started process instance: ${result.processInstanceKey}`);
}
async function createProcessInstanceByKeyExample(processDefinitionKey: ProcessDefinitionKey) {
const camunda = createCamundaClient();
// Key from a previous API response (e.g. deployment)
const result = await camunda.createProcessInstance({
processDefinitionKey,
variables: {
orderId: 'ORD-12345',
amount: 99.95,
},
});
console.log(`Started process instance: ${result.processInstanceKey}`);
}
Create role
Create a new role. *
Optionaloptions: OperationOptionsCreate tenant
Creates a new tenant. *
Optionaloptions: OperationOptionsCreate a tenant-scoped cluster variable
Create a new cluster variable for the given tenant. *
Optionaloptions: OperationOptionsasync function createTenantClusterVariableExample(tenantId: TenantId, name: ClusterVariableName) {
const camunda = createCamundaClient();
const result = await camunda.createTenantClusterVariable({
tenantId,
name,
value: { region: 'us-east-1' },
});
console.log(`Created: ${result.name}`);
}
Create a threaded job worker that runs handler logic in a pool of worker threads.
The handler must be a separate module file that exports a default function with
signature (job, client) => Promise<JobActionReceipt>.
This keeps the main event loop free for polling and I/O, dramatically improving throughput for CPU-bound job handlers.
Worker configuration fields inherit global defaults resolved via the
unified configuration (environment variables or equivalent CAMUNDA_WORKER_*
keys provided via CamundaOptions.config) when not explicitly set on the
config object.
Threaded worker configuration
Create user
Create a new user. *
Optionaloptions: OperationOptionsasync function createUserExample(username: Username) {
const camunda = createCamundaClient();
const result = await camunda.createUser({
username,
name: 'Alice Smith',
email: 'alice@example.com',
password: 'secure-password-123',
});
console.log(`Created user: ${result.username}`);
}
Delete authorization
Deletes the authorization with the given key. *
Optionaloptions: OperationOptionsDelete decision instance
Delete all associated decision evaluations based on provided key. *
Optionaloptions: OperationOptionsDelete decision instances (batch)
Delete multiple decision instances. This will delete the historic data from secondary storage. This is done asynchronously, the progress can be tracked using the batchOperationKey from the response and the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Optionaloptions: OperationOptionsDelete document
Delete a document from the Camunda 8 cluster.
Note that this is currently supported for document stores of type: AWS, Azure, GCP, in-memory (non-production), local (non-production)
Optionaloptions: OperationOptionsDelete a global-scoped cluster variable
Delete a global-scoped cluster variable. *
Optionaloptions: OperationOptionsDelete global user task listener
Deletes a global user task listener. *
Optionaloptions: OperationOptionsDelete group
Deletes the group with the given ID. *
Optionaloptions: OperationOptionsDelete history backup
Deletes the history backup with the given id, by deleting every snapshot that makes it up.
Only available on clusters whose secondary storage is Elasticsearch or OpenSearch.
Optionaloptions: OperationOptionsDelete a history backup across physical tenants
Deletes the history backup with the given id from every physical tenant of the cluster, or from the one named by physicalTenantId. A tenant that does not hold the backup has already reached the requested end state, so it counts as deleted rather than as a failure.
The request is all-or-nothing: a physical tenant the backup cannot be deleted from fails the whole request, and the deletions that already succeeded on other tenants are not undone. Narrow the request with physicalTenantId to delete from the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Only available on clusters whose secondary storage is Elasticsearch or OpenSearch. Use DELETE /v2/backups/history/{backupId} to act as a single physical tenant.
*
Optionaloptions: OperationOptionsasync function deleteHistoryBackupAsClusterAdminExample() {
const camunda = createCamundaClient();
// Deletion fans out to every physical tenant (or a single one when
// `physicalTenantId` is given) and is not undone if a later tenant fails.
await camunda.deleteHistoryBackupAsClusterAdmin({ backupId: 100 });
}
Delete a mapping rule
Deletes the mapping rule with the given ID.
Optionaloptions: OperationOptionsDelete process instance
Deletes a process instance. Only instances that are completed or terminated can be deleted. *
Optionaloptions: OperationOptionsDelete process instances (batch)
Delete multiple process instances. This will delete the historic data from secondary storage. Only process instances in a final state (COMPLETED or TERMINATED) can be deleted. This is done asynchronously, the progress can be tracked using the batchOperationKey from the response and the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Optionaloptions: OperationOptionsasync function deleteProcessInstancesBatchOperationExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const result = await camunda.deleteProcessInstancesBatchOperation({
filter: {
processDefinitionKey,
},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Delete resource
Deletes a deployed resource. This can be a process definition, decision requirements
definition, or form definition deployed using the deploy resources endpoint. Specify the
resource you want to delete in the resourceKey parameter.
Once a resource has been deleted it cannot be recovered. If the resource needs to be available again, a new deployment of the resource is required.
By default, only the resource itself is deleted from the runtime state. To also delete the
historic data associated with a resource, set the deleteHistory flag in the request body
to true. History deletion is supported for process definitions and decision requirements
definitions; for other resource types (forms, generic resources) the flag is ignored and no
history is deleted.
The two supported types differ in how the history is removed. For a decision requirements
definition the history is deleted asynchronously via a batch operation whose details are
returned in the batchOperation field of the response. For a process definition that still
exists in the runtime state, the definition first drains its running instances and its
history is deleted asynchronously once the definition is fully removed cluster-wide; no batch
operation is returned in the response. If the process definition has already been removed
from the runtime state and the deletion is later re-triggered with deleteHistory set to
true, a batch operation is created immediately and returned in the batchOperation field.
*
OptionaldeleteHistory?: booleanIndicates if the historic data associated with the resource should also be deleted asynchronously.
This flag is effective for process definitions and decision requirements definitions.
For other resource types (forms, generic resources) it is ignored and no history is
deleted. For a decision requirements definition the batchOperation field in the
response carries the created batch operation. For a process definition the history is
deleted as part of the definition's draining/deletion lifecycle and no batch operation is
returned.
OptionaloperationReference?: numberOptionaloptions: OperationOptionsDelete role
Deletes the role with the given ID. *
Optionaloptions: OperationOptionsDelete runtime backup
Deletes the runtime backup with the given id. *
Optionaloptions: OperationOptionsDelete a runtime backup across physical tenants
Deletes the runtime backup with the given id from every physical tenant of the cluster, or from the one named by physicalTenantId. A tenant that does not hold the backup has already reached the requested end state, so it counts as deleted rather than as a failure — the same as deleting an unknown backup id through the per-physical-tenant endpoint.
The request is all-or-nothing: a physical tenant the backup cannot be deleted from fails the whole request, and the deletions that already succeeded on other tenants are not undone. Narrow the request with physicalTenantId to delete from the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use DELETE /v2/backups/runtime/{backupId} to act as a single physical tenant.
*
Optionaloptions: OperationOptionsasync function deleteRuntimeBackupAsClusterAdminExample() {
const camunda = createCamundaClient();
// Deletion fans out to every physical tenant (or a single one when
// `physicalTenantId` is given) and is not undone if a later tenant fails.
await camunda.deleteRuntimeBackupAsClusterAdmin({ backupId: 100 });
}
Delete runtime backup state
Resets the runtime backup state of every partition of the physical tenant, clearing all checkpoint info, backup info, checkpoint metadata, and backup ranges. Used when switching backup stores.
Optionaloptions: OperationOptionsasync function deleteRuntimeBackupStateExample() {
const camunda = createCamundaClient();
// Clears all checkpoint info, backup info, checkpoint metadata, and backup
// ranges on every partition. Used when switching backup stores.
await camunda.deleteRuntimeBackupState();
}
Delete runtime backup state across physical tenants
Resets the runtime backup state of every partition of every physical tenant of the cluster, or of the one named by physicalTenantId, clearing all checkpoint info, backup info, checkpoint metadata, and backup ranges. Used when switching backup stores.
The request is all-or-nothing: a physical tenant whose state cannot be reset fails the whole request, and the resets that already succeeded on other tenants are not undone. Narrow the request with physicalTenantId to reset the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use DELETE /v2/backups/runtime/state to act as a single physical tenant.
*
Optionaloptions: OperationOptionsasync function deleteRuntimeBackupStateAsClusterAdminExample() {
const camunda = createCamundaClient();
// Clears all checkpoint info, backup info, checkpoint metadata, and backup
// ranges on every partition of every targeted physical tenant (or a single one
// when `physicalTenantId` is given). Used when switching backup stores.
await camunda.deleteRuntimeBackupStateAsClusterAdmin({});
}
Delete tenant
Deletes an existing tenant. *
Optionaloptions: OperationOptionsDelete a tenant-scoped cluster variable
Delete a tenant-scoped cluster variable. *
Optionaloptions: OperationOptionsDelete user
Deletes a user. *
Optionaloptions: OperationOptionsNode-only convenience: deploy resources from local filesystem paths.
Absolute or relative file paths to BPMN/DMN/form/resource files.
Optionaloptions: { tenantId?: string }
Optional: tenantId.
ExtendedDeploymentResult
Emit the standard support log preamble & redacted configuration to the current support logger. Safe to call multiple times; subsequent calls are ignored (idempotent). Useful when a custom supportLogger was injected and you still want the canonical header & config dump.
Evaluate root level conditional start events
Evaluates root-level conditional start events for process definitions. If the evaluation is successful, it will return the keys of all created process instances, along with their associated process definition key. Multiple root-level conditional start events of the same process definition can trigger if their conditions evaluate to true.
Optionaloptions: OperationOptionsEvaluate decision
Evaluates a decision. You specify the decision to evaluate either by using its unique key (as returned by DeployResource), or using the decision ID. When using the decision ID, the latest deployed version of the decision is used.
Optionaloptions: OperationOptionsasync function evaluateDecisionByIdExample(decisionDefinitionId: DecisionDefinitionId) {
const camunda = createCamundaClient();
const result = await camunda.evaluateDecision({
decisionDefinitionId,
variables: {
amount: 1000,
invoiceCategory: 'Misc',
},
});
console.log(`Decision: ${result.decisionDefinitionId}`);
console.log(`Output: ${result.output}`);
}
async function evaluateDecisionByKeyExample(decisionDefinitionKey: DecisionDefinitionKey) {
const camunda = createCamundaClient();
const result = await camunda.evaluateDecision({
decisionDefinitionKey,
variables: {
amount: 1000,
invoiceCategory: 'Misc',
},
});
console.log(`Decision output: ${result.output}`);
}
Evaluate an expression
Evaluates a FEEL expression and returns the result. Supports references to tenant scoped
cluster variables when a tenant ID is provided. Optionally, provide a scopeKey to make the
variables of a specific process instance or element instance visible while evaluating the
expression.
Optionaloptions: OperationOptionsFail job
Mark the job as failed.
Optionaloptions: OperationOptionsGet agent definition
Returns an agent definition by key. *
Optionaloptions: OperationOptionsasync function getAgentDefinitionExample(agentDefinitionKey: AgentDefinitionKey) {
const camunda = createCamundaClient();
const definition = await camunda.getAgentDefinition(
{ agentDefinitionKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Name: ${definition.name}`);
console.log(`Type: ${definition.agentType}`);
console.log(`Element: ${definition.elementId}`);
}
Get agent instance
Returns agent instance as JSON. *
Optionaloptions: OperationOptionsasync function getAgentInstanceExample(agentInstanceKey: AgentInstanceKey) {
const camunda = createCamundaClient();
const instance = await camunda.getAgentInstance(
{ agentInstanceKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Status: ${instance.status}`);
console.log(`Element: ${instance.elementId}`);
}
Get audit log
Get an audit log entry by auditLogKey. *
Optionaloptions: OperationOptionsGet current user
Retrieves the current authenticated user. *
Optionaloptions: OperationOptionsGet authorization
Get authorization by the given key. *
Optionaloptions: OperationOptionsasync function getAuthorizationExample(authorizationKey: AuthorizationKey) {
const camunda = createCamundaClient();
const authorization = await camunda.getAuthorization(
{ authorizationKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Owner: ${authorization.ownerId} (${authorization.ownerType})`);
}
Public accessor for current backpressure adaptive limiter state (stable)
Get batch operation
Get batch operation by key. *
Optionaloptions: OperationOptionsasync function getBatchOperationExample(batchOperationKey: BatchOperationKey) {
const camunda = createCamundaClient();
const batch = await camunda.getBatchOperation(
{ batchOperationKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Batch: ${batch.batchOperationType} (${batch.state})`);
}
Get exporting status of the whole cluster
Returns the exporting status of the whole cluster, folded over the exporting status of every physical tenant. Only PAUSED and SOFT_PAUSED confirm that exporting is paused cluster-wide; every other value means at least one physical tenant is not paused, so callers should keep polling. A physical tenant that itself reports MIXED makes the whole cluster MIXED.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here.
*
Optionaloptions: OperationOptionsasync function getClusterExportingStatusExample() {
const camunda = createCamundaClient();
// Reports the aggregated exporting status of the whole cluster — useful to
// confirm exporting has paused everywhere before taking a cluster-wide backup.
const { status } = await camunda.getClusterExportingStatus();
console.log(`Cluster exporting status: ${status}`);
}
Report the cluster's current leadership balance
Reports whether the cluster is currently balanced, the current leadership state of every partition, and what became of the last rebalance to finish. The last completed rebalance is held in memory by the coordinating broker, so none will be reported if the coordinator has moved or restarted since the last rebalance.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here.
*
Optionaloptions: OperationOptionsasync function getClusterRebalanceExample() {
const camunda = createCamundaClient();
const balance = await camunda.getClusterRebalance();
console.log(`Cluster balance state: ${balance.state}`);
for (const partition of balance.partitions) {
console.log(
` Partition ${partition.partitionId}: state=${partition.state}, currentLeader=${partition.currentLeader}, desiredLeader=${partition.desiredLeader}`
);
}
if (balance.runningRebalance) {
console.log(`Running rebalance id=${balance.runningRebalance.rebalanceId}`);
}
}
Get the status of the whole cluster
Checks the health status of the whole cluster, aggregated over all physical tenants. Returns HEALTHY when every physical tenant is healthy, DOWN when no physical tenant can process work, and DEGRADED in every other case. No per-tenant detail is reported; use GET /cluster/v2/topology for that.
This endpoint is public and requires no authentication, unlike PATCH /cluster/v2/mode below, which needs cluster-admin credentials.
*
Optionaloptions: OperationOptionsGet the topology of the whole cluster
Obtains the topology of the whole cluster, aggregated over all physical tenants. Cluster-level information is reported once; partition layout, replication and per-partition role, health and state are reported per physical tenant.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use GET /v2/topology for the topology of a single physical tenant.
*
Optionaloptions: OperationOptionsasync function getClusterTopologyExample() {
const camunda = createCamundaClient();
// Returns the full cluster topology: brokers, physical tenants (in a
// multi-tenant cluster), cluster size, and gateway version.
const topology = await camunda.getClusterTopology();
console.log(
`Cluster ${topology.clusterId} — ${topology.clusterSize} broker(s), gateway ${topology.gatewayVersion}`
);
for (const broker of topology.brokers) {
console.log(` Broker ${broker.brokerId}: ${broker.host}:${broker.port} (${broker.version})`);
}
for (const tenant of topology.physicalTenants) {
console.log(
` Physical tenant ${tenant.physicalTenantId}: ${tenant.partitionsCount} partition(s), replication ${tenant.replicationFactor}`
);
}
}
Get the upgrade-readiness status of the whole cluster
Reports one overall upgrade-readiness status for the whole cluster, folded over every physical tenant and condition. MIGRATED only once every known condition has migrated for every known physical tenant; MIGRATION_IN_PROGRESS when at least one is confirmed not yet migrated; UNKNOWN otherwise (including before anything has been reported yet). No per-tenant or per-condition detail is reported here; see the upgradeReadiness actuator endpoint for that.
*
Optionaloptions: OperationOptionsRead-only snapshot of current hydrated configuration (do not mutate directly). Use configure(...) to apply changes.
Get decision definition
Returns a decision definition by key. *
Optionaloptions: OperationOptionsasync function getDecisionDefinitionExample(decisionDefinitionKey: DecisionDefinitionKey) {
const camunda = createCamundaClient();
const definition = await camunda.getDecisionDefinition(
{ decisionDefinitionKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Decision: ${definition.decisionDefinitionId}`);
console.log(`Version: ${definition.version}`);
}
Get decision definition XML
Returns decision definition as XML. *
Optionaloptions: OperationOptionsasync function getDecisionDefinitionXmlExample(decisionDefinitionKey: DecisionDefinitionKey) {
const camunda = createCamundaClient();
const xml = await camunda.getDecisionDefinitionXml(
{ decisionDefinitionKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`XML length: ${JSON.stringify(xml).length}`);
}
Get decision instance
Returns a decision instance. *
Optionaloptions: OperationOptionsasync function getDecisionInstanceExample(
decisionEvaluationInstanceKey: DecisionEvaluationInstanceKey
) {
const camunda = createCamundaClient();
const instance = await camunda.getDecisionInstance(
{ decisionEvaluationInstanceKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Decision: ${instance.decisionDefinitionId}`);
}
Get decision requirements
Returns Decision Requirements as JSON. *
Optionaloptions: OperationOptionsasync function getDecisionRequirementsExample(decisionRequirementsKey: DecisionRequirementsKey) {
const camunda = createCamundaClient();
const requirements = await camunda.getDecisionRequirements(
{ decisionRequirementsKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Requirements: ${requirements.decisionRequirementsId}`);
}
Get decision requirements XML
Returns decision requirements as XML. *
Optionaloptions: OperationOptionsasync function getDecisionRequirementsXmlExample(decisionRequirementsKey: DecisionRequirementsKey) {
const camunda = createCamundaClient();
const xml = await camunda.getDecisionRequirementsXml(
{ decisionRequirementsKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`XML length: ${JSON.stringify(xml).length}`);
}
Download document
Download a document from the Camunda 8 cluster.
Note that this is currently supported for document stores of type: AWS, Azure, GCP, in-memory (non-production), local (non-production)
Optionaloptions: OperationOptionsGet element instance
Returns element instance as JSON. *
Optionaloptions: OperationOptionsasync function getElementInstanceExample(elementInstanceKey: ElementInstanceKey) {
const camunda = createCamundaClient();
const element = await camunda.getElementInstance(
{ elementInstanceKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Element: ${element.elementId} (${element.type})`);
}
Internal accessor (read-only) for eventual consistency error mode.
Get exporting status
Returns the exporting status of the physical tenant, aggregated over every replica of every one of its partitions.
Because pause and resume are applied to all replicas, the status is only a single phase
if every replica reports that phase; otherwise it is MIXED, which means a pause or
resume is still in flight or was only partially applied. Backup tooling should treat
only PAUSED and SOFT_PAUSED as confirmation that exporting is paused.
Optionaloptions: OperationOptionsasync function getExportingStatusExample() {
const camunda = createCamundaClient();
// Reports the aggregated exporting status of the physical tenant — useful to
// confirm exporting has actually paused before taking a backup, and that it
// has resumed afterwards.
const { status } = await camunda.getExportingStatus();
console.log(`Exporting status: ${status}`);
}
Get form by key
Get a form by its unique form key.
Optionaloptions: OperationOptionsGet a global-scoped cluster variable
Get a global-scoped cluster variable. *
Optionaloptions: OperationOptionsasync function getGlobalClusterVariableExample(name: ClusterVariableName) {
const camunda = createCamundaClient();
const variable = await camunda.getGlobalClusterVariable(
{ name },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`${variable.name} = ${variable.value}`);
}
Global job statistics
Returns global aggregated counts for jobs. Filter by the creation time window (required) and optionally by jobType.
Optionaloptions: OperationOptionsasync function getGlobalJobStatisticsExample() {
const camunda = createCamundaClient();
const result = await camunda.getGlobalJobStatistics(
{
from: '2025-01-01T00:00:00Z',
to: '2025-12-31T23:59:59Z',
},
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Statistics retrieved: ${JSON.stringify(result)}`);
}
Get global user task listener
Get a global user task listener by its id. *
Optionaloptions: OperationOptionsasync function getGlobalTaskListenerExample(id: GlobalListenerId) {
const camunda = createCamundaClient();
const listener = await camunda.getGlobalTaskListener(
{ id },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Listener: ${listener.type} (${listener.eventTypes})`);
}
Get group
Get a group by its ID. *
Optionaloptions: OperationOptionsGet history backup
Returns detailed status of the history backup with the given id.
Only available on clusters whose secondary storage is Elasticsearch or OpenSearch.
Optionaloptions: OperationOptionsasync function getHistoryBackupExample() {
const camunda = createCamundaClient();
const backup = await camunda.getHistoryBackup({ backupId: 100 });
// The aggregated state is derived from the state of every expected snapshot.
console.log(`History backup ${backup.backupId}: ${backup.state}`);
}
Get a history backup across physical tenants
Reports what every physical tenant of the cluster, or the one named by physicalTenantId, holds for the given backup id. There is no aggregated cluster-level state: a tenant that was reached and does not hold this backup reports NOT_FOUND, which is a successful observation rather than a failure.
The request is all-or-nothing: a physical tenant whose state cannot be read fails the whole request. Narrow the request with physicalTenantId to read the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Only available on clusters whose secondary storage is Elasticsearch or OpenSearch. Use GET /v2/backups/history/{backupId} to act as a single physical tenant.
*
Optionaloptions: OperationOptionsasync function getHistoryBackupAsClusterAdminExample() {
const camunda = createCamundaClient();
// Looking a backup id up directly lists every targeted physical tenant,
// including the ones reporting `NOT_FOUND` — a backup that only some tenants
// hold is a supported outcome.
const backup = await camunda.getHistoryBackupAsClusterAdmin({ backupId: 100 });
console.log(`Cluster history backup ${backup.backupId}:`);
for (const tenant of backup.physicalTenants) {
console.log(` [${tenant.physicalTenantId}] ${tenant.state}`);
}
}
Get incident
Returns incident as JSON.
Optionaloptions: OperationOptionsasync function getIncidentExample(incidentKey: IncidentKey) {
const camunda = createCamundaClient();
const incident = await camunda.getIncident(
{ incidentKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Type: ${incident.errorType}`);
console.log(`State: ${incident.state}`);
console.log(`Message: ${incident.errorMessage}`);
}
Get error metrics for a job type
Returns aggregated metrics per error for the given jobType.
Optionaloptions: OperationOptionsasync function getJobErrorStatisticsExample() {
const camunda = createCamundaClient();
const result = await camunda.getJobErrorStatistics(
{
filter: {
from: '2025-01-01T00:00:00Z',
to: '2025-12-31T23:59:59Z',
jobType: 'payment-processing',
},
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const stat of result.items ?? []) {
console.log(`Error: ${stat.errorMessage}, workers: ${stat.workers}`);
}
}
Get time-series metrics for a job type
Returns a list of time-bucketed metrics ordered ascending by time.
The from and to fields select the time window of interest.
Each item in the response corresponds to one time bucket of the requested resolution.
Optionaloptions: OperationOptionsasync function getJobTimeSeriesStatisticsExample() {
const camunda = createCamundaClient();
const result = await camunda.getJobTimeSeriesStatistics(
{
filter: {
from: '2025-01-01T00:00:00Z',
to: '2025-12-31T23:59:59Z',
jobType: 'payment-processing',
},
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const point of result.items ?? []) {
console.log(`Time: ${point.time}, created: ${point.created.count}`);
}
}
Get job statistics by type
Get statistics about jobs, grouped by job type.
Optionaloptions: OperationOptionsasync function getJobTypeStatisticsExample() {
const camunda = createCamundaClient();
const result = await camunda.getJobTypeStatistics({}, { consistency: { waitUpToMs: 5000 } });
for (const stat of result.items ?? []) {
console.log(`Type: ${stat.jobType}, workers: ${stat.workers}`);
}
}
Get job statistics by worker
Get statistics about jobs, grouped by worker, for a given job type.
Optionaloptions: OperationOptionsasync function getJobWorkerStatisticsExample() {
const camunda = createCamundaClient();
const result = await camunda.getJobWorkerStatistics(
{
filter: {
from: '2025-01-01T00:00:00Z',
to: '2025-12-31T23:59:59Z',
jobType: 'payment-processing',
},
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const stat of result.items ?? []) {
console.log(`Worker: ${stat.worker}, completed: ${stat.completed.count}`);
}
}
Get license status
Obtains the status of the current Camunda license. *
Optionaloptions: OperationOptionsGet a mapping rule
Gets the mapping rule with the given ID.
Optionaloptions: OperationOptionsasync function getMappingRuleExample(mappingRuleId: MappingRuleId) {
const camunda = createCamundaClient();
const rule = await camunda.getMappingRule(
{ mappingRuleId },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Rule: ${rule.name} (${rule.claimName}=${rule.claimValue})`);
}
Get process definition
Returns process definition as JSON. *
Optionaloptions: OperationOptionsasync function getProcessDefinitionExample(processDefinitionKey: ProcessDefinitionKey) {
const camunda = createCamundaClient();
const definition = await camunda.getProcessDefinition(
{ processDefinitionKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Process: ${definition.processDefinitionId} v${definition.version}`);
}
Get process instance statistics
Get statistics about process instances, grouped by process definition and tenant.
Optionaloptions: OperationOptionsasync function getProcessDefinitionInstanceStatisticsExample() {
const camunda = createCamundaClient();
const result = await camunda.getProcessDefinitionInstanceStatistics(
{},
{ consistency: { waitUpToMs: 5000 } }
);
for (const stat of result.items ?? []) {
console.log(
`Definition ${stat.processDefinitionId}: ${stat.activeInstancesWithoutIncidentCount} active`
);
}
}
Get process instance statistics by version
Get statistics about process instances, grouped by version for a given process definition. The process definition ID must be provided as a required field in the request body filter.
Optionaloptions: OperationOptionsasync function getProcessDefinitionInstanceVersionStatisticsExample(
processDefinitionId: ProcessDefinitionId
) {
const camunda = createCamundaClient();
const result = await camunda.getProcessDefinitionInstanceVersionStatistics(
{
filter: {
processDefinitionId,
},
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const stat of result.items ?? []) {
console.log(
`Version ${stat.processDefinitionVersion}: ${stat.activeInstancesWithoutIncidentCount} active`
);
}
}
Get message subscription statistics
Get message subscription statistics, grouped by process definition.
Optionaloptions: OperationOptionsasync function getProcessDefinitionMessageSubscriptionStatisticsExample() {
const camunda = createCamundaClient();
const result = await camunda.getProcessDefinitionMessageSubscriptionStatistics(
{},
{ consistency: { waitUpToMs: 5000 } }
);
for (const stat of result.items ?? []) {
console.log(
`Definition ${stat.processDefinitionId}: ${stat.activeSubscriptions} subscriptions`
);
}
}
Get process definition statistics
Get statistics about elements in currently running process instances by process definition key and search filter. *
Optionaloptions: OperationOptionsasync function getProcessDefinitionStatisticsExample(processDefinitionKey: ProcessDefinitionKey) {
const camunda = createCamundaClient();
const result = await camunda.getProcessDefinitionStatistics(
{ processDefinitionKey },
{ consistency: { waitUpToMs: 5000 } }
);
for (const stat of result.items ?? []) {
console.log(`Element ${stat.elementId}: active=${stat.active}`);
}
}
Get process definition XML
Returns process definition as XML. *
Optionaloptions: OperationOptionsasync function getProcessDefinitionXmlExample(processDefinitionKey: ProcessDefinitionKey) {
const camunda = createCamundaClient();
const xml = await camunda.getProcessDefinitionXml(
{ processDefinitionKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`XML length: ${JSON.stringify(xml).length}`);
}
Get process instance
Get the process instance by the process instance key. *
Optionaloptions: OperationOptionsasync function getProcessInstanceExample(processInstanceKey: ProcessInstanceKey) {
const camunda = createCamundaClient();
const instance = await camunda.getProcessInstance(
{ processInstanceKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`State: ${instance.state}`);
console.log(`Process: ${instance.processDefinitionId}`);
}
Get call hierarchy
Returns the call hierarchy for a given process instance, showing its ancestry up to the root instance. *
Optionaloptions: OperationOptionsasync function getProcessInstanceCallHierarchyExample(processInstanceKey: ProcessInstanceKey) {
const camunda = createCamundaClient();
const result = await camunda.getProcessInstanceCallHierarchy(
{ processInstanceKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Call hierarchy entries: ${result.length}`);
}
Get sequence flows
Get sequence flows taken by the process instance. *
Optionaloptions: OperationOptionsasync function getProcessInstanceSequenceFlowsExample(processInstanceKey: ProcessInstanceKey) {
const camunda = createCamundaClient();
const result = await camunda.getProcessInstanceSequenceFlows(
{ processInstanceKey },
{ consistency: { waitUpToMs: 5000 } }
);
for (const flow of result.items ?? []) {
console.log(`Sequence flow: ${flow.sequenceFlowId}`);
}
}
Get element instance statistics
Get statistics about elements by the process instance key. *
Optionaloptions: OperationOptionsasync function getProcessInstanceStatisticsExample(processInstanceKey: ProcessInstanceKey) {
const camunda = createCamundaClient();
const result = await camunda.getProcessInstanceStatistics(
{ processInstanceKey },
{ consistency: { waitUpToMs: 5000 } }
);
for (const stat of result.items ?? []) {
console.log(`Element ${stat.elementId}: active=${stat.active}`);
}
}
Get process instance statistics by definition
Returns statistics for active process instances with incidents, grouped by process definition. The result set is scoped to a specific incident error hash code, which must be provided as a filter in the request body.
Optionaloptions: OperationOptionsasync function getProcessInstanceStatisticsByDefinitionExample() {
const camunda = createCamundaClient();
const result = await camunda.getProcessInstanceStatisticsByDefinition(
{
filter: {
errorHashCode: 12345,
},
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const stat of result.items ?? []) {
console.log(
`Definition ${stat.processDefinitionId}: ${stat.activeInstancesWithErrorCount} incidents`
);
}
}
Get process instance statistics by error
Returns statistics for active process instances that currently have active incidents, grouped by incident error hash code.
Optionaloptions: OperationOptionsasync function getProcessInstanceStatisticsByErrorExample() {
const camunda = createCamundaClient();
const result = await camunda.getProcessInstanceStatisticsByError(
{},
{ consistency: { waitUpToMs: 5000 } }
);
for (const stat of result.items ?? []) {
console.log(`Error: ${stat.errorMessage}, count: ${stat.activeInstancesWithErrorCount}`);
}
}
Get wait state statistics
Get statistics about waiting element instances by the process instance key, grouped by element id. *
Optionaloptions: OperationOptionsasync function getProcessInstanceWaitStateStatisticsExample(
processInstanceKey: ProcessInstanceKey
) {
const camunda = createCamundaClient();
const result = await camunda.getProcessInstanceWaitStateStatistics(
{ processInstanceKey },
{ consistency: { waitUpToMs: 5000 } }
);
for (const stat of result.items ?? []) {
console.log(`Element ${stat.elementId}: waiting=${stat.waitingCount}`);
}
}
Get resource
Returns a deployed resource. :::info This endpoint does not return BPMN process definitions, DMN decision definitions, or form resources. To query BPMN process definitions or DMN decision definitions, use their respective APIs. :::
Optionaloptions: OperationOptionsasync function getResourceExample(resourceKey: ProcessDefinitionKey) {
const camunda = createCamundaClient();
const resource = await camunda.getResource(
{
resourceKey,
},
{ consistency: { waitUpToMs: 0 } }
);
console.log(`Resource: ${resource.resourceName} (${resource.resourceId})`);
}
Get RPA resource content (deprecated)
Deprecated — use /resources/{resourceKey}/content/binary instead, which supports all
resource types and returns content as binary (octet-stream).
Returns the content of a deployed RPA resource as JSON.
:::info
This endpoint only supports RPA resources. For generic resource content in binary format,
use the /resources/{resourceKey}/content/binary endpoint.
:::
Optionaloptions: OperationOptionsasync function getResourceContentExample(resourceKey: ProcessDefinitionKey) {
const camunda = createCamundaClient();
const content = await camunda.getResourceContent(
{
resourceKey,
},
{ consistency: { waitUpToMs: 0 } }
);
console.log(`Content retrieved (type: ${typeof content})`);
}
Get resource content as binary
Returns the content of a deployed resource in binary format (octet-stream). :::info This endpoint does not return BPMN process definitions, DMN decision definitions, or form resources. To query BPMN process definitions or DMN decision definitions, use their respective APIs. :::
Optionaloptions: OperationOptionsasync function getResourceContentBinaryExample(resourceKey: ProcessDefinitionKey) {
const camunda = createCamundaClient();
const content = await camunda.getResourceContentBinary(
{
resourceKey,
},
{ consistency: { waitUpToMs: 0 } }
);
console.log(`Binary content retrieved (type: ${typeof content})`);
}
Get the status of the restore that is currently in progress
Returns the status of the restore that is currently in progress, reported per broker and per partition. There is at most one restore in flight at any time. Once the restore has finished this endpoint returns 404; the per-partition detail is not retained after completion. *
Optionaloptions: OperationOptionsasync function getRestoreStatusExample() {
const camunda = createCamundaClient();
const status = await camunda.getRestoreStatus();
console.log(`Restore status: ${status.status} (change ${status.changeId})`);
for (const broker of status.brokers) {
console.log(
` Broker ${broker.brokerId}: ${broker.partitionsRestored}/${broker.partitionsToRestore} partitions restored`
);
}
}
Get role
Get a role by its ID. *
Optionaloptions: OperationOptionsGet runtime backup
Returns detailed status of the runtime backup with the given id. *
Optionaloptions: OperationOptionsasync function getRuntimeBackupExample() {
const camunda = createCamundaClient();
const backup = await camunda.getRuntimeBackup({ backupId: 100 });
console.log(`Backup ${backup.backupId}: ${backup.state}`);
for (const partition of backup.details) {
console.log(` Partition ${partition.partitionId}: ${partition.state}`);
}
}
Get a runtime backup across physical tenants
Reports what every physical tenant of the cluster, or the one named by physicalTenantId, holds for the given backup id, plus the state aggregated over all of them. A tenant that was reached and does not hold this backup reports DOES_NOT_EXIST, which is a successful observation rather than a failure — so a backup only some tenants hold aggregates to INCOMPLETE, the same way a backup only some partitions hold does within one tenant.
The request is all-or-nothing: a physical tenant whose state cannot be read fails the whole request. Narrow the request with physicalTenantId to read the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use GET /v2/backups/runtime/{backupId} to act as a single physical tenant.
*
Optionaloptions: OperationOptionsasync function getRuntimeBackupAsClusterAdminExample() {
const camunda = createCamundaClient();
// Looking a backup id up directly lists every targeted physical tenant,
// including the ones reporting `DOES_NOT_EXIST` — a backup that only some
// tenants hold is a supported outcome.
const backup = await camunda.getRuntimeBackupAsClusterAdmin({ backupId: 100 });
console.log(`Cluster runtime backup ${backup.backupId}: ${backup.state}`);
for (const tenant of backup.physicalTenants) {
console.log(` [${tenant.physicalTenantId}] ${tenant.state}`);
}
}
Get runtime backup state
Returns the current checkpoint and backup state of every partition of the physical
tenant. Unlike the backupRuntime actuator, this fails the whole request if the
checkpoint state or the backup ranges cannot be retrieved from any partition, instead
of silently returning an empty section.
Optionaloptions: OperationOptionsasync function getRuntimeBackupStateExample() {
const camunda = createCamundaClient();
const state = await camunda.getRuntimeBackupState();
for (const checkpoint of state.checkpointStates) {
console.log(
`Partition ${checkpoint.partitionId} checkpoint ${checkpoint.checkpointId} (${checkpoint.checkpointType})`
);
}
for (const range of state.ranges) {
console.log(
`Partition ${range.partitionId} range: ${range.start?.checkpointId} -> ${range.end?.checkpointId}`
);
}
}
Get runtime backup state across physical tenants
Reports the checkpoint and backup state of every partition of every physical tenant of the cluster, or of the one named by physicalTenantId, grouped by physical tenant. Checkpoint ids and log positions only mean anything within one physical tenant's partitions, so nothing is aggregated across tenants.
The request is all-or-nothing: a physical tenant whose state cannot be read fails the whole request rather than contributing an empty section, which an operator making a delete or restore decision could not tell apart from "nothing to report yet". Narrow the request with physicalTenantId to read the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use GET /v2/backups/runtime/state to act as a single physical tenant.
*
Optionaloptions: OperationOptionsasync function getRuntimeBackupStateAsClusterAdminExample() {
const camunda = createCamundaClient();
// Returns the checkpoint and backup state of every targeted physical tenant.
// Nothing is aggregated across tenants — checkpoint ids and log positions only
// mean anything within one tenant's partitions.
const clusterState = await camunda.getRuntimeBackupStateAsClusterAdmin({});
for (const tenant of clusterState.physicalTenants) {
console.log(`[${tenant.physicalTenantId}] ${tenant.state.checkpointStates.length} checkpoints`);
}
}
Get process start form
Get the start form of a process. Note that this endpoint will only return linked forms. This endpoint does not support embedded forms.
Optionaloptions: OperationOptionsasync function getStartProcessFormExample(processDefinitionKey: ProcessDefinitionKey) {
const camunda = createCamundaClient();
const form = await camunda.getStartProcessForm(
{ processDefinitionKey },
{ consistency: { waitUpToMs: 5000 } }
);
if (form) {
console.log(`Form key: ${form.formKey}`);
}
}
Get physical tenant status
Checks the health status of the default physical tenant by verifying if there's at least one partition of its group with a healthy leader. This endpoint is scoped to the default physical tenant only: it is available unprefixed and at /physical-tenants/default/v2/status, but not for any other physical tenant id (/physical-tenants/{id}/v2/status returns 404 for every other id, whether or not a physical tenant with that id exists). On a cluster with only the default physical tenant this endpoint answers the same question as /cluster/v2/status, though not with the same response: /cluster/v2/status reports its status in a body and so also distinguishes a degraded tenant from a healthy one. Use /cluster/v2/status for the aggregated status of the whole cluster, or /physical-tenants/{id}/v2/topology for the health of a specific physical tenant's partitions.
*
Optionaloptions: OperationOptionsSystem configuration (alpha)
Returns the current system configuration. The response is an envelope that groups settings by feature area.
This endpoint is an alpha feature and may be subject to change in future releases.
Optionaloptions: OperationOptionsGet tenant
Retrieves a single tenant by tenant ID. *
Optionaloptions: OperationOptionsGet a tenant-scoped cluster variable
Get a tenant-scoped cluster variable. *
Optionaloptions: OperationOptionsasync function getTenantClusterVariableExample(tenantId: TenantId, name: ClusterVariableName) {
const camunda = createCamundaClient();
const variable = await camunda.getTenantClusterVariable(
{
tenantId,
name,
},
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`${variable.name} = ${variable.value}`);
}
Get cluster topology
Obtains the current topology of the cluster the gateway is part of. *
Optionaloptions: OperationOptionsasync function getTopologyExample() {
const camunda = createCamundaClient();
const topology = await camunda.getTopology();
console.log(`Cluster size: ${topology.clusterSize}`);
console.log(`Partitions: ${topology.partitionsCount}`);
for (const broker of topology.brokers ?? []) {
console.log(` Broker ${broker.nodeId}: ${broker.host}:${broker.port}`);
}
}
Get usage metrics
Retrieve the usage metrics based on given criteria. *
Optionaloptions: OperationOptionsasync function getUsageMetricsExample() {
const camunda = createCamundaClient();
const metrics = await camunda.getUsageMetrics(
{
startTime: '2025-01-01T00:00:00Z',
endTime: '2025-12-31T23:59:59Z',
},
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Usage metrics retrieved: ${JSON.stringify(metrics)}`);
}
Get user
Get a user by its username. *
Optionaloptions: OperationOptionsGet user task
Get the user task by the user task key. *
Optionaloptions: OperationOptionsGet user task form
Get the form of a user task. Note that this endpoint will only return linked forms. This endpoint does not support embedded forms.
Optionaloptions: OperationOptionsGet variable
Get a variable by its key.
This endpoint returns both process-level and local (element-scoped) variables. The variable's scopeKey indicates whether it's a process-level variable or scoped to a specific element instance. *
Optionaloptions: OperationOptionsReturn a read-only snapshot of currently registered job workers.
List history backups
Returns a list of all available history backups of the physical tenant, with their state and additional info, most recent first by snapshot start time.
Only available on clusters whose secondary storage is Elasticsearch or OpenSearch.
Optionaloptions: OperationOptionsasync function listHistoryBackupsExample() {
const camunda = createCamundaClient();
// `prefix` must end in a single '*'. Omit it to list every history backup.
const backups = await camunda.listHistoryBackups({ prefix: '10*' });
for (const backup of backups) {
console.log(`History backup ${backup.backupId}: ${backup.state}`);
}
}
List history backups across physical tenants
Lists the history backups of every physical tenant of the cluster, or of the one named by physicalTenantId, grouped by backup id. A backup id that only some physical tenants hold is a supported outcome rather than a degraded one, so only the tenants that hold it are listed under it.
The request is all-or-nothing: a physical tenant whose backups cannot be read fails the whole request rather than silently dropping out of the listing. Narrow the request with physicalTenantId to list the backups of the tenants that can still be read.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Only available on clusters whose secondary storage is Elasticsearch or OpenSearch. Use GET /v2/backups/history to act as a single physical tenant.
*
Optionaloptions: OperationOptionsasync function listHistoryBackupsAsClusterAdminExample() {
const camunda = createCamundaClient();
// `prefix` must end in a single '*'. Omit `physicalTenantId` to span every
// physical tenant of the cluster — results are grouped by backup id, and each
// group lists only the tenants that hold that id.
const backups = await camunda.listHistoryBackupsAsClusterAdmin({ prefix: '10*' });
for (const backup of backups) {
console.log(`Cluster history backup ${backup.backupId}:`);
for (const tenant of backup.physicalTenants) {
console.log(` [${tenant.physicalTenantId}] ${tenant.state}`);
}
}
}
List runtime backups
Returns a list of all available runtime backups of the physical tenant, with their state and additional info, sorted in descending order of backupId.
Optionaloptions: OperationOptionsasync function listRuntimeBackupsExample() {
const camunda = createCamundaClient();
// `prefix` must end in a single '*'. Omit it to list every backup.
const backups = await camunda.listRuntimeBackups({ prefix: '10*' });
for (const backup of backups) {
console.log(`Backup ${backup.backupId}: ${backup.state}`);
}
}
List runtime backups across physical tenants
Lists the runtime backups of every physical tenant of the cluster, or of the one named by physicalTenantId, grouped by backup id. Every group reports every targeted tenant, including the ones holding nothing for that id, so a backup only some tenants hold aggregates to INCOMPLETE here exactly as it does when looked up directly — the state of a listed group can be trusted to say whether the cluster can be restored from it. A backup id that only some physical tenants hold is a supported outcome rather than a degraded one; tenants that generate their own backup ids never share one, so in that mode each backup forms its own group and the other tenants report DOES_NOT_EXIST under it.
The request is all-or-nothing: a physical tenant whose backups cannot be read fails the whole request rather than silently dropping out of the listing. Narrow the request with physicalTenantId to list the backups of the tenants that can still be read.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use GET /v2/backups/runtime to act as a single physical tenant.
*
Optionaloptions: OperationOptionsasync function listRuntimeBackupsAsClusterAdminExample() {
const camunda = createCamundaClient();
// `prefix` must end in a single '*'. Omit `physicalTenantId` to span every
// physical tenant — results are grouped by backup id, and each group reports
// every targeted tenant, including ones holding nothing for that id (reported
// as `DOES_NOT_EXIST`).
const backups = await camunda.listRuntimeBackupsAsClusterAdmin({ prefix: '10*' });
for (const backup of backups) {
console.log(`Cluster runtime backup ${backup.backupId}: ${backup.state}`);
for (const tenant of backup.physicalTenants) {
console.log(` [${tenant.physicalTenantId}] ${tenant.state}`);
}
}
}
List secrets
List the camunda.secrets.* references known for the caller's physical tenant.
Only references the caller holds SECRET:READ on are returned. This endpoint never
returns secret values, only the reference names.
The references are read from the secret stores configured for the caller's physical tenant.
A store may hold names outside the reference name charset (for example one containing a
dot); those are omitted, since /secrets/resolve would reject them and no permission can
be granted on them.
A returned reference is usable verbatim with /secrets/resolve. In a FEEL expression,
however, a name that is not a bare identifier has to be backtick-escaped, since FEEL reads
a bare dash as the minus operator: a listed camunda.secrets.db-password is written
=camunda.secrets.`db-password` in a BPMN input mapping.
Optionaloptions: OperationOptionsasync function listSecretsExample() {
const camunda = createCamundaClient();
// The request body is reserved for future filtering options and currently
// takes no properties.
const result = await camunda.listSecrets({});
// Only the references are returned — never the secret values. Use
// `resolveSecrets` to fetch a value when one is actually needed.
for (const reference of result.references) {
console.log(`Secret available: ${reference}`);
}
}
Access a scoped logger (internal & future user emission).
Optionalscope: stringMigrate process instance
Migrates a process instance to a new process definition. This request can contain multiple mapping instructions to define mapping between the active process instance's elements and target process definition elements.
Use this to upgrade a process instance to a new version of a process or to a different process definition, e.g. to keep your running instances up-to-date with the latest process improvements.
Optionaloptions: OperationOptionsasync function migrateProcessInstanceExample(
processInstanceKey: ProcessInstanceKey,
targetProcessDefinitionKey: ProcessDefinitionKey,
sourceElementId: ElementId,
targetElementId: ElementId
) {
const camunda = createCamundaClient();
await camunda.migrateProcessInstance({
processInstanceKey,
targetProcessDefinitionKey,
mappingInstructions: [
{
sourceElementId,
targetElementId,
},
],
});
}
Migrate process instances (batch)
Migrate multiple process instances. Since only process instances with ACTIVE state can be migrated, any given filters for state are ignored and overridden during this batch operation. This is done asynchronously, the progress can be tracked using the batchOperationKey from the response and the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Optionaloptions: OperationOptionsasync function migrateProcessInstancesBatchOperationExample(
processDefinitionKey: ProcessDefinitionKey,
targetProcessDefinitionKey: ProcessDefinitionKey,
sourceElementId: ElementId,
targetElementId: ElementId
) {
const camunda = createCamundaClient();
const result = await camunda.migrateProcessInstancesBatchOperation({
filter: {
processDefinitionKey,
},
migrationPlan: {
targetProcessDefinitionKey,
mappingInstructions: [
{
sourceElementId,
targetElementId,
},
],
},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Modify process instance
Modifies a running process instance. This request can contain multiple instructions to activate an element of the process or to terminate an active instance of an element.
Use this to repair a process instance that is stuck on an element or took an unintended path. For example, because an external system is not available or doesn't respond as expected.
Optionaloptions: OperationOptionsasync function modifyProcessInstanceExample(
processInstanceKey: ProcessInstanceKey,
elementId: ElementId,
elementInstanceKey: ElementInstanceKey
) {
const camunda = createCamundaClient();
await camunda.modifyProcessInstance({
processInstanceKey,
activateInstructions: [{ elementId }],
terminateInstructions: [{ elementInstanceKey }],
});
}
Modify process instances (batch)
Modify multiple process instances. Since only process instances with ACTIVE state can be modified, any given filters for state are ignored and overridden during this batch operation. In contrast to single modification operation, it is not possible to add variable instructions or modify by element key. It is only possible to use the element id of the source and target. This is done asynchronously, the progress can be tracked using the batchOperationKey from the response and the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Optionaloptions: OperationOptionsasync function modifyProcessInstancesBatchOperationExample(
processDefinitionKey: ProcessDefinitionKey,
sourceElementId: ElementId,
targetElementId: ElementId
) {
const camunda = createCamundaClient();
const result = await camunda.modifyProcessInstancesBatchOperation({
filter: {
processDefinitionKey,
},
moveInstructions: [
{
sourceElementId,
targetElementId,
},
],
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Pause exporting across the whole cluster
Pauses exporting on every physical tenant of the cluster in one call. With soft=true, every physical tenant is soft-paused instead.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here.
*
Optionaloptions: OperationOptionsasync function pauseClusterExportingExample() {
const camunda = createCamundaClient();
// Cluster-admin variant: pauses exporting on every physical tenant of the
// cluster. With `soft: true` exporting keeps running but its position is not
// committed, so the log is still not compacted.
await camunda.pauseClusterExporting({ soft: true });
}
Pause exporting
Pauses exporting on all partitions of the physical tenant. While paused, exported records are not committed, so the log is not compacted for the affected partitions.
With soft=true, exporting continues to run but its position is not committed, so the
state after resuming is identical to a hard pause; use this variant when exporting must
keep progressing (e.g. to avoid falling behind) while still preventing log compaction,
such as during a backup.
Optionaloptions: OperationOptionsasync function pauseExportingExample() {
const camunda = createCamundaClient();
// With `soft: true` exporting keeps running but its position is not committed,
// so the log is still not compacted — use it when exporting must keep
// progressing, for example while a backup is taken.
await camunda.pauseExporting({ soft: true });
}
Pin internal clock (alpha)
Set a precise, static time for the Zeebe engine's internal clock. When the clock is pinned, it remains at the specified time and does not advance. To change the time, the clock must be pinned again with a new timestamp.
This endpoint is an alpha feature and may be subject to change in future releases.
Optionaloptions: OperationOptionsPublish message
Publishes a single message. Messages are published to specific partitions computed from their correlation keys. Messages can be buffered. The endpoint does not wait for a correlation result. Use the message correlation endpoint for such use cases.
Optionaloptions: OperationOptionsReset internal clock (alpha)
Resets the Zeebe engine's internal clock to the current system time, enabling it to tick in real-time. This operation is useful for returning the clock to normal behavior after it has been pinned to a specific time.
This endpoint is an alpha feature and may be subject to change in future releases.
Optionaloptions: OperationOptionsResolve incident
Marks the incident as resolved; most likely a call to Update job will be necessary to reset the job's retries, followed by this call.
Optionaloptions: OperationOptionsResolve related incidents (batch)
Resolves multiple instances of process instances. Since only process instances with ACTIVE state can have unresolved incidents, any given filters for state are ignored and overridden during this batch operation. This is done asynchronously, the progress can be tracked using the batchOperationKey from the response and the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Optionaloptions: OperationOptionsasync function resolveIncidentsBatchOperationExample(processDefinitionKey: ProcessDefinitionKey) {
const camunda = createCamundaClient();
const result = await camunda.resolveIncidentsBatchOperation({
filter: {
processDefinitionKey,
},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Resolve related incidents
Creates a batch operation to resolve multiple incidents of a process instance. *
Optionaloptions: OperationOptionsasync function resolveProcessInstanceIncidentsExample(processInstanceKey: ProcessInstanceKey) {
const camunda = createCamundaClient();
const result = await camunda.resolveProcessInstanceIncidents({ processInstanceKey });
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Resolve secrets
Resolve a deduplicated batch of camunda.secrets.* references for the caller's
physical tenant in a single round-trip.
Each reference is authorized and resolved independently. For valid requests, the endpoint
always responds with HTTP 200: successfully resolved references are returned in resolved,
while references that could not be resolved (for example not found, malformed or over-long,
or the caller lacks SECRET:REVEAL on that reference) are returned in errors. A failure of
one reference never fails the others. Only structurally invalid requests are rejected with
HTTP 400: a missing or non-array references field, more than 20 references, or a null entry.
References are resolved against the secret stores configured for the caller's physical tenant, served from the gateway's secret cache when the value is already cached and read from the store otherwise.
Optionaloptions: OperationOptionsasync function resolveSecretsExample() {
const camunda = createCamundaClient();
const result = await camunda.resolveSecrets({
references: ['camunda.secrets.myApiToken', 'camunda.secrets.dbPassword'],
});
// Successfully resolved references are returned in `resolved`; references that
// could not be resolved are returned in `errors`, each with a typed error code.
// Never log a resolved value — it holds secret material. Pass it straight to the
// consumer that needs it (HTTP client, DB driver, ...) instead.
for (const resolved of result.resolved) {
console.log(`Resolved ${resolved.reference} (value redacted)`);
useSecret(resolved.value);
}
for (const error of result.errors) {
console.log(`Failed to resolve ${error.reference}: ${error.code} - ${error.message}`);
}
}
// Hands the resolved secret to whatever needs it, without logging it.
function useSecret(_value: string) {}
Restore from a backup
Restores the cluster from a backup. The restore is described either by a single backup ID or by a time range (from/to) that selects the backups to restore. This endpoint is only accessible while the cluster is in recovery mode; requests are rejected otherwise. The request is validated and acknowledged, but the restore itself is performed asynchronously.
*
Optionaloptions: OperationOptionsasync function restoreExample() {
const camunda = createCamundaClient();
// The cluster must be in recovery mode before a restore is accepted. Provide
// either a list of backup IDs (one per partition) or a time range (`from`/`to`)
// that selects the backups to restore, but not both.
const change = await camunda.restore({
backupIds: [100, 101],
});
console.log(`Cluster change ${change.changeId}:`);
for (const group of change.plannedChanges) {
console.log(` ${group.physicalTenantId ?? 'cluster-wide'}:`);
for (const op of group.operations) {
const mode = 'mode' in op ? op.mode : undefined;
console.log(` ${op.operation}${mode ? ` -> ${mode}` : ''}`);
}
}
}
Restore one or every physical tenant from a backup
Restores physical tenants from backups. The restore is described either by a list of backup IDs or by a time range (from/to) that selects the backups to restore. Restores are only accepted while the targeted physical tenants are in recovery mode; requests are rejected otherwise. The request is validated and acknowledged, but the restore itself is performed asynchronously.
If the physicalTenantId parameter is provided, only that physical tenant is restored and overrides must be omitted.
If it is not provided, every physical tenant of the cluster is restored: those named in overrides with their own backup selection, all others with the selection at the top level of the request body.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here.
*
Optionaloptions: OperationOptionsasync function restoreAsClusterAdminExample() {
const camunda = createCamundaClient();
// The cluster-admin variant can target a specific physical tenant and supports
// per-tenant overrides. Omit `physicalTenantId` to restore every physical
// tenant. Provide either backup IDs (one per partition) or a time range
// (`from`/`to`), but not both.
const change = await camunda.restoreAsClusterAdmin({
backupIds: [200, 201],
physicalTenantId: 'default',
dryRun: true,
});
console.log(`Cluster change ${change.changeId}:`);
for (const group of change.plannedChanges) {
console.log(` ${group.physicalTenantId ?? 'cluster-wide'}:`);
for (const op of group.operations) {
const mode = 'mode' in op ? op.mode : undefined;
console.log(` ${op.operation}${mode ? ` -> ${mode}` : ''}`);
}
}
}
Resume Batch operation
Resumes a suspended batch operation. This is done asynchronously, the progress can be tracked using the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Optionaloptions: OperationOptionsResume exporting across the whole cluster
Resumes exporting on every physical tenant of the cluster in one call, after a pause or soft pause.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here.
*
Optionaloptions: OperationOptionsResume exporting
Resumes exporting on all partitions of the physical tenant after a pause or soft pause.
Optionaloptions: OperationOptionsResume process instance
Resumes a suspended process instance, returning it to the ACTIVE state and continuing processing. Only process instances in the SUSPENDED state can be resumed. A child process instance can be resumed independently of its parent or root process instance; resumption does not cascade to or from related instances.
Optionaloptions: OperationOptionsResume process instances (batch)
Resumes multiple suspended process instances. Any given filter for state or parentProcessInstanceKey is ignored and overridden, as only SUSPENDED process instances can be resumed and resumption does not cascade between parent and child instances, so child instances are resumed independently of their parent or root instance. This is done asynchronously, the progress can be tracked using the batchOperationKey from the response and the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Optionaloptions: OperationOptionsasync function resumeProcessInstancesBatchOperationExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const result = await camunda.resumeProcessInstancesBatchOperation({
filter: {
processDefinitionKey,
},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Search agent definitions
Search for agent definitions based on given criteria. *
Optionaloptions: OperationOptionsasync function searchAgentDefinitionsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchAgentDefinitions(
{
filter: { agentType: { $eq: 'AI_AGENT_TASK' } },
sort: [{ field: 'name', order: 'ASC' }],
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const definition of result.items ?? []) {
console.log(`${definition.agentDefinitionKey}: ${definition.name} (${definition.agentType})`);
}
console.log(`Total: ${result.page.totalItems}`);
}
Search agent instance history
Searches the conversation history of an agent instance. Committed items are returned by default.
Optionaloptions: OperationOptionsasync function searchAgentInstanceHistoryExample(agentInstanceKey: AgentInstanceKey) {
const camunda = createCamundaClient();
const result = await camunda.searchAgentInstanceHistory(
{
agentInstanceKey,
filter: { role: { $eq: 'ASSISTANT' } },
sort: [{ field: 'producedAt', order: 'ASC' }],
page: { limit: 20 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const item of result.items ?? []) {
console.log(`${item.historyItemKey} (${item.role})`);
}
console.log(`Total: ${result.page.totalItems}`);
}
Search agent instances
Search for agent instances based on given criteria. *
Optionaloptions: OperationOptionsasync function searchAgentInstancesExample() {
const camunda = createCamundaClient();
const result = await camunda.searchAgentInstances(
{
filter: { status: { $eq: 'IDLE' } },
sort: [{ field: 'creationDate', order: 'DESC' }],
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const instance of result.items ?? []) {
console.log(`${instance.agentInstanceKey}: ${instance.status}`);
}
console.log(`Total: ${result.page.totalItems}`);
}
Search audit logs
Search for audit logs based on given criteria. *
Optionaloptions: OperationOptionsasync function searchAuditLogsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchAuditLogs(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const log of result.items ?? []) {
console.log(`${log.auditLogKey}: ${log.operationType}`);
}
}
Search authorizations
Search for authorizations based on given criteria. *
Optionaloptions: OperationOptionsasync function searchAuthorizationsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchAuthorizations(
{
filter: { ownerType: 'USER' },
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const auth of result.items ?? []) {
console.log(`${auth.authorizationKey}: ${auth.ownerId} - ${auth.resourceType}`);
}
}
Search batch operation items
Search for batch operation items based on given criteria. *
Optionaloptions: OperationOptionsasync function searchBatchOperationItemsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchBatchOperationItems(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const item of result.items ?? []) {
console.log(`Item: ${item.itemKey} (${item.state})`);
}
}
Search batch operations
Search for batch operations based on given criteria. *
Optionaloptions: OperationOptionsasync function searchBatchOperationsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchBatchOperations(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const batch of result.items ?? []) {
console.log(`${batch.batchOperationKey}: ${batch.batchOperationType} (${batch.state})`);
}
}
Search group clients
Search clients assigned to a group. *
Optionaloptions: OperationOptionsasync function searchClientsForGroupExample(groupId: GroupId) {
const camunda = createCamundaClient();
const result = await camunda.searchClientsForGroup(
{ groupId },
{ consistency: { waitUpToMs: 5000 } }
);
for (const client of result.items ?? []) {
console.log(`Client: ${client.clientId}`);
}
}
Search role clients
Search clients with assigned role. *
Optionaloptions: OperationOptionsasync function searchClientsForRoleExample(roleId: RoleId) {
const camunda = createCamundaClient();
const result = await camunda.searchClientsForRole(
{ roleId },
{ consistency: { waitUpToMs: 5000 } }
);
for (const client of result.items ?? []) {
console.log(`Client: ${client.clientId}`);
}
}
Search clients for tenant
Retrieves a filtered and sorted list of clients for a specified tenant. *
Optionaloptions: OperationOptionsasync function searchClientsForTenantExample(tenantId: TenantId) {
const camunda = createCamundaClient();
const result = await camunda.searchClientsForTenant(
{ tenantId },
{ consistency: { waitUpToMs: 5000 } }
);
for (const client of result.items ?? []) {
console.log(`Client: ${client.clientId}`);
}
}
Search for cluster variables based on given criteria. By default, long variable values in the response are truncated. *
Optionaloptions: OperationOptionsasync function searchClusterVariablesExample() {
const camunda = createCamundaClient();
const result = await camunda.searchClusterVariables(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const variable of result.items ?? []) {
console.log(`${variable.name} = ${variable.value}`);
}
}
Search correlated message subscriptions
Search correlated message subscriptions based on given criteria. *
Optionaloptions: OperationOptionsasync function searchCorrelatedMessageSubscriptionsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchCorrelatedMessageSubscriptions(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const sub of result.items ?? []) {
console.log(`Correlated subscription: ${sub.messageName}`);
}
}
Search decision definitions
Search for decision definitions based on given criteria. *
Optionaloptions: OperationOptionsasync function searchDecisionDefinitionsExample(decisionDefinitionId: DecisionDefinitionId) {
const camunda = createCamundaClient();
const result = await camunda.searchDecisionDefinitions(
{
filter: { decisionDefinitionId },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const definition of result.items ?? []) {
console.log(`${definition.decisionDefinitionId} v${definition.version}`);
}
}
Search decision instances
Search for decision instances based on given criteria. *
Optionaloptions: OperationOptionsasync function searchDecisionInstancesExample() {
const camunda = createCamundaClient();
const result = await camunda.searchDecisionInstances(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const instance of result.items ?? []) {
console.log(`${instance.decisionEvaluationKey}: ${instance.decisionDefinitionId}`);
}
}
Search decision requirements
Search for decision requirements based on given criteria. *
Optionaloptions: OperationOptionsasync function searchDecisionRequirementsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchDecisionRequirements(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const req of result.items ?? []) {
console.log(`${req.decisionRequirementsKey}: ${req.decisionRequirementsId}`);
}
}
Search for incidents of a specific element instance
Search for incidents caused by the specified element instance, including incidents of any child instances created from this element instance.
Although the elementInstanceKey is provided as a path parameter to indicate the root element instance,
you may also include an elementInstanceKey within the filter object to narrow results to specific
child element instances. This is useful, for example, if you want to isolate incidents associated with
nested or subordinate elements within the given element instance while excluding incidents directly tied
to the root element itself.
Optionaloptions: OperationOptionsasync function searchElementInstanceIncidentsExample(elementInstanceKey: ElementInstanceKey) {
const camunda = createCamundaClient();
const result = await camunda.searchElementInstanceIncidents(
{ elementInstanceKey },
{ consistency: { waitUpToMs: 5000 } }
);
for (const incident of result.items ?? []) {
console.log(`Incident: ${incident.errorType}`);
}
}
Search element instances
Search for element instances based on given criteria. *
Optionaloptions: OperationOptionsasync function searchElementInstancesExample(processInstanceKey: ProcessInstanceKey) {
const camunda = createCamundaClient();
const result = await camunda.searchElementInstances(
{
filter: {
processInstanceKey,
},
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const element of result.items ?? []) {
console.log(`${element.elementId}: ${element.type} (${element.state})`);
}
}
Search element instance wait states
Returns the wait states for element instances matching the given filter.
Optionaloptions: OperationOptionsasync function searchElementInstanceWaitStatesExample(processInstanceKey: ProcessInstanceKey) {
const camunda = createCamundaClient();
const result = await camunda.searchElementInstanceWaitStates(
{
filter: {
processInstanceKey,
},
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const waitState of result.items ?? []) {
const { details } = waitState;
let description: string;
if (details.waitStateType === 'JOB') {
description = `waiting on job '${details.jobType}'`;
} else if (details.waitStateType === 'MESSAGE') {
description = `waiting for message '${details.messageName}'`;
} else {
description = `waiting (${details.waitStateType})`;
}
console.log(`${waitState.elementId}: ${description}`);
}
}
Search global user task listeners
Search for global user task listeners based on given criteria. *
Optionaloptions: OperationOptionsasync function searchGlobalTaskListenersExample() {
const camunda = createCamundaClient();
const result = await camunda.searchGlobalTaskListeners(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const listener of result.items ?? []) {
console.log(`${listener.id}: ${listener.type} (${listener.eventTypes})`);
}
}
Search groups for tenant
Retrieves a filtered and sorted list of groups for a specified tenant. *
Optionaloptions: OperationOptionsasync function searchGroupIdsForTenantExample(tenantId: TenantId) {
const camunda = createCamundaClient();
const result = await camunda.searchGroupIdsForTenant(
{ tenantId },
{ consistency: { waitUpToMs: 5000 } }
);
for (const group of result.items ?? []) {
console.log(`Group: ${group.groupId}`);
}
}
Search groups
Search for groups based on given criteria. *
Optionaloptions: OperationOptionsasync function searchGroupsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchGroups(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const group of result.items ?? []) {
console.log(`${group.groupId}: ${group.name}`);
}
}
Search role groups
Search groups with assigned role. *
Optionaloptions: OperationOptionsasync function searchGroupsForRoleExample(roleId: RoleId) {
const camunda = createCamundaClient();
const result = await camunda.searchGroupsForRole(
{ roleId },
{ consistency: { waitUpToMs: 5000 } }
);
for (const group of result.items ?? []) {
console.log(`Group: ${group.groupId}`);
}
}
Search incidents
Search for incidents based on given criteria.
Optionaloptions: OperationOptionsasync function searchIncidentsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchIncidents(
{
filter: { state: 'ACTIVE' },
sort: [{ field: 'creationTime', order: 'DESC' }],
page: { limit: 20 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const incident of result.items ?? []) {
console.log(`${incident.incidentKey}: ${incident.errorType} — ${incident.errorMessage}`);
}
console.log(`Total active incidents: ${result.page.totalItems}`);
}
Search jobs
Search for jobs based on given criteria. *
Optionaloptions: OperationOptionsasync function searchJobsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchJobs(
{
filter: { type: 'payment-processing', state: 'CREATED' },
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const job of result.items ?? []) {
console.log(`Job ${job.jobKey}: ${job.type} (${job.state})`);
}
}
Search mapping rules
Search for mapping rules based on given criteria.
Optionaloptions: OperationOptionsasync function searchMappingRulesExample() {
const camunda = createCamundaClient();
const result = await camunda.searchMappingRule(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const rule of result.items ?? []) {
console.log(`${rule.mappingRuleId}: ${rule.name}`);
}
}
Search group mapping rules
Search mapping rules assigned to a group. *
Optionaloptions: OperationOptionsasync function searchMappingRulesForGroupExample(groupId: GroupId) {
const camunda = createCamundaClient();
const result = await camunda.searchMappingRulesForGroup(
{ groupId },
{ consistency: { waitUpToMs: 5000 } }
);
for (const rule of result.items ?? []) {
console.log(`Mapping rule: ${rule.name}`);
}
}
Search role mapping rules
Search mapping rules with assigned role. *
Optionaloptions: OperationOptionsasync function searchMappingRulesForRoleExample(roleId: RoleId) {
const camunda = createCamundaClient();
const result = await camunda.searchMappingRulesForRole(
{ roleId },
{ consistency: { waitUpToMs: 5000 } }
);
for (const rule of result.items ?? []) {
console.log(`Mapping rule: ${rule.name}`);
}
}
Search mapping rules for tenant
Retrieves a filtered and sorted list of MappingRules for a specified tenant. *
Optionaloptions: OperationOptionsasync function searchMappingRulesForTenantExample(tenantId: TenantId) {
const camunda = createCamundaClient();
const result = await camunda.searchMappingRulesForTenant(
{ tenantId },
{ consistency: { waitUpToMs: 5000 } }
);
for (const rule of result.items ?? []) {
console.log(`Mapping rule: ${rule.name}`);
}
}
Search message subscriptions
Search for message subscriptions based on given criteria.
By default, both start and intermediate event subscriptions are returned. Use the
messageSubscriptionType filter to restrict results to a single type.
Version notes:
messageSubscriptionType field is only populated for data created
with Camunda 8.10 or later. For pre-8.10 data, intermediate event entries have no
messageSubscriptionType value stored. For convenience, the API returns PROCESS_EVENT
as a default for such search results, though.messageSubscriptionType not matching START_EVENT.Optionaloptions: OperationOptionsasync function searchMessageSubscriptionsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchMessageSubscriptions(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const sub of result.items ?? []) {
console.log(`Subscription: ${sub.messageName}`);
}
}
Search own authorizations
Search for the current authenticated principal's own authorization records — including authorizations granted directly to the user or client, as well as those granted via a group, role, or mapping rule the principal belongs to. *
Optionaloptions: OperationOptionsasync function searchOwnAuthorizationsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchOwnAuthorizations(
{
filter: { resourceType: 'PROCESS_DEFINITION' },
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const auth of result.items ?? []) {
console.log(`${auth.resourceId}: ${auth.permissionTypes?.join(', ')}`);
}
}
Search process definitions
Search for process definitions based on given criteria. *
Optionaloptions: OperationOptionsasync function searchProcessDefinitionsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchProcessDefinitions(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const def of result.items ?? []) {
console.log(`${def.processDefinitionKey}: ${def.processDefinitionId} v${def.version}`);
}
}
Search process definition variable names
Search for distinct variable names defined on a process definition, optionally narrowed by the name filter. *
Optionaloptions: OperationOptionsasync function searchProcessDefinitionVariableNamesExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const result = await camunda.searchProcessDefinitionVariableNames(
{ processDefinitionKey },
{ consistency: { waitUpToMs: 5000 } }
);
for (const variable of result.items ?? []) {
console.log(`Variable name: ${variable.name}`);
}
}
Search related incidents
Search for incidents caused by the process instance or any of its called process or decision instances.
Although the processInstanceKey is provided as a path parameter to indicate the root process instance,
you may also include a processInstanceKey within the filter object to narrow results to specific
child process instances. This is useful, for example, if you want to isolate incidents associated with
subprocesses or called processes under the root instance while excluding incidents directly tied to the root.
Optionaloptions: OperationOptionsasync function searchProcessInstanceIncidentsExample(processInstanceKey: ProcessInstanceKey) {
const camunda = createCamundaClient();
const result = await camunda.searchProcessInstanceIncidents(
{
processInstanceKey,
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const incident of result.items ?? []) {
console.log(`Incident: ${incident.errorType} - ${incident.errorMessage}`);
}
}
Search process instances
Search for process instances based on given criteria. *
Optionaloptions: OperationOptionsasync function searchProcessInstancesExample(processDefinitionId: ProcessDefinitionId) {
const camunda = createCamundaClient();
const result = await camunda.searchProcessInstances(
{
filter: { processDefinitionId },
sort: [{ field: 'startDate', order: 'DESC' }],
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const instance of result.items ?? []) {
console.log(`${instance.processInstanceKey}: ${instance.state}`);
}
console.log(`Total: ${result.page.totalItems}`);
}
Search resources
Search for deployed resources based on given criteria. :::info This endpoint does not return BPMN process definitions, DMN decision definitions, or form resources. To query BPMN process definitions or DMN decision definitions, use their respective search APIs. :::
Optionaloptions: OperationOptionsasync function searchResourcesExample() {
const camunda = createCamundaClient();
const result = await camunda.searchResources(
{ page: { limit: 10 } },
{ consistency: { waitUpToMs: 5000 } }
);
for (const resource of result.items ?? []) {
console.log(`Resource: ${resource.resourceName}`);
}
}
Search roles
Search for roles based on given criteria. *
Optionaloptions: OperationOptionsSearch group roles
Search roles assigned to a group. *
Optionaloptions: OperationOptionsasync function searchRolesForGroupExample(groupId: GroupId) {
const camunda = createCamundaClient();
const result = await camunda.searchRolesForGroup(
{ groupId },
{ consistency: { waitUpToMs: 5000 } }
);
for (const role of result.items ?? []) {
console.log(`Role: ${role.name}`);
}
}
Search roles for tenant
Retrieves a filtered and sorted list of roles for a specified tenant. *
Optionaloptions: OperationOptionsasync function searchRolesForTenantExample(tenantId: TenantId) {
const camunda = createCamundaClient();
const result = await camunda.searchRolesForTenant(
{ tenantId },
{ consistency: { waitUpToMs: 5000 } }
);
for (const role of result.items ?? []) {
console.log(`Role: ${role.name}`);
}
}
Search tenants
Retrieves a filtered and sorted list of tenants. *
Optionaloptions: OperationOptionsasync function searchTenantsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchTenants(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const tenant of result.items ?? []) {
console.log(`${tenant.tenantId}: ${tenant.name}`);
}
}
Search users
Search for users based on given criteria. *
Optionaloptions: OperationOptionsasync function searchUsersExample() {
const camunda = createCamundaClient();
const result = await camunda.searchUsers(
{
filter: {},
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const user of result.items ?? []) {
console.log(`${user.username}: ${user.name}`);
}
}
Search group users
Search users assigned to a group. *
Optionaloptions: OperationOptionsasync function searchUsersForGroupExample(groupId: GroupId) {
const camunda = createCamundaClient();
const result = await camunda.searchUsersForGroup(
{ groupId },
{ consistency: { waitUpToMs: 5000 } }
);
for (const user of result.items ?? []) {
console.log(`Member: ${user.username}`);
}
}
Search role users
Search users with assigned role. *
Optionaloptions: OperationOptionsasync function searchUsersForRoleExample(roleId: RoleId) {
const camunda = createCamundaClient();
const result = await camunda.searchUsersForRole(
{ roleId },
{ consistency: { waitUpToMs: 5000 } }
);
for (const user of result.items ?? []) {
console.log(`User: ${user.username}`);
}
}
Search users for tenant
Retrieves a filtered and sorted list of users for a specified tenant. *
Optionaloptions: OperationOptionsasync function searchUsersForTenantExample(tenantId: TenantId) {
const camunda = createCamundaClient();
const result = await camunda.searchUsersForTenant(
{ tenantId },
{ consistency: { waitUpToMs: 5000 } }
);
for (const user of result.items ?? []) {
console.log(`Tenant member: ${user.username}`);
}
}
Search user task audit logs
Search for user task audit logs based on given criteria. *
Optionaloptions: OperationOptionsasync function searchUserTaskAuditLogsExample(userTaskKey: UserTaskKey) {
const camunda = createCamundaClient();
const result = await camunda.searchUserTaskAuditLogs(
{ userTaskKey },
{ consistency: { waitUpToMs: 5000 } }
);
for (const log of result.items ?? []) {
console.log(`Audit: ${log.operationType} at ${log.timestamp}`);
}
}
Search user task effective variables
Search for the effective variables of a user task. This endpoint returns deduplicated variables where each variable name appears at most once. When the same variable name exists at multiple scope levels in the scope hierarchy, the value from the innermost scope (closest to the user task) takes precedence. This is useful for retrieving the actual runtime state of variables as seen by the user task. By default, long variable values in the response are truncated.
Optionaloptions: OperationOptionsasync function searchUserTaskEffectiveVariablesExample(userTaskKey: UserTaskKey) {
const camunda = createCamundaClient();
const result = await camunda.searchUserTaskEffectiveVariables(
{ userTaskKey },
{ consistency: { waitUpToMs: 5000 } }
);
for (const variable of result.items ?? []) {
console.log(`${variable.name} = ${variable.value}`);
}
}
Search user tasks
Search for user tasks based on given criteria. *
Optionaloptions: OperationOptionsasync function searchUserTasksExample() {
const camunda = createCamundaClient();
const result = await camunda.searchUserTasks(
{
filter: { assignee: 'alice', state: 'CREATED' },
sort: [{ field: 'creationDate', order: 'DESC' }],
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const task of result.items ?? []) {
console.log(`${task.userTaskKey}: ${task.name} (${task.state})`);
}
}
Search user task variables
Search for user task variables based on given criteria. This endpoint returns all variable
documents visible from the user task's scope, including variables from parent scopes in the
scope hierarchy. If the same variable name exists at multiple scope levels, each scope's
variable is returned as a separate result. Use the
/user-tasks/{userTaskKey}/effective-variables/search endpoint to get deduplicated variables
where the innermost scope takes precedence. By default, long variable values in the response
are truncated.
Optionaloptions: OperationOptionsasync function searchUserTaskVariablesExample(userTaskKey: UserTaskKey) {
const camunda = createCamundaClient();
const result = await camunda.searchUserTaskVariables(
{ userTaskKey },
{ consistency: { waitUpToMs: 5000 } }
);
for (const variable of result.items ?? []) {
console.log(`${variable.name} = ${variable.value}`);
}
}
Search variables
Search for variables based on given criteria.
This endpoint returns variables that exist directly at the specified scopes - it does not include variables from parent scopes that would be visible through the scope hierarchy.
Variables can be process-level (scoped to the process instance) or local (scoped to specific BPMN elements like tasks, subprocesses, etc.).
By default, long variable values in the response are truncated. *
Optionaloptions: OperationOptionsasync function searchVariablesExample(processInstanceKey: ProcessInstanceKey) {
const camunda = createCamundaClient();
const result = await camunda.searchVariables(
{
filter: {
processInstanceKey,
},
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const variable of result.items ?? []) {
console.log(`${variable.name} = ${variable.value}`);
}
}
Search for process variables and bind them to a Zod schema (the DTO).
The schema's keys are the exact variable names to fetch; its shape drives validation. Only
those declared variables are queried (via a name $in [...] filter), so memory stays bound
by the DTO shape rather than the total number of variables on the instance. Results are
paged internally until every declared variable is found or the result set is exhausted.
Returns a VariableMap offering lenient access (has / get) and a strict
validate() that parses the collected values against the schema — returning a fully-typed
object or throwing a ZodError when a required variable is missing or malformed.
A Zod object schema declaring the variables to fetch.
Query scope. processInstanceKey is required; scopeKey narrows to a single
element-instance scope, tenantId filters by tenant, and pageSize tunes the page limit.
consistency controls eventual-consistency tolerance for the underlying searchVariables
calls: it defaults to { waitUpToMs: 0 } (no waiting), but a non-zero waitUpToMs makes the
paging calls poll until the data is consistent, avoiding intermittent missing variables /
ZodError on a freshly-updated instance.
when a declared variable is found at more than one
scope and no scopeKey was provided to disambiguate.
import { z } from 'zod';
const OrderVariables = z.object({ orderId: z.string(), amount: z.number().optional() });
const map = await client.searchVariablesAsDto(OrderVariables, { processInstanceKey });
if (map.has('amount')) console.log(map.get('amount'));
const order = map.validate(); // { orderId: string; amount?: number }
Stop all registered job workers (best-effort) and terminate the shared thread pool.
Suspend Batch operation
Suspends a running batch operation. This is done asynchronously, the progress can be tracked using the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Optionaloptions: OperationOptionsSuspend process instance
Suspends a running process instance, pausing further processing until it is resumed. Only process instances in the ACTIVE state can be suspended. A child process instance can be suspended independently of its parent or root process instance; suspension does not cascade to or from related instances.
Optionaloptions: OperationOptionsSuspend process instances (batch)
Suspends multiple running process instances. Any given filter for state or parentProcessInstanceKey is ignored and overridden, as only ACTIVE process instances can be suspended and suspension does not cascade between parent and child instances, so child instances are suspended independently of their parent or root instance. This is done asynchronously, the progress can be tracked using the batchOperationKey from the response and the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Optionaloptions: OperationOptionsasync function suspendProcessInstancesBatchOperationExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const result = await camunda.suspendProcessInstancesBatchOperation({
filter: {
processDefinitionKey,
},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Force-write runtime backup state
Force-writes the checkpoint and backup metadata of every partition of the physical tenant to the backup store, independent of any backup being taken or confirmed, and returns the updated state.
Optionaloptions: OperationOptionsasync function syncRuntimeBackupStateExample() {
const camunda = createCamundaClient();
// Force-writes checkpoint and backup metadata of every partition to the backup
// store, independent of any backup being taken, and returns the updated state.
const state = await camunda.syncRuntimeBackupState();
console.log(`Synced ${state.backupStates.length} partition backup states`);
}
Force-write runtime backup state across physical tenants
Force-writes the checkpoint and backup metadata of every partition of every physical tenant of the cluster, or of the one named by physicalTenantId, to that tenant's backup store, independent of any backup being taken or confirmed, and returns the updated state per physical tenant.
The request is all-or-nothing: a physical tenant whose metadata cannot be written fails the whole request, and the writes that already succeeded on other tenants are not undone. The operation is idempotent, so retrying the same call is the correct remedy. Narrow the request with physicalTenantId to write the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use POST /v2/backups/runtime/state/sync to act as a single physical tenant.
*
Optionaloptions: OperationOptionsasync function syncRuntimeBackupStateAsClusterAdminExample() {
const camunda = createCamundaClient();
// Force-writes checkpoint and backup metadata of every partition to the backup
// store on every targeted physical tenant, independent of any backup being
// taken, and returns the updated per-tenant state.
const clusterState = await camunda.syncRuntimeBackupStateAsClusterAdmin({});
console.log(`Synced ${clusterState.physicalTenants.length} physical tenants`);
}
Take a history backup
Triggers a backup of the physical tenant's history, by scheduling a snapshot of every secondary storage index it owns.
Unlike runtime backups, history backups have no generated-id mode: backupId is always
required.
Only available on clusters whose secondary storage is Elasticsearch or OpenSearch.
Optionaloptions: OperationOptionsasync function takeHistoryBackupExample() {
const camunda = createCamundaClient();
// Backups are logically ordered by id, so each successive backup must use a
// higher id than the previous one.
const backup = await camunda.takeHistoryBackup({ backupId: 100 });
console.log(`Scheduled history backup ${backup.backupId}`);
for (const snapshot of backup.scheduledSnapshots) {
console.log(` ${snapshot}`);
}
}
Take a history backup on one or every physical tenant
Triggers a history backup on every physical tenant of the cluster, or on the one named by physicalTenantId. Every targeted tenant uses the same caller-supplied backupId, but the backups are independent: they are neither coordinated nor rolled back together.
The request is all-or-nothing: the backupId is checked on every targeted tenant before any snapshot is scheduled, so a tenant that already holds this id, or that cannot be reached, fails the whole request and no backup is started anywhere. There is no aggregated cluster-level state in the response.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Only available on clusters whose secondary storage is Elasticsearch or OpenSearch. Use POST /v2/backups/history to act as a single physical tenant.
*
Optionaloptions: OperationOptionsasync function takeHistoryBackupAsClusterAdminExample() {
const camunda = createCamundaClient();
// Cluster-admin variant: fans the backup out to every physical tenant of the
// cluster (or a single one when `physicalTenantId` is given). Requires a
// separate cluster-admin security chain — Orchestration Cluster user
// credentials are NOT accepted. Each backup must use a higher id than the last.
const backup = await camunda.takeHistoryBackupAsClusterAdmin({ backupId: 100 });
console.log(`Scheduled cluster history backup ${backup.backupId}`);
for (const tenant of backup.physicalTenants) {
console.log(
` [${tenant.physicalTenantId}] scheduled ${tenant.scheduledSnapshots.length} snapshots`
);
}
}
Take a runtime backup
Triggers a backup of runtime data on all partitions of the physical tenant.
The backupId must be omitted if continuous backups and/or a backup or checkpoint
schedule is enabled for the physical tenant, as the id is generated automatically.
Otherwise, backupId is required.
Optionaloptions: OperationOptionsasync function takeRuntimeBackupExample() {
const camunda = createCamundaClient();
// Omit `backupId` when continuous backups or a backup/checkpoint schedule is
// enabled for the physical tenant — the id is then generated by the cluster.
// Otherwise `backupId` is required and must be higher than any existing one.
const backup = await camunda.takeRuntimeBackup({ backupId: 100 });
console.log(`Scheduled backup ${backup.backupId}`);
}
Take a runtime backup on one or every physical tenant
Triggers a runtime backup on every physical tenant of the cluster, or on the one named by physicalTenantId. A cluster-wide backup is a set of independent per-tenant backups, not an atomic snapshot of the cluster: they are neither coordinated nor rolled back together, and each tenant stores its own, so the same backupId can be used for all of them.
Every targeted physical tenant must be in the same backup-id mode. backupId must be omitted when every targeted tenant generates its own ids (because continuous backups and/or a backup or checkpoint schedule is enabled for it), and is required when none of them does. A cluster whose targeted tenants mix the two modes is rejected with 400 and has to be driven one tenant at a time through POST /v2/backups/runtime. In generated-id mode each tenant generates its own id, so the response reports an id per physical tenant rather than one for the cluster.
The trigger is all-or-error, and never silent about a partial trigger: if any targeted tenant cannot be triggered the response carries an error status, but its body still lists every targeted tenant — which ones were triggered, under which backupId to monitor or delete them, and why the others failed. Nothing is rolled back, so the backups that were triggered keep running and have to be deleted explicitly. A request rejected before any tenant was triggered answers with a problem detail instead, and nothing is running.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use POST /v2/backups/runtime to act as a single physical tenant.
*
Optionaloptions: OperationOptionsasync function takeRuntimeBackupAsClusterAdminExample() {
const camunda = createCamundaClient();
// Cluster-admin variant: triggers a runtime backup on every physical tenant of
// the cluster (or a single one when `physicalTenantId` is given). Requires the
// separate cluster-admin security chain — Orchestration Cluster user
// credentials are NOT accepted. Passing an explicit `backupId` is manual-id
// mode: every targeted tenant must share that id (omit it for generated-id
// mode, where each tenant generates its own). Either way the response lists the
// outcome per physical tenant rather than cluster-wide.
const backup = await camunda.takeRuntimeBackupAsClusterAdmin({ backupId: 100 });
for (const tenant of backup.physicalTenants) {
console.log(`[${tenant.physicalTenantId}] ${tenant.outcome} (backupId ${tenant.backupId})`);
}
}
Throw error for job
Reports a business error (i.e. non-technical) that occurs while processing a job.
Optionaloptions: OperationOptionsTrigger a cluster-wide leadership rebalance
Transfers leadership of every partition that is not led by its highest-priority replica towards that replica, one partition at a time. Returns as soon as the rebalance has been accepted (poll GET /cluster/v2/rebalance to monitor progress).
Each rebalance can specify overrides for the configured rebalance settings (e.g. maximum replication lag to allow). An absent request body means "use the configured settings".
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here.
*
Optionaloptions: OperationOptionsasync function triggerClusterRebalanceExample() {
const camunda = createCamundaClient();
const balance = await camunda.triggerClusterRebalance({
replicationLagThreshold: 10_000_000,
maxTransferAttempts: 3,
});
console.log(`Cluster balance state: ${balance.state}`);
if (balance.runningRebalance) {
console.log(`Rebalance started: id=${balance.runningRebalance.rebalanceId}`);
}
}
Unassign a client from a group
Unassigns a client from a group. The client is removed as a group member, with associated authorizations, roles, and tenant assignments no longer applied.
Optionaloptions: OperationOptionsUnassign a client from a tenant
Unassigns the client from the specified tenant. The client can no longer access tenant data.
Optionaloptions: OperationOptionsUnassign a group from a tenant
Unassigns a group from a specified tenant. Members of the group (users, clients) will no longer have access to the tenant's data - except they are assigned directly to the tenant.
Optionaloptions: OperationOptionsUnassign a mapping rule from a group
Unassigns a mapping rule from a group. *
Optionaloptions: OperationOptionsUnassign a mapping rule from a tenant
Unassigns a single mapping rule from a specified tenant without deleting the rule. *
Optionaloptions: OperationOptionsUnassign a role from a client
Unassigns the specified role from the client. The client will no longer inherit the authorizations associated with this role. *
Optionaloptions: OperationOptionsUnassign a role from a group
Unassigns the specified role from the group. All group members (user or client) no longer inherit the authorizations associated with this role. *
Optionaloptions: OperationOptionsUnassign a role from a mapping rule
Unassigns a role from a mapping rule. *
Optionaloptions: OperationOptionsUnassign a role from a tenant
Unassigns a role from a specified tenant. Users, Clients or Groups, that have the role assigned, will no longer have access to the tenant's data - unless they are assigned directly to the tenant.
Optionaloptions: OperationOptionsUnassign a role from a user
Unassigns a role from a user. The user will no longer inherit the authorizations associated with this role. *
Optionaloptions: OperationOptionsUnassign a user from a group
Unassigns a user from a group. The user is removed as a group member, with associated authorizations, roles, and tenant assignments no longer applied.
Optionaloptions: OperationOptionsUnassign a user from a tenant
Unassigns the user from the specified tenant. The user can no longer access tenant data.
Optionaloptions: OperationOptionsUnassign user task
Removes the assignee of a task with the given key. Unassignment waits for blocking task listeners on this lifecycle transition. If listener processing is delayed beyond the request timeout, this endpoint can return 504. Other gateway timeout causes are also possible. Retry with backoff and inspect listener worker availability and logs when this repeats.
Optionaloptions: OperationOptionsUpdate agent instance
Updates the status of an agent instance and appends a batch of history items to its conversation history. Each history item created for this request is echoed back in the response.
Optionaloptions: OperationOptionsasync function updateAgentInstanceExample(
agentInstanceKey: AgentInstanceKey,
elementInstanceKey: ElementInstanceKey,
jobKey: JobKey,
jobLeaseToken: JobLeaseToken
) {
const camunda = createCamundaClient();
await camunda.updateAgentInstance({
agentInstanceKey,
elementInstanceKey,
jobKey,
jobLeaseToken,
status: 'THINKING',
history: [
{
historyItemId: HistoryItemId.assumeExists('assistant-1'),
loopIteration: 1,
role: 'ASSISTANT',
content: [{ contentType: 'TEXT', text: 'How can I help you?' }],
producedAt: new Date().toISOString(),
metrics: { inputTokens: 150, outputTokens: 50, durationMs: 820 },
},
],
});
console.log(`Updated agent instance: ${agentInstanceKey}`);
}
Update authorization
Update the authorization with the given key. *
Optionaloptions: OperationOptionsasync function updateAuthorizationExample(authorizationKey: AuthorizationKey) {
const camunda = createCamundaClient();
await camunda.updateAuthorization({
authorizationKey,
ownerId: 'user-123',
ownerType: 'USER',
resourceId: 'order-process',
resourceType: 'PROCESS_DEFINITION',
permissionTypes: [
'CREATE_PROCESS_INSTANCE',
'READ_PROCESS_INSTANCE',
'DELETE_PROCESS_INSTANCE',
],
});
}
Update a global-scoped cluster variable
Updates the value of an existing global cluster variable. The variable must exist, otherwise a 404 error is returned.
Optionaloptions: OperationOptionsUpdate global user task listener
Updates a global user task listener. *
Optionaloptions: OperationOptionsUpdate group
Update a group with the given ID. *
Optionaloptions: OperationOptionsUpdate job
Update a job with the given key. *
Optionaloptions: OperationOptionsUpdate jobs (batch)
Creates a batch operation to update jobs matching the given filter. At least one changeset field must be non-null. This is done asynchronously; the progress can be tracked using the batchOperationKey from the response and the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Optionaloptions: OperationOptionsasync function updateJobsBatchOperationExample() {
const camunda = createCamundaClient();
const result = await camunda.updateJobsBatchOperation({
filter: {
type: 'payment-processing',
hasFailedWithRetriesLeft: false,
},
changeset: {
retries: 3,
},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Update mapping rule
Update a mapping rule.
Optionaloptions: OperationOptionsUpdate role
Update a role with the given ID. *
Optionaloptions: OperationOptionsUpdate tenant
Updates an existing tenant. *
Optionaloptions: OperationOptionsUpdate a tenant-scoped cluster variable
Updates the value of an existing tenant-scoped cluster variable. The variable must exist, otherwise a 404 error is returned.
Optionaloptions: OperationOptionsUpdate user
Updates a user. *
Optionaloptions: OperationOptionsUpdate user task
Update a user task with the given key. Updates wait for blocking task listeners on this lifecycle transition. If listener processing is delayed beyond the request timeout, this endpoint can return 504. Other gateway timeout causes are also possible. Retry with backoff and inspect listener worker availability and logs when this repeats.
Optionaloptions: OperationOptions
The Camunda client's operation methods. Create clients with createCamundaClient or CamundaClient, which add
.paginate(...)to every search operation.