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' });
}
}
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: 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 running process instances. Since only ACTIVE root instances can be cancelled, any given filters for state and parentProcessInstanceKey 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 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,
});
console.log(`Cluster change ${change.changeId}:`);
for (const op of change.plannedChanges) {
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) {
const camunda = createCamundaClient();
const result = await camunda.createAgentInstance({
elementInstanceKey,
definition: {
model: 'gpt-4o',
provider: 'openai',
systemPrompt: 'You are a helpful assistant.',
},
});
console.log(`Created agent instance: ${result.agentInstanceKey}`);
}
Create agent instance history item
Appends a single history item to an agent instance's conversation history. The created item has commitStatus PENDING until the job identified by jobLease completes successfully, at which point it transitions to COMMITTED. If the job fails or is superseded by a retry, the item is marked DISCARDED.
Optionaloptions: OperationOptionsasync function createAgentInstanceHistoryItemExample(
agentInstanceKey: AgentInstanceKey,
elementInstanceKey: ElementInstanceKey,
jobKey: JobKey,
jobLease: string
) {
const camunda = createCamundaClient();
const result = await camunda.createAgentInstanceHistoryItem({
agentInstanceKey,
elementInstanceKey,
jobKey,
jobLease,
role: 'ASSISTANT',
content: [{ contentType: 'TEXT', text: 'How can I help you today?' }],
producedAt: new Date().toISOString(),
});
console.log(`Created history item: ${result.historyItemKey}`);
}
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.
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 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. The historic data is deleted asynchronously via a batch operation. The details of
the created batch operation are included in the response. Note that history deletion is only
supported for process resources; for other resource types this flag is ignored and no history
will be deleted.
*
OptionaldeleteHistory?: booleanIndicates if the historic data of a process resource should be deleted via a batch operation asynchronously.
This flag is only effective for process resources. For other resource types
(decisions, forms, generic resources), this flag is ignored and no history
will be deleted. In those cases, the batchOperation field in the response
will not be populated.
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 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 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 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 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.
*
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 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 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 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 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 secrets (alpha)
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.
Secret names that cannot form a valid camunda.secrets.<name> reference (for example names
containing a dot or a dash) are omitted, since they could neither be resolved nor be used in
a BPMN expression.
This endpoint is an alpha feature and may be subject to change in future releases.
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
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 (alpha)
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.
This endpoint is an alpha feature and may be subject to change in future releases.
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 op of change.plannedChanges) {
console.log(` ${op.operation}${op.mode ? ` -> ${op.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
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.
Optionaloptions: OperationOptionsResume process instances (batch)
Resumes multiple suspended process instances. Since only SUSPENDED root instances can be resumed, any given filters for state and parentProcessInstanceKey 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 resumeProcessInstancesBatchOperationExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const result = await camunda.resumeProcessInstancesBatchOperation({
filter: {
processDefinitionKey,
},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
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 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.
Optionaloptions: OperationOptionsSuspend process instances (batch)
Suspends multiple running process instances. Since only ACTIVE root instances can be suspended, any given filters for state and parentProcessInstanceKey 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 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`);
}
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}`);
}
Throw error for job
Reports a business error (i.e. non-technical) that occurs while processing a job.
Optionaloptions: OperationOptionsUnassign 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 mutable fields of an agent instance: status, metric counters, and tools. Metric values are treated as deltas and applied immediately to the aggregate counters. Tool updates replace the existing tool list.
Optionaloptions: OperationOptionsasync function updateAgentInstanceExample(
agentInstanceKey: AgentInstanceKey,
elementInstanceKey: ElementInstanceKey
) {
const camunda = createCamundaClient();
await camunda.updateAgentInstance({
agentInstanceKey,
elementInstanceKey,
status: 'THINKING',
metrics: {
inputTokens: 150,
outputTokens: 50,
modelCalls: 1,
},
});
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
Internal accessor for support logger (no public API commitment yet).