Class: CamundaClientBase
The Camunda client's operation methods. Create clients with createCamundaClient
or CamundaClient, which add .paginate(...) to every search operation.
Constructors
Constructor
new CamundaClientBase(opts?): CamundaClientBase;
Parameters
opts?
CamundaOptions = {}
Returns
CamundaClientBase
Accessors
clock
Get Signature
get clock(): Clock;
Clock backing SDK-internal cadence. The injected one when supplied, else the live clock.
Returns
config
Get Signature
get config(): Readonly<CamundaConfig>;
Returns
Readonly<CamundaConfig>
Methods
_getSupportLogger()
_getSupportLogger(): SupportLogger;
Internal accessor for support logger (no public API commitment yet).
Returns
_invokeWithRetry()
_invokeWithRetry<T>(op, opts): Promise<T>;
Internal invocation helper to apply global backpressure gating + retry + normalization
Type Parameters
T
T
Parameters
op
() => Promise<T>
opts
classify?
(e) => object
exempt?
boolean
opId
string
retryOverride?
| false
| Partial<HttpRetryPolicy>
Returns
Promise<T>
activateAdHocSubProcessActivities()
activateAdHocSubProcessActivities(input, options?): CancelablePromise<void>;
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.
Parameters
input
activateAdHocSubProcessActivitiesInput
options?
Returns
CancelablePromise<void>
Example
Activate ad-hoc sub-process activities
async function activateAdHocSubProcessActivitiesExample(
adHocSubProcessInstanceKey: ElementInstanceKey,
elementId: ElementId
) {
const camunda = createCamundaClient();
await camunda.activateAdHocSubProcessActivities({
adHocSubProcessInstanceKey,
elements: [{ elementId }],
});
}
Operation Id
activateAdHocSubProcessActivities
Tags
Ad-hoc sub-process
activateJobs()
Call Signature
activateJobs(input, options?): CancelablePromise<{
jobs: EnrichedActivatedJobOf<ActivatedJobResultWithJobLeaseToken>[];
}>;
Activate jobs
Iterate through all known partitions and activate jobs up to the requested maximum.
Parameters
input
JobActivationRequest & object
options?
Returns
CancelablePromise<{
jobs: EnrichedActivatedJobOf<ActivatedJobResultWithJobLeaseToken>[];
}>
Example
Activate and process jobs
async 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" });
}
}
Operation Id
activateJobs
Tags
Job
Call Signature
activateJobs(input, options?): CancelablePromise<{
jobs: EnrichedActivatedJobOf<ActivatedJobResultWithoutJobLeaseToken>[];
}>;
Activate jobs
Iterate through all known partitions and activate jobs up to the requested maximum.
Parameters
input
JobActivationRequest & object
options?
Returns
CancelablePromise<{
jobs: EnrichedActivatedJobOf<ActivatedJobResultWithoutJobLeaseToken>[];
}>
Example
Activate and process jobs
async 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" });
}
}
Operation Id
activateJobs
Tags
Job
Call Signature
activateJobs(input, options?): CancelablePromise<{
jobs: EnrichedActivatedJob[];
}>;
Activate jobs
Iterate through all known partitions and activate jobs up to the requested maximum.
Parameters
input
options?
Returns
CancelablePromise<{
jobs: EnrichedActivatedJob[];
}>
Example
Activate and process jobs
async 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" });
}
}
Operation Id
activateJobs
Tags
Job
assignClientToGroup()
assignClientToGroup(input, options?): CancelablePromise<void>;
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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Assign a client to a group
async function assignClientToGroupExample(
groupId: GroupId,
clientId: ClientId
) {
const camunda = createCamundaClient();
await camunda.assignClientToGroup({
groupId,
clientId,
});
}
Operation Id
assignClientToGroup
Tags
Group
assignClientToTenant()
assignClientToTenant(input, options?): CancelablePromise<void>;
Assign a client to a tenant
Assign the client to the specified tenant. The client can then access tenant data and perform authorized actions.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Assign a client to a tenant
async function assignClientToTenantExample(
tenantId: TenantId,
clientId: ClientId
) {
const camunda = createCamundaClient();
await camunda.assignClientToTenant({
tenantId,
clientId,
});
}
Operation Id
assignClientToTenant
Tags
Tenant
assignGroupToTenant()
assignGroupToTenant(input, options?): CancelablePromise<void>;
Assign 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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Assign a group to a tenant
async function assignGroupToTenantExample(
tenantId: TenantId,
groupId: GroupId
) {
const camunda = createCamundaClient();
await camunda.assignGroupToTenant({
tenantId,
groupId,
});
}
Operation Id
assignGroupToTenant
Tags
Tenant
assignMappingRuleToGroup()
assignMappingRuleToGroup(input, options?): CancelablePromise<void>;
Assign a mapping rule to a group
Assigns a mapping rule to a group. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Assign a mapping rule to a group
async function assignMappingRuleToGroupExample(
groupId: GroupId,
mappingRuleId: MappingRuleId
) {
const camunda = createCamundaClient();
await camunda.assignMappingRuleToGroup({
groupId,
mappingRuleId,
});
}
Operation Id
assignMappingRuleToGroup
Tags
Group
assignMappingRuleToTenant()
assignMappingRuleToTenant(input, options?): CancelablePromise<void>;
Assign a mapping rule to a tenant
Assign a single mapping rule to a specified tenant. *
Parameters
input
assignMappingRuleToTenantInput
options?
Returns
CancelablePromise<void>
Example
Assign a mapping rule to a tenant
async function assignMappingRuleToTenantExample(
tenantId: TenantId,
mappingRuleId: MappingRuleId
) {
const camunda = createCamundaClient();
await camunda.assignMappingRuleToTenant({
tenantId,
mappingRuleId,
});
}
Operation Id
assignMappingRuleToTenant
Tags
Tenant
assignProcessInstanceBusinessId()
assignProcessInstanceBusinessId(input, options?): CancelablePromise<void>;
Assign 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.
Parameters
input
assignProcessInstanceBusinessIdInput
options?
Returns
CancelablePromise<void>
Example
Assign a business ID to a process instance
async function assignProcessInstanceBusinessIdExample(
processInstanceKey: ProcessInstanceKey,
businessId: BusinessId
) {
const camunda = createCamundaClient();
await camunda.assignProcessInstanceBusinessId({
processInstanceKey,
businessId,
});
}
Operation Id
assignProcessInstanceBusinessId
Tags
Process instance
assignRoleToClient()
assignRoleToClient(input, options?): CancelablePromise<void>;
Assign a role to a client
Assigns the specified role to the client. The client will inherit the authorizations associated with this role. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Assign a role to a client
async function assignRoleToClientExample(roleId: RoleId, clientId: ClientId) {
const camunda = createCamundaClient();
await camunda.assignRoleToClient({
roleId,
clientId,
});
}
Operation Id
assignRoleToClient
Tags
Role
assignRoleToGroup()
assignRoleToGroup(input, options?): CancelablePromise<void>;
Assign 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. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Assign a role to a group
async function assignRoleToGroupExample(roleId: RoleId, groupId: GroupId) {
const camunda = createCamundaClient();
await camunda.assignRoleToGroup({
roleId,
groupId,
});
}
Operation Id
assignRoleToGroup
Tags
Role
assignRoleToMappingRule()
assignRoleToMappingRule(input, options?): CancelablePromise<void>;
Assign a role to a mapping rule
Assigns a role to a mapping rule. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Assign a role to a mapping rule
async function assignRoleToMappingRuleExample(
roleId: RoleId,
mappingRuleId: MappingRuleId
) {
const camunda = createCamundaClient();
await camunda.assignRoleToMappingRule({
roleId,
mappingRuleId,
});
}
Operation Id
assignRoleToMappingRule
Tags
Role
assignRoleToTenant()
assignRoleToTenant(input, options?): CancelablePromise<void>;
Assign 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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Assign a role to a tenant
async function assignRoleToTenantExample(tenantId: TenantId, roleId: RoleId) {
const camunda = createCamundaClient();
await camunda.assignRoleToTenant({
tenantId,
roleId,
});
}
Operation Id
assignRoleToTenant
Tags
Tenant
assignRoleToUser()
assignRoleToUser(input, options?): CancelablePromise<void>;
Assign a role to a user
Assigns the specified role to the user. The user will inherit the authorizations associated with this role. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Assign a role to a user
async function assignRoleToUserExample(roleId: RoleId, username: Username) {
const camunda = createCamundaClient();
await camunda.assignRoleToUser({
roleId,
username,
});
}
Operation Id
assignRoleToUser
Tags
Role
assignUserTask()
assignUserTask(input, options?): CancelablePromise<void>;
Assign 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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Assign a user task
async function assignUserTaskExample(userTaskKey: UserTaskKey) {
const camunda = createCamundaClient();
await camunda.assignUserTask({
userTaskKey,
assignee: "alice",
allowOverride: true,
});
}
Operation Id
assignUserTask
Tags
User task
assignUserToGroup()
assignUserToGroup(input, options?): CancelablePromise<void>;
Assign 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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Assign a user to a group
async function assignUserToGroupExample(groupId: GroupId, username: Username) {
const camunda = createCamundaClient();
await camunda.assignUserToGroup({
groupId,
username,
});
}
Operation Id
assignUserToGroup
Tags
Group
assignUserToTenant()
assignUserToTenant(input, options?): CancelablePromise<void>;
Assign a user to a tenant
Assign a single user to a specified tenant. The user can then access tenant data and perform authorized actions. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Assign a user to a tenant
async function assignUserToTenantExample(
tenantId: TenantId,
username: Username
) {
const camunda = createCamundaClient();
await camunda.assignUserToTenant({
tenantId,
username,
});
}
Operation Id
assignUserToTenant
Tags
Tenant
broadcastSignal()
broadcastSignal(input, options?): CancelablePromise<SignalBroadcastResult>;
Broadcast signal
Broadcasts a signal. *
Parameters
input
options?
Returns
CancelablePromise<SignalBroadcastResult>
Example
Broadcast a signal
async function broadcastSignalExample() {
const camunda = createCamundaClient();
const result = await camunda.broadcastSignal({
signalName: "system-shutdown",
variables: {
reason: "Scheduled maintenance",
},
});
console.log(`Signal broadcast key: ${result.signalKey}`);
}
Operation Id
broadcastSignal
Tags
Signal
cancelBatchOperation()
cancelBatchOperation(input, options?): CancelablePromise<void>;
Cancel 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}).
Parameters
input
batchOperationKey
options?
Returns
CancelablePromise<void>
Example
Cancel a batch operation
async function cancelBatchOperationExample(
batchOperationKey: BatchOperationKey
) {
const camunda = createCamundaClient();
await camunda.cancelBatchOperation({ batchOperationKey });
}
Operation Id
cancelBatchOperation
Tags
Batch operation
cancelClusterRebalance()
cancelClusterRebalance(options?): CancelablePromise<RebalanceCancellationResponse>;
Stop the running rebalance
Asks the running rebalance to stop once the transfer in flight has finished. Partitions already transferred keep their new leaders, and those the rebalance had not yet reached keep their current ones.
Cancellation requests are idempotent and always accepted. The wasRunning response field can be used to distinguish a cancellation that found a running rebalance from one that did not.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. *
Parameters
options?
Returns
CancelablePromise<RebalanceCancellationResponse>
Example
Cancel the running cluster rebalance
async function cancelClusterRebalanceExample() {
const camunda = createCamundaClient();
const result = await camunda.cancelClusterRebalance();
console.log(
`Cancel requested; was a rebalance running? ${result.wasRunning}`
);
}
Operation Id
cancelClusterRebalance
Tags
Cluster
cancelProcessInstance()
cancelProcessInstance(input, options?): CancelablePromise<void>;
Cancel 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.
Parameters
input
object & object
options?
Returns
CancelablePromise<void>
Example
Cancel a process instance
async 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,
});
}
Operation Id
cancelProcessInstance
Tags
Process instance
cancelProcessInstancesBatchOperation()
cancelProcessInstancesBatchOperation(input, options?): CancelablePromise<BatchOperationCreatedResult>;
Cancel process instances (batch)
Cancels multiple active or suspended process instances. Since only ACTIVE and SUSPENDED 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}).
Parameters
input
ProcessInstanceCancellationBatchOperationRequest
options?
Returns
CancelablePromise<BatchOperationCreatedResult>
Example
Cancel process instances in batch
async function cancelProcessInstancesBatchOperationExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const result = await camunda.cancelProcessInstancesBatchOperation({
filter: {
processDefinitionKey,
},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Operation Id
cancelProcessInstancesBatchOperation
Tags
Process instance
changeClusterMode()
changeClusterMode(input, options?): CancelablePromise<ClusterModeChangeResponse>;
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. *
Parameters
input
options?
Returns
CancelablePromise<ClusterModeChangeResponse>
Example
Change cluster mode
async function changeClusterModeExample() {
const camunda = createCamundaClient();
// Transition the cluster into recovery mode. Pass `dryRun: true` to validate
// the request and inspect the resulting plan without applying it. Omit it (or
// set it to false) to actually trigger the transition.
const change = await camunda.changeClusterMode({
mode: "RECOVERING",
dryRun: true,
});
// Operations are grouped by physical tenant; a null tenant means the operation
// is not scoped to one, such as a broker lifecycle operation.
console.log(`Cluster change ${change.changeId}:`);
for (const group of change.plannedChanges) {
console.log(` ${group.physicalTenantId ?? "cluster-wide"}:`);
for (const op of group.operations) {
console.log(` ${op.operation}${op.mode ? ` -> ${op.mode}` : ""}`);
}
}
}
Operation Id
changeClusterMode
Tags
Recovery
changeClusterModeAsClusterAdmin()
changeClusterModeAsClusterAdmin(input, options?): CancelablePromise<ClusterModeChangeResponse>;
Change the cluster mode of one or every physical tenant
Transitions physical tenants between processing and recovery mode.
If the physicalTenantId parameter is not provided, all available physical tenants are transitioned individually.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. *
Parameters
input
changeClusterModeAsClusterAdminInput
options?
Returns
CancelablePromise<ClusterModeChangeResponse>
Example
Change cluster mode as cluster admin
async function changeClusterModeAsClusterAdminExample() {
const camunda = createCamundaClient();
// The cluster-admin variant can target a single physical tenant. Omit
// `physicalTenantId` to apply the change to every physical tenant.
const change = await camunda.changeClusterModeAsClusterAdmin({
mode: "RECOVERING",
physicalTenantId: "default",
dryRun: true,
});
console.log(`Cluster change ${change.changeId}:`);
for (const group of change.plannedChanges) {
console.log(` ${group.physicalTenantId ?? "cluster-wide"}:`);
for (const op of group.operations) {
console.log(` ${op.operation}${op.mode ? ` -> ${op.mode}` : ""}`);
}
}
}
Operation Id
changeClusterModeAsClusterAdmin
Tags
Recovery
clearAuthCache()
clearAuthCache(opts?): void;
Parameters
opts?
disk?
boolean
memory?
boolean
Returns
void
completeJob()
completeJob(input, options?): CancelablePromise<void>;
Complete job
Complete a job with the given payload, which allows completing the associated service task.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Complete a job
async function completeJobExample(jobKey: JobKey) {
const camunda = createCamundaClient();
await camunda.completeJob({
jobKey,
variables: {
paymentId: "PAY-123",
status: "completed",
},
});
}
Operation Id
completeJob
Tags
Job
completeUserTask()
completeUserTask(input, options?): CancelablePromise<void>;
Complete 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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Complete a user task
async function completeUserTaskExample(userTaskKey: UserTaskKey) {
const camunda = createCamundaClient();
await camunda.completeUserTask({
userTaskKey,
variables: {
approved: true,
comment: "Looks good",
},
});
}
Operation Id
completeUserTask
Tags
User task
configure()
configure(next): void;
Parameters
next
Returns
void
correlateMessage()
correlateMessage(input, options?): CancelablePromise<MessageCorrelationResult>;
Correlate 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.
Parameters
input
options?
Returns
CancelablePromise<MessageCorrelationResult>
Example
Correlate a message
async 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}`);
}
Operation Id
correlateMessage
Tags
Message
createAdminUser()
createAdminUser(input, options?): CancelablePromise<UserCreateResult>;
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. *
Parameters
input
options?
Returns
CancelablePromise<UserCreateResult>
Example
Create an admin user
async 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}`);
}
Operation Id
createAdminUser
Tags
Setup
createAgentInstance()
createAgentInstance(input, options?): CancelablePromise<AgentInstanceCreationResult>;
Create agent instance
Creates a new agent instance. The returned key identifies the instance and must be used in subsequent update and query calls.
Parameters
input
options?
Returns
CancelablePromise<AgentInstanceCreationResult>
Example
Create an agent instance
async function createAgentInstanceExample(
elementInstanceKey: ElementInstanceKey,
jobKey: JobKey,
jobLeaseToken: JobLeaseToken
) {
const camunda = createCamundaClient();
// The batch must open with a CONFIGURATION item; it establishes the model,
// provider and system prompt for the instance.
const result = await camunda.createAgentInstance({
elementInstanceKey,
jobKey,
jobLeaseToken,
history: [
{
historyItemId: HistoryItemId.assumeExists("configuration-1"),
loopIteration: 1,
role: "CONFIGURATION",
content: [],
producedAt: new Date().toISOString(),
model: "gpt-4o",
provider: "openai",
systemPrompt: [
{ contentType: "TEXT", text: "You are a helpful assistant." },
],
},
],
});
console.log(`Created agent instance: ${result.agentInstanceKey}`);
}
Operation Id
createAgentInstance
Tags
Agent instance
createAuthorization()
createAuthorization(input, options?): CancelablePromise<AuthorizationCreateResult>;
Create authorization
Create the authorization. *
Parameters
input
| AuthorizationIdBasedRequest
| AuthorizationPropertyBasedRequest
options?
Returns
CancelablePromise<AuthorizationCreateResult>
Example
Create an authorization
async 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}`);
}
Operation Id
createAuthorization
Tags
Authorization
createDeployment()
createDeployment(input, options?): CancelablePromise<ExtendedDeploymentResult>;
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.
Parameters
input
options?
Returns
CancelablePromise<ExtendedDeploymentResult>
Enriched deployment result with typed arrays (processes, decisions, decisionRequirements, forms, resources).
Example
Deploy resources from files
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}`);
}
Operation Id
createDeployment
Tags
Resource
createDocument()
createDocument(input, options?): CancelablePromise<DocumentReference>;
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)
Parameters
input
options?
Returns
CancelablePromise<DocumentReference>
Example
Upload a document
async 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}`);
}
Operation Id
createDocument
Tags
Document
createDocumentLink()
createDocumentLink(input, options?): CancelablePromise<DocumentLink>;
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
Parameters
input
options?
Returns
CancelablePromise<DocumentLink>
Example
Create a document link
async function createDocumentLinkExample(documentId: DocumentId) {
const camunda = createCamundaClient();
const link = await camunda.createDocumentLink({
documentId,
timeToLive: 3600000,
});
console.log(`Document link: ${link.url}`);
}
Operation Id
createDocumentLink
Tags
Document
createDocuments()
createDocuments(input, options?): CancelablePromise<DocumentCreationBatchResponse>;
Upload 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)
Parameters
input
options?
Returns
CancelablePromise<DocumentCreationBatchResponse>
Example
Upload multiple documents
async 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}`);
}
}
Operation Id
createDocuments
Tags
Document
createElementInstanceVariables()
createElementInstanceVariables(input, options?): CancelablePromise<void>;
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.
Parameters
input
createElementInstanceVariablesInput
options?
Returns
CancelablePromise<void>
Example
Create element instance variables
async function createElementInstanceVariablesExample(
elementInstanceKey: ElementInstanceKey
) {
const camunda = createCamundaClient();
await camunda.createElementInstanceVariables({
elementInstanceKey,
variables: { orderId: "ORD-12345", status: "processing" },
});
}
Operation Id
createElementInstanceVariables
Tags
Element instance
createGlobalClusterVariable()
createGlobalClusterVariable(input, options?): CancelablePromise<ClusterVariableResult>;
Create a global-scoped cluster variable
Create a global-scoped cluster variable. *
Parameters
input
options?
Returns
CancelablePromise<ClusterVariableResult>
Example
Create a global cluster variable
async function createGlobalClusterVariableExample(name: ClusterVariableName) {
const camunda = createCamundaClient();
const result = await camunda.createGlobalClusterVariable({
name,
value: { darkMode: true },
});
console.log(`Created: ${result.name}`);
}
Operation Id
createGlobalClusterVariable
Tags
Cluster Variable
createGlobalTaskListener()
createGlobalTaskListener(input, options?): CancelablePromise<GlobalTaskListenerResult>;
Create global user task listener
Create a new global user task listener. *
Parameters
input
CreateGlobalTaskListenerRequest
options?
Returns
CancelablePromise<GlobalTaskListenerResult>
Example
Create a global task listener
async 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}`);
}
Operation Id
createGlobalTaskListener
Tags
Global listener
createGroup()
createGroup(input, options?): CancelablePromise<GroupCreateResult>;
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.
Parameters
input
options?
Returns
CancelablePromise<GroupCreateResult>
Example
Create a group
async function createGroupExample(groupId: GroupId) {
const camunda = createCamundaClient();
const result = await camunda.createGroup({
groupId,
name: "Engineering Team",
});
console.log(`Created group: ${result.groupId}`);
}
Operation Id
createGroup
Tags
Group
createJobWorker()
createJobWorker<In, Out, Headers>(cfg): JobWorker;
Create 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.
Type Parameters
In
In extends ZodTypeAny<unknown, unknown, $ZodTypeInternals<unknown, unknown>> = any
Out
Out extends ZodTypeAny<unknown, unknown, $ZodTypeInternals<unknown, unknown>> = any
Headers
Headers extends ZodTypeAny<unknown, unknown, $ZodTypeInternals<unknown, unknown>> = any
Parameters
cfg
JobWorkerConfig<In, Out, Headers>
Worker configuration
Returns
Examples
Create a job worker
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();
}
Job worker with error handling
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;
}
createMappingRule()
createMappingRule(input, options?): CancelablePromise<MappingRuleCreateUpdateResult>;
Create mapping rule
Create a new mapping rule
Parameters
input
options?
Returns
CancelablePromise<MappingRuleCreateUpdateResult>
Example
Create a mapping rule
async 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}`);
}
Operation Id
createMappingRule
Tags
Mapping rule
createProcessInstance()
createProcessInstance(input, options?): CancelablePromise<CreateProcessInstanceResult>;
Create process instance
Creates and starts an instance of the specified process. The process definition to use to create the instance can be specified either using its unique key (as returned by Deploy resources), or using the BPMN process id and a version. If only the process definition id is given, the latest ACTIVE version is used. If no ACTIVE version exists, the request is rejected as not found.
Waits for the completion of the process instance before returning a result when awaitCompletion is enabled.
Parameters
input
| ProcessInstanceCreationInstructionByKey
| ProcessInstanceCreationInstructionById
options?
Returns
CancelablePromise<CreateProcessInstanceResult>
Examples
By ID
async 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}`);
}
By key
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}`);
}
Operation Id
createProcessInstance
Tags
Process instance
createRole()
createRole(input, options?): CancelablePromise<RoleCreateResult>;
Create role
Create a new role. *
Parameters
input
options?
Returns
CancelablePromise<RoleCreateResult>
Example
Create a role
async function createRoleExample(roleId: RoleId) {
const camunda = createCamundaClient();
const result = await camunda.createRole({
roleId,
name: "Process Admin",
});
console.log(`Created role: ${result.roleId}`);
}
Operation Id
createRole
Tags
Role
createTenant()
createTenant(input, options?): CancelablePromise<TenantCreateResult>;
Create tenant
Creates a new tenant. *
Parameters
input
options?
Returns
CancelablePromise<TenantCreateResult>
Example
Create a tenant
async function createTenantExample(tenantId: TenantId) {
const camunda = createCamundaClient();
const result = await camunda.createTenant({
tenantId,
name: "Customer Service",
});
console.log(`Created tenant: ${result.tenantId}`);
}
Operation Id
createTenant
Tags
Tenant
createTenantClusterVariable()
createTenantClusterVariable(input, options?): CancelablePromise<ClusterVariableResult>;
Create a tenant-scoped cluster variable
Create a new cluster variable for the given tenant. *
Parameters
input
createTenantClusterVariableInput
options?
Returns
CancelablePromise<ClusterVariableResult>
Example
Create a tenant cluster variable
async 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}`);
}
Operation Id
createTenantClusterVariable
Tags
Cluster Variable
createThreadedJobWorker()
createThreadedJobWorker<In, Out, Headers>(cfg): ThreadedJobWorker;
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.
Type Parameters
In
In extends ZodTypeAny<unknown, unknown, $ZodTypeInternals<unknown, unknown>> = any
Out
Out extends ZodTypeAny<unknown, unknown, $ZodTypeInternals<unknown, unknown>> = any
Headers
Headers extends ZodTypeAny<unknown, unknown, $ZodTypeInternals<unknown, unknown>> = any
Parameters
cfg
ThreadedJobWorkerConfig<In, Out, Headers>
Threaded worker configuration
Returns
Example
Create a threaded job worker
const worker = client.createThreadedJobWorker({
jobType: "cpu-heavy-task",
handlerModule: "./my-handler.js",
maxParallelJobs: 32,
jobTimeoutMs: 30000,
});
createUser()
createUser(input, options?): CancelablePromise<UserCreateResult>;
Create user
Create a new user. *
Parameters
input
options?
Returns
CancelablePromise<UserCreateResult>
Example
Create a user
async 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}`);
}
Operation Id
createUser
Tags
User
deleteAuthorization()
deleteAuthorization(input, options?): CancelablePromise<void>;
Delete authorization
Deletes the authorization with the given key. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Delete an authorization
async function deleteAuthorizationExample(authorizationKey: AuthorizationKey) {
const camunda = createCamundaClient();
await camunda.deleteAuthorization({ authorizationKey });
}
Operation Id
deleteAuthorization
Tags
Authorization
deleteDecisionInstance()
deleteDecisionInstance(input, options?): CancelablePromise<void>;
Delete decision instance
Delete all associated decision evaluations based on provided key. *
Parameters
input
object & object
options?
Returns
CancelablePromise<void>
Example
Delete a decision instance
async function deleteDecisionInstanceExample(
decisionEvaluationKey: DecisionEvaluationKey
) {
const camunda = createCamundaClient();
await camunda.deleteDecisionInstance({ decisionEvaluationKey });
}
Operation Id
deleteDecisionInstance
Tags
Decision instance
deleteDecisionInstancesBatchOperation()
deleteDecisionInstancesBatchOperation(input, options?): CancelablePromise<BatchOperationCreatedResult>;
Delete 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}).
Parameters
input
DecisionInstanceDeletionBatchOperationRequest
options?
Returns
CancelablePromise<BatchOperationCreatedResult>
Example
Delete decision instances in batch
async function deleteDecisionInstancesBatchOperationExample() {
const camunda = createCamundaClient();
const result = await camunda.deleteDecisionInstancesBatchOperation({
filter: {},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Operation Id
deleteDecisionInstancesBatchOperation
Tags
Decision instance
deleteDocument()
deleteDocument(input, options?): CancelablePromise<void>;
Delete 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)
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Delete a document
async function deleteDocumentExample(documentId: DocumentId) {
const camunda = createCamundaClient();
await camunda.deleteDocument({ documentId });
}
Operation Id
deleteDocument
Tags
Document
deleteGlobalClusterVariable()
deleteGlobalClusterVariable(input, options?): CancelablePromise<void>;
Delete a global-scoped cluster variable
Delete a global-scoped cluster variable. *
Parameters
input
deleteGlobalClusterVariableInput
options?
Returns
CancelablePromise<void>
Example
Delete a global cluster variable
async function deleteGlobalClusterVariableExample(name: ClusterVariableName) {
const camunda = createCamundaClient();
await camunda.deleteGlobalClusterVariable({ name });
}
Operation Id
deleteGlobalClusterVariable
Tags
Cluster Variable
deleteGlobalTaskListener()
deleteGlobalTaskListener(input, options?): CancelablePromise<void>;
Delete global user task listener
Deletes a global user task listener. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Delete a global task listener
async function deleteGlobalTaskListenerExample(id: GlobalListenerId) {
const camunda = createCamundaClient();
await camunda.deleteGlobalTaskListener({
id,
});
}
Operation Id
deleteGlobalTaskListener
Tags
Global listener
deleteGroup()
deleteGroup(input, options?): CancelablePromise<void>;
Delete group
Deletes the group with the given ID. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Delete a group
async function deleteGroupExample(groupId: GroupId) {
const camunda = createCamundaClient();
await camunda.deleteGroup({ groupId });
}
Operation Id
deleteGroup
Tags
Group
deleteHistoryBackup()
deleteHistoryBackup(input, options?): CancelablePromise<void>;
Delete history backup
Deletes the history backup with the given id, by deleting every snapshot that makes it up.
Only available on clusters whose secondary storage is Elasticsearch or OpenSearch.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Delete a history backup
async function deleteHistoryBackupExample() {
const camunda = createCamundaClient();
await camunda.deleteHistoryBackup({ backupId: 100 });
}
Operation Id
deleteHistoryBackup
Tags
Backup
deleteHistoryBackupAsClusterAdmin()
deleteHistoryBackupAsClusterAdmin(input, options?): CancelablePromise<void>;
Delete a history backup across physical tenants
Deletes the history backup with the given id from every physical tenant of the cluster, or from the one named by physicalTenantId. A tenant that does not hold the backup has already reached the requested end state, so it counts as deleted rather than as a failure.
The request is all-or-nothing: a physical tenant the backup cannot be deleted from fails the whole request, and the deletions that already succeeded on other tenants are not undone. Narrow the request with physicalTenantId to delete from the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Only available on clusters whose secondary storage is Elasticsearch or OpenSearch. Use DELETE /v2/backups/history/{backupId} to act as a single physical tenant. *
Parameters
input
deleteHistoryBackupAsClusterAdminInput
options?
Returns
CancelablePromise<void>
Example
Delete a history backup (cluster admin)
async function deleteHistoryBackupAsClusterAdminExample() {
const camunda = createCamundaClient();
// Deletion fans out to every physical tenant (or a single one when
// `physicalTenantId` is given) and is not undone if a later tenant fails.
await camunda.deleteHistoryBackupAsClusterAdmin({ backupId: 100 });
}
Operation Id
deleteHistoryBackupAsClusterAdmin
Tags
Backup
deleteMappingRule()
deleteMappingRule(input, options?): CancelablePromise<void>;
Delete a mapping rule
Deletes the mapping rule with the given ID.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Delete a mapping rule
async function deleteMappingRuleExample(mappingRuleId: MappingRuleId) {
const camunda = createCamundaClient();
await camunda.deleteMappingRule({ mappingRuleId });
}
Operation Id
deleteMappingRule
Tags
Mapping rule
deleteProcessInstance()
deleteProcessInstance(input, options?): CancelablePromise<void>;
Delete process instance
Deletes a process instance. Only instances that are completed or terminated can be deleted. *
Parameters
input
object & object
options?
Returns
CancelablePromise<void>
Example
Delete a process instance
async function deleteProcessInstanceExample(
processInstanceKey: ProcessInstanceKey
) {
const camunda = createCamundaClient();
await camunda.deleteProcessInstance({ processInstanceKey });
}
Operation Id
deleteProcessInstance
Tags
Process instance
deleteProcessInstancesBatchOperation()
deleteProcessInstancesBatchOperation(input, options?): CancelablePromise<BatchOperationCreatedResult>;
Delete 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}).
Parameters
input
ProcessInstanceDeletionBatchOperationRequest
options?
Returns
CancelablePromise<BatchOperationCreatedResult>
Example
Delete process instances in batch
async function deleteProcessInstancesBatchOperationExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const result = await camunda.deleteProcessInstancesBatchOperation({
filter: {
processDefinitionKey,
},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Operation Id
deleteProcessInstancesBatchOperation
Tags
Process instance
deleteResource()
deleteResource(input, options?): CancelablePromise<DeleteResourceResponse>;
Delete resource
Deletes a deployed resource. This can be a process definition, decision requirements
definition, or form definition deployed using the deploy resources endpoint. Specify the
resource you want to delete in the resourceKey parameter.
Once a resource has been deleted it cannot be recovered. If the resource needs to be available again, a new deployment of the resource is required.
By default, only the resource itself is deleted from the runtime state. To also delete the
historic data associated with a resource, set the deleteHistory flag in the request body
to true. History deletion is supported for process definitions and decision requirements
definitions; for other resource types (forms, generic resources) the flag is ignored and no
history is deleted.
The two supported types differ in how the history is removed. For a decision requirements
definition the history is deleted asynchronously via a batch operation whose details are
returned in the batchOperation field of the response. For a process definition that still
exists in the runtime state, the definition first drains its running instances and its
history is deleted asynchronously once the definition is fully removed cluster-wide; no batch
operation is returned in the response. If the process definition has already been removed
from the runtime state and the deletion is later re-triggered with deleteHistory set to
true, a batch operation is created immediately and returned in the batchOperation field. *
Parameters
input
object & object
options?
Returns
CancelablePromise<DeleteResourceResponse>
Example
Delete a resource
async function deleteResourceExample(resourceKey: ProcessDefinitionKey) {
const camunda = createCamundaClient();
// Use a process definition key as a resource key for deletion
await camunda.deleteResource({
resourceKey,
});
}
Operation Id
deleteResource
Tags
Resource
deleteRole()
deleteRole(input, options?): CancelablePromise<void>;
Delete role
Deletes the role with the given ID. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Delete a role
async function deleteRoleExample(roleId: RoleId) {
const camunda = createCamundaClient();
await camunda.deleteRole({ roleId });
}
Operation Id
deleteRole
Tags
Role
deleteRuntimeBackup()
deleteRuntimeBackup(input, options?): CancelablePromise<void>;
Delete runtime backup
Deletes the runtime backup with the given id. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Delete a runtime backup
async function deleteRuntimeBackupExample() {
const camunda = createCamundaClient();
await camunda.deleteRuntimeBackup({ backupId: 100 });
}
Operation Id
deleteRuntimeBackup
Tags
Backup
deleteRuntimeBackupAsClusterAdmin()
deleteRuntimeBackupAsClusterAdmin(input, options?): CancelablePromise<void>;
Delete a runtime backup across physical tenants
Deletes the runtime backup with the given id from every physical tenant of the cluster, or from the one named by physicalTenantId. A tenant that does not hold the backup has already reached the requested end state, so it counts as deleted rather than as a failure — the same as deleting an unknown backup id through the per-physical-tenant endpoint.
The request is all-or-nothing: a physical tenant the backup cannot be deleted from fails the whole request, and the deletions that already succeeded on other tenants are not undone. Narrow the request with physicalTenantId to delete from the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use DELETE /v2/backups/runtime/{backupId} to act as a single physical tenant. *
Parameters
input
deleteRuntimeBackupAsClusterAdminInput
options?
Returns
CancelablePromise<void>
Example
Delete a runtime backup (cluster admin)
async function deleteRuntimeBackupAsClusterAdminExample() {
const camunda = createCamundaClient();
// Deletion fans out to every physical tenant (or a single one when
// `physicalTenantId` is given) and is not undone if a later tenant fails.
await camunda.deleteRuntimeBackupAsClusterAdmin({ backupId: 100 });
}
Operation Id
deleteRuntimeBackupAsClusterAdmin
Tags
Backup
deleteRuntimeBackupState()
deleteRuntimeBackupState(options?): CancelablePromise<void>;
Delete runtime backup state
Resets the runtime backup state of every partition of the physical tenant, clearing all checkpoint info, backup info, checkpoint metadata, and backup ranges. Used when switching backup stores.
Parameters
options?
Returns
CancelablePromise<void>
Example
Delete the runtime backup state
async 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();
}
Operation Id
deleteRuntimeBackupState
Tags
Backup
deleteRuntimeBackupStateAsClusterAdmin()
deleteRuntimeBackupStateAsClusterAdmin(input, options?): CancelablePromise<void>;
Delete runtime backup state across physical tenants
Resets the runtime backup state of every partition of every physical tenant of the cluster, or of the one named by physicalTenantId, clearing all checkpoint info, backup info, checkpoint metadata, and backup ranges. Used when switching backup stores.
The request is all-or-nothing: a physical tenant whose state cannot be reset fails the whole request, and the resets that already succeeded on other tenants are not undone. Narrow the request with physicalTenantId to reset the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use DELETE /v2/backups/runtime/state to act as a single physical tenant. *
Parameters
input
deleteRuntimeBackupStateAsClusterAdminInput
options?
Returns
CancelablePromise<void>
Example
Delete the runtime backup state (cluster admin)
async function deleteRuntimeBackupStateAsClusterAdminExample() {
const camunda = createCamundaClient();
// Clears all checkpoint info, backup info, checkpoint metadata, and backup
// ranges on every partition of every targeted physical tenant (or a single one
// when `physicalTenantId` is given). Used when switching backup stores.
await camunda.deleteRuntimeBackupStateAsClusterAdmin({});
}
Operation Id
deleteRuntimeBackupStateAsClusterAdmin
Tags
Backup
deleteTenant()
deleteTenant(input, options?): CancelablePromise<void>;
Delete tenant
Deletes an existing tenant. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Delete a tenant
async function deleteTenantExample(tenantId: TenantId) {
const camunda = createCamundaClient();
await camunda.deleteTenant({ tenantId });
}
Operation Id
deleteTenant
Tags
Tenant
deleteTenantClusterVariable()
deleteTenantClusterVariable(input, options?): CancelablePromise<void>;
Delete a tenant-scoped cluster variable
Delete a tenant-scoped cluster variable. *
Parameters
input
deleteTenantClusterVariableInput
options?
Returns
CancelablePromise<void>
Example
Delete a tenant cluster variable
async function deleteTenantClusterVariableExample(
tenantId: TenantId,
name: ClusterVariableName
) {
const camunda = createCamundaClient();
await camunda.deleteTenantClusterVariable({
tenantId,
name,
});
}
Operation Id
deleteTenantClusterVariable
Tags
Cluster Variable
deleteUser()
deleteUser(input, options?): CancelablePromise<void>;
Delete user
Deletes a user. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Delete a user
async function deleteUserExample(username: Username) {
const camunda = createCamundaClient();
await camunda.deleteUser({ username });
}
Operation Id
deleteUser
Tags
User
deployResourcesFromFiles()
deployResourcesFromFiles(resourceFilenames, options?): CancelablePromise<ExtendedDeploymentResult>;
Node-only convenience: deploy resources from local filesystem paths.
Parameters
resourceFilenames
string[]
Absolute or relative file paths to BPMN/DMN/form/resource files.
options?
Optional: tenantId.
tenantId?
string
Returns
CancelablePromise<ExtendedDeploymentResult>
ExtendedDeploymentResult
emitSupportLogPreamble()
emitSupportLogPreamble(): void;
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.
Returns
void
evaluateConditionals()
evaluateConditionals(input, options?): CancelablePromise<EvaluateConditionalResult>;
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.
Parameters
input
ConditionalEvaluationInstruction
options?
Returns
CancelablePromise<EvaluateConditionalResult>
Example
Evaluate conditionals
async function evaluateConditionalsExample(tenantId: TenantId) {
const camunda = createCamundaClient();
const result = await camunda.evaluateConditionals({
variables: { orderReady: true },
tenantId,
});
console.log(`Evaluated conditionals: ${JSON.stringify(result)}`);
}
Operation Id
evaluateConditionals
Tags
Conditional
evaluateDecision()
evaluateDecision(input, options?): CancelablePromise<EvaluateDecisionResult>;
Evaluate 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.
Parameters
input
| DecisionEvaluationById
| DecisionEvaluationByKey
options?
Returns
CancelablePromise<EvaluateDecisionResult>
Examples
By ID
async 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}`);
}
By key
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}`);
}
Operation Id
evaluateDecision
Tags
Decision definition
evaluateExpression()
evaluateExpression(input, options?): CancelablePromise<ExpressionEvaluationResult>;
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.
Parameters
input
options?
Returns
CancelablePromise<ExpressionEvaluationResult>
Example
Evaluate an expression
async function evaluateExpressionExample() {
const camunda = createCamundaClient();
const result = await camunda.evaluateExpression({
expression: "= x + y",
variables: { x: 10, y: 20 },
});
console.log(`Result: ${result.result}`);
}
Operation Id
evaluateExpression
Tags
Expression
failJob()
failJob(input, options?): CancelablePromise<void>;
Fail job
Mark the job as failed.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Fail a job with retry
async function failJobExample(jobKey: JobKey) {
const camunda = createCamundaClient();
await camunda.failJob({
jobKey,
retries: 2,
errorMessage: "Payment gateway timeout",
retryBackOff: 5000,
});
}
Operation Id
failJob
Tags
Job
forceAuthRefresh()
forceAuthRefresh(): Promise<string | undefined>;
Returns
Promise<string | undefined>
getAgentDefinition()
getAgentDefinition(
input,
consistencyManagement,
options?
): CancelablePromise<AgentDefinitionResult>;
Get agent definition
Returns an agent definition by key. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<AgentDefinitionResult>
Example
Get an agent definition
async function getAgentDefinitionExample(
agentDefinitionKey: AgentDefinitionKey
) {
const camunda = createCamundaClient();
const definition = await camunda.getAgentDefinition(
{ agentDefinitionKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Name: ${definition.name}`);
console.log(`Type: ${definition.agentType}`);
console.log(`Element: ${definition.elementId}`);
}
Operation Id
getAgentDefinition
Tags
Agent definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getAgentInstance()
getAgentInstance(
input,
consistencyManagement,
options?
): CancelablePromise<AgentInstanceResult>;
Get agent instance
Returns agent instance as JSON. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<AgentInstanceResult>
Example
Get an agent instance
async 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}`);
}
Operation Id
getAgentInstance
Tags
Agent instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getAuditLog()
getAuditLog(
input,
consistencyManagement,
options?
): CancelablePromise<AuditLogResult>;
Get audit log
Get an audit log entry by auditLogKey. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<AuditLogResult>
Example
Get an audit log entry
async function getAuditLogExample(auditLogKey: AuditLogKey) {
const camunda = createCamundaClient();
const log = await camunda.getAuditLog(
{ auditLogKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Audit log: ${log.operationType}`);
}
Operation Id
getAuditLog
Tags
Audit Log
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getAuthentication()
getAuthentication(options?): CancelablePromise<CamundaUserResult>;
Get current user
Retrieves the current authenticated user. *
Parameters
options?
Returns
CancelablePromise<CamundaUserResult>
Example
Get authentication info
async function getAuthenticationExample() {
const camunda = createCamundaClient();
const user = await camunda.getAuthentication();
console.log(`Authenticated as: ${user.username}`);
}
Operation Id
getAuthentication
Tags
Authentication
getAuthHeaders()
getAuthHeaders(): Promise<Record<string, string>>;
Returns
Promise<Record<string, string>>
getAuthorization()
getAuthorization(
input,
consistencyManagement,
options?
): CancelablePromise<AuthorizationResult>;
Get authorization
Get authorization by the given key. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<AuthorizationResult>
Example
Get an authorization
async function getAuthorizationExample(authorizationKey: AuthorizationKey) {
const camunda = createCamundaClient();
const authorization = await camunda.getAuthorization(
{ authorizationKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Owner: ${authorization.ownerId} (${authorization.ownerType})`);
}
Operation Id
getAuthorization
Tags
Authorization
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getBackpressureState()
getBackpressureState():
| {
backoffMs: number;
consecutive: number;
permitsCurrent: number;
permitsMax: number | null;
severity: BackpressureSeverity;
waiters: number;
}
| {
consecutive: number;
permitsCurrent: number;
permitsMax: null;
severity: string;
waiters: number;
};
Public accessor for current backpressure adaptive limiter state (stable)
Returns
| {
backoffMs: number;
consecutive: number;
permitsCurrent: number;
permitsMax: number | null;
severity: BackpressureSeverity;
waiters: number;
}
| {
consecutive: number;
permitsCurrent: number;
permitsMax: null;
severity: string;
waiters: number;
}
getBatchOperation()
getBatchOperation(
input,
consistencyManagement,
options?
): CancelablePromise<BatchOperationResponse>;
Get batch operation
Get batch operation by key. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<BatchOperationResponse>
Example
Get a batch operation
async function getBatchOperationExample(batchOperationKey: BatchOperationKey) {
const camunda = createCamundaClient();
const batch = await camunda.getBatchOperation(
{ batchOperationKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Batch: ${batch.batchOperationType} (${batch.state})`);
}
Operation Id
getBatchOperation
Tags
Batch operation
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getClusterExportingStatus()
getClusterExportingStatus(options?): CancelablePromise<ExportingStatusResponse>;
Get exporting status of the whole cluster
Returns the exporting status of the whole cluster, folded over the exporting status of every physical tenant. Only PAUSED and SOFT_PAUSED confirm that exporting is paused cluster-wide; every other value means at least one physical tenant is not paused, so callers should keep polling. A physical tenant that itself reports MIXED makes the whole cluster MIXED.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. *
Parameters
options?
Returns
CancelablePromise<ExportingStatusResponse>
Example
Get cluster exporting status
async function getClusterExportingStatusExample() {
const camunda = createCamundaClient();
// Reports the aggregated exporting status of the whole cluster — useful to
// confirm exporting has paused everywhere before taking a cluster-wide backup.
const { status } = await camunda.getClusterExportingStatus();
console.log(`Cluster exporting status: ${status}`);
}
Operation Id
getClusterExportingStatus
Tags
Exporting
getClusterRebalance()
getClusterRebalance(options?): CancelablePromise<ClusterBalanceResponse>;
Report the cluster's current leadership balance
Reports whether the cluster is currently balanced, the current leadership state of every partition, and what became of the last rebalance to finish. The last completed rebalance is held in memory by the coordinating broker, so none will be reported if the coordinator has moved or restarted since the last rebalance.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. *
Parameters
options?
Returns
CancelablePromise<ClusterBalanceResponse>
Example
Get cluster rebalance status
async function getClusterRebalanceExample() {
const camunda = createCamundaClient();
const balance = await camunda.getClusterRebalance();
console.log(`Cluster balance state: ${balance.state}`);
for (const partition of balance.partitions) {
console.log(
` Partition ${partition.partitionId}: state=${partition.state}, currentLeader=${partition.currentLeader}, desiredLeader=${partition.desiredLeader}`
);
}
if (balance.runningRebalance) {
console.log(`Running rebalance id=${balance.runningRebalance.rebalanceId}`);
}
}
Operation Id
getClusterRebalance
Tags
Cluster
getClusterStatus()
getClusterStatus(options?): CancelablePromise<ClusterStatusResponse>;
Get the status of the whole cluster
Checks the health status of the whole cluster, aggregated over all physical tenants. Returns HEALTHY when every physical tenant is healthy, DOWN when no physical tenant can process work, and DEGRADED in every other case. No per-tenant detail is reported; use GET /cluster/v2/topology for that.
This endpoint is public and requires no authentication, unlike PATCH /cluster/v2/mode below, which needs cluster-admin credentials. *
Parameters
options?
Returns
CancelablePromise<ClusterStatusResponse>
Example
Get cluster status
async function getClusterStatusExample() {
const camunda = createCamundaClient();
const status = await camunda.getClusterStatus();
console.log(`Cluster status: ${status.status}`);
}
Operation Id
getClusterStatus
Tags
Cluster
getClusterTopology()
getClusterTopology(options?): CancelablePromise<ClusterTopologyResponse>;
Get the topology of the whole cluster
Obtains the topology of the whole cluster, aggregated over all physical tenants. Cluster-level information is reported once; partition layout, replication and per-partition role, health and state are reported per physical tenant.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use GET /v2/topology for the topology of a single physical tenant. *
Parameters
options?
Returns
CancelablePromise<ClusterTopologyResponse>
Example
Get cluster topology (v2)
async function getClusterTopologyExample() {
const camunda = createCamundaClient();
// Returns the full cluster topology: brokers, physical tenants (in a
// multi-tenant cluster), cluster size, and gateway version.
const topology = await camunda.getClusterTopology();
console.log(
`Cluster ${topology.clusterId} — ${topology.clusterSize} broker(s), gateway ${topology.gatewayVersion}`
);
for (const broker of topology.brokers) {
console.log(
` Broker ${broker.brokerId}: ${broker.host}:${broker.port} (${broker.version})`
);
}
for (const tenant of topology.physicalTenants) {
console.log(
` Physical tenant ${tenant.physicalTenantId}: ${tenant.partitionsCount} partition(s), replication ${tenant.replicationFactor}`
);
}
}
Operation Id
getClusterTopology
Tags
Cluster
getClusterUpgradeStatus()
getClusterUpgradeStatus(options?): CancelablePromise<ClusterUpgradeStatusResponse>;
Get the upgrade-readiness status of the whole cluster
Reports one overall upgrade-readiness status for the whole cluster, folded over every physical tenant and condition. MIGRATED only once every known condition has migrated for every known physical tenant; MIGRATION_IN_PROGRESS when at least one is confirmed not yet migrated; UNKNOWN otherwise (including before anything has been reported yet). No per-tenant or per-condition detail is reported here; see the upgradeReadiness actuator endpoint for that. *
Parameters
options?
Returns
CancelablePromise<ClusterUpgradeStatusResponse>
Example
Get cluster upgrade-readiness status
async function getClusterUpgradeStatusExample() {
const camunda = createCamundaClient();
const upgradeStatus = await camunda.getClusterUpgradeStatus();
console.log(`Cluster upgrade-readiness status: ${upgradeStatus.status}`);
}
Operation Id
getClusterUpgradeStatus
Tags
Cluster
getConfig()
getConfig(): Readonly<CamundaConfig>;
Read-only snapshot of current hydrated configuration (do not mutate directly). Use configure(...) to apply changes.
Returns
Readonly<CamundaConfig>
getDecisionDefinition()
getDecisionDefinition(
input,
consistencyManagement,
options?
): CancelablePromise<DecisionDefinitionResult>;
Get decision definition
Returns a decision definition by key. *
Parameters
input
consistencyManagement
getDecisionDefinitionConsistency
options?
Returns
CancelablePromise<DecisionDefinitionResult>
Example
Get a decision definition
async 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}`);
}
Operation Id
getDecisionDefinition
Tags
Decision definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getDecisionDefinitionXml()
getDecisionDefinitionXml(
input,
consistencyManagement,
options?
): CancelablePromise<string>;
Get decision definition XML
Returns decision definition as XML. *
Parameters
input
consistencyManagement
getDecisionDefinitionXmlConsistency
options?
Returns
CancelablePromise<string>
Example
Get decision definition XML
async function getDecisionDefinitionXmlExample(
decisionDefinitionKey: DecisionDefinitionKey
) {
const camunda = createCamundaClient();
const xml = await camunda.getDecisionDefinitionXml(
{ decisionDefinitionKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`XML length: ${JSON.stringify(xml).length}`);
}
Operation Id
getDecisionDefinitionXML
Tags
Decision definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getDecisionInstance()
getDecisionInstance(
input,
consistencyManagement,
options?
): CancelablePromise<DecisionInstanceGetQueryResult>;
Get decision instance
Returns a decision instance. *
Parameters
input
consistencyManagement
getDecisionInstanceConsistency
options?
Returns
CancelablePromise<DecisionInstanceGetQueryResult>
Example
Get a decision instance
async function getDecisionInstanceExample(
decisionEvaluationInstanceKey: DecisionEvaluationInstanceKey
) {
const camunda = createCamundaClient();
const instance = await camunda.getDecisionInstance(
{ decisionEvaluationInstanceKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Decision: ${instance.decisionDefinitionId}`);
}
Operation Id
getDecisionInstance
Tags
Decision instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getDecisionRequirements()
getDecisionRequirements(
input,
consistencyManagement,
options?
): CancelablePromise<DecisionRequirementsResult>;
Get decision requirements
Returns Decision Requirements as JSON. *
Parameters
input
consistencyManagement
getDecisionRequirementsConsistency
options?
Returns
CancelablePromise<DecisionRequirementsResult>
Example
Get decision requirements
async function getDecisionRequirementsExample(
decisionRequirementsKey: DecisionRequirementsKey
) {
const camunda = createCamundaClient();
const requirements = await camunda.getDecisionRequirements(
{ decisionRequirementsKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Requirements: ${requirements.decisionRequirementsId}`);
}
Operation Id
getDecisionRequirements
Tags
Decision requirements
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getDecisionRequirementsXml()
getDecisionRequirementsXml(
input,
consistencyManagement,
options?
): CancelablePromise<string>;
Get decision requirements XML
Returns decision requirements as XML. *
Parameters
input
getDecisionRequirementsXmlInput
consistencyManagement
getDecisionRequirementsXmlConsistency
options?
Returns
CancelablePromise<string>
Example
Get decision requirements XML
async function getDecisionRequirementsXmlExample(
decisionRequirementsKey: DecisionRequirementsKey
) {
const camunda = createCamundaClient();
const xml = await camunda.getDecisionRequirementsXml(
{ decisionRequirementsKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`XML length: ${JSON.stringify(xml).length}`);
}
Operation Id
getDecisionRequirementsXML
Tags
Decision requirements
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getDocument()
getDocument(input, options?): CancelablePromise<Blob>;
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)
Parameters
input
options?
Returns
CancelablePromise<Blob>
Example
Download a document
async function getDocumentExample(documentId: DocumentId) {
const camunda = createCamundaClient();
await camunda.getDocument({ documentId });
console.log(`Downloaded document: ${documentId}`);
}
Operation Id
getDocument
Tags
Document
getElementInstance()
getElementInstance(
input,
consistencyManagement,
options?
): CancelablePromise<ElementInstanceResult>;
Get element instance
Returns element instance as JSON. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<ElementInstanceResult>
Example
Get an element instance
async function getElementInstanceExample(
elementInstanceKey: ElementInstanceKey
) {
const camunda = createCamundaClient();
const element = await camunda.getElementInstance(
{ elementInstanceKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Element: ${element.elementId} (${element.type})`);
}
Operation Id
getElementInstance
Tags
Element instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getErrorMode()
getErrorMode(): "throw" | "result";
Internal accessor (read-only) for eventual consistency error mode.
Returns
"throw" | "result"
getExportingStatus()
getExportingStatus(options?): CancelablePromise<ExportingStatusResponse>;
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.
Parameters
options?
Returns
CancelablePromise<ExportingStatusResponse>
Example
Get exporting status
async 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}`);
}
Operation Id
getExportingStatus
Tags
Exporting
getFormByKey()
getFormByKey(
input,
consistencyManagement,
options?
): CancelablePromise<FormResult>;
Get form by key
Get a form by its unique form key.
Parameters
input
consistencyManagement
options?
Returns
Example
Get a form by key
async function getFormByKeyExample(formKey: FormKey) {
const camunda = createCamundaClient();
const form = await camunda.getFormByKey(
{
formKey,
},
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Form: ${form.formId}, version: ${form.version}`);
}
Operation Id
getFormByKey
Tags
Form
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getGlobalClusterVariable()
getGlobalClusterVariable(
input,
consistencyManagement,
options?
): CancelablePromise<ClusterVariableResult>;
Get a global-scoped cluster variable
Get a global-scoped cluster variable. *
Parameters
input
consistencyManagement
getGlobalClusterVariableConsistency
options?
Returns
CancelablePromise<ClusterVariableResult>
Example
Get a global cluster variable
async function getGlobalClusterVariableExample(name: ClusterVariableName) {
const camunda = createCamundaClient();
const variable = await camunda.getGlobalClusterVariable(
{ name },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`${variable.name} = ${variable.value}`);
}
Operation Id
getGlobalClusterVariable
Tags
Cluster Variable
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getGlobalJobStatistics()
getGlobalJobStatistics(
input,
consistencyManagement,
options?
): CancelablePromise<GlobalJobStatisticsQueryResult>;
Global job statistics
Returns global aggregated counts for jobs. Filter by the creation time window (required) and optionally by jobType.
Parameters
input
consistencyManagement
getGlobalJobStatisticsConsistency
options?
Returns
CancelablePromise<GlobalJobStatisticsQueryResult>
Example
Get global job statistics
async 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)}`);
}
Operation Id
getGlobalJobStatistics
Tags
Job
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getGlobalTaskListener()
getGlobalTaskListener(
input,
consistencyManagement,
options?
): CancelablePromise<GlobalTaskListenerResult>;
Get global user task listener
Get a global user task listener by its id. *
Parameters
input
consistencyManagement
getGlobalTaskListenerConsistency
options?
Returns
CancelablePromise<GlobalTaskListenerResult>
Example
Get a global task listener
async function getGlobalTaskListenerExample(id: GlobalListenerId) {
const camunda = createCamundaClient();
const listener = await camunda.getGlobalTaskListener(
{ id },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Listener: ${listener.type} (${listener.eventTypes})`);
}
Operation Id
getGlobalTaskListener
Tags
Global listener
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getGroup()
getGroup(
input,
consistencyManagement,
options?
): CancelablePromise<GroupResult>;
Get group
Get a group by its ID. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<GroupResult>
Example
Get a group
async function getGroupExample(groupId: GroupId) {
const camunda = createCamundaClient();
const group = await camunda.getGroup(
{ groupId },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Group: ${group.name}`);
}
Operation Id
getGroup
Tags
Group
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getHistoryBackup()
getHistoryBackup(input, options?): CancelablePromise<HistoryBackupInfo>;
Get history backup
Returns detailed status of the history backup with the given id.
Only available on clusters whose secondary storage is Elasticsearch or OpenSearch.
Parameters
input
options?
Returns
CancelablePromise<HistoryBackupInfo>
Example
Get a history backup
async function getHistoryBackupExample() {
const camunda = createCamundaClient();
const backup = await camunda.getHistoryBackup({ backupId: 100 });
// The aggregated state is derived from the state of every expected snapshot.
console.log(`History backup ${backup.backupId}: ${backup.state}`);
}
Operation Id
getHistoryBackup
Tags
Backup
getHistoryBackupAsClusterAdmin()
getHistoryBackupAsClusterAdmin(input, options?): CancelablePromise<ClusterHistoryBackupInfo>;
Get a history backup across physical tenants
Reports what every physical tenant of the cluster, or the one named by physicalTenantId, holds for the given backup id. There is no aggregated cluster-level state: a tenant that was reached and does not hold this backup reports NOT_FOUND, which is a successful observation rather than a failure.
The request is all-or-nothing: a physical tenant whose state cannot be read fails the whole request. Narrow the request with physicalTenantId to read the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Only available on clusters whose secondary storage is Elasticsearch or OpenSearch. Use GET /v2/backups/history/{backupId} to act as a single physical tenant. *
Parameters
input
getHistoryBackupAsClusterAdminInput
options?
Returns
CancelablePromise<ClusterHistoryBackupInfo>
Example
Get a history backup (cluster admin)
async function getHistoryBackupAsClusterAdminExample() {
const camunda = createCamundaClient();
// Looking a backup id up directly lists every targeted physical tenant,
// including the ones reporting `NOT_FOUND` — a backup that only some tenants
// hold is a supported outcome.
const backup = await camunda.getHistoryBackupAsClusterAdmin({
backupId: 100,
});
console.log(`Cluster history backup ${backup.backupId}:`);
for (const tenant of backup.physicalTenants) {
console.log(` [${tenant.physicalTenantId}] ${tenant.state}`);
}
}
Operation Id
getHistoryBackupAsClusterAdmin
Tags
Backup
getIncident()
getIncident(
input,
consistencyManagement,
options?
): CancelablePromise<IncidentResult>;
Get incident
Returns incident as JSON.
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<IncidentResult>
Example
Get an incident
async 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}`);
}
Operation Id
getIncident
Tags
Incident
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getJobErrorStatistics()
getJobErrorStatistics(
input,
consistencyManagement,
options?
): CancelablePromise<JobErrorStatisticsQueryResult>;
Get error metrics for a job type
Returns aggregated metrics per error for the given jobType.
Parameters
input
consistencyManagement
getJobErrorStatisticsConsistency
options?
Returns
CancelablePromise<JobErrorStatisticsQueryResult>
Example
Get job error statistics
async 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}`);
}
}
Operation Id
getJobErrorStatistics
Tags
Job
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getJobTimeSeriesStatistics()
getJobTimeSeriesStatistics(
input,
consistencyManagement,
options?
): CancelablePromise<JobTimeSeriesStatisticsQueryResult>;
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.
Parameters
input
consistencyManagement
getJobTimeSeriesStatisticsConsistency
options?
Returns
CancelablePromise<JobTimeSeriesStatisticsQueryResult>
Example
Get job time series statistics
async 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}`);
}
}
Operation Id
getJobTimeSeriesStatistics
Tags
Job
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getJobTypeStatistics()
getJobTypeStatistics(
input,
consistencyManagement,
options?
): CancelablePromise<JobTypeStatisticsQueryResult>;
Get job statistics by type
Get statistics about jobs, grouped by job type.
Parameters
input
consistencyManagement
getJobTypeStatisticsConsistency
options?
Returns
CancelablePromise<JobTypeStatisticsQueryResult>
Example
Get job type statistics
async 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}`);
}
}
Operation Id
getJobTypeStatistics
Tags
Job
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getJobWorkerStatistics()
getJobWorkerStatistics(
input,
consistencyManagement,
options?
): CancelablePromise<JobWorkerStatisticsQueryResult>;
Get job statistics by worker
Get statistics about jobs, grouped by worker, for a given job type.
Parameters
input
consistencyManagement
getJobWorkerStatisticsConsistency
options?
Returns
CancelablePromise<JobWorkerStatisticsQueryResult>
Example
Get job worker statistics
async 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}`);
}
}
Operation Id
getJobWorkerStatistics
Tags
Job
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getLicense()
getLicense(options?): CancelablePromise<LicenseResponse>;
Get license status
Obtains the status of the current Camunda license. *
Parameters
options?
Returns
CancelablePromise<LicenseResponse>
Example
Get license information
async function getLicenseExample() {
const camunda = createCamundaClient();
const license = await camunda.getLicense();
console.log(`License type: ${license.validLicense}`);
}
Operation Id
getLicense
Tags
License
getMappingRule()
getMappingRule(
input,
consistencyManagement,
options?
): CancelablePromise<MappingRuleResult>;
Get a mapping rule
Gets the mapping rule with the given ID.
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<MappingRuleResult>
Example
Get a mapping rule
async 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})`);
}
Operation Id
getMappingRule
Tags
Mapping rule
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getProcessDefinition()
getProcessDefinition(
input,
consistencyManagement,
options?
): CancelablePromise<ProcessDefinitionResult>;
Get process definition
Returns process definition as JSON. *
Parameters
input
consistencyManagement
getProcessDefinitionConsistency
options?
Returns
CancelablePromise<ProcessDefinitionResult>
Example
Get a process definition
async function getProcessDefinitionExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const definition = await camunda.getProcessDefinition(
{ processDefinitionKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(
`Process: ${definition.processDefinitionId} v${definition.version}`
);
}
Operation Id
getProcessDefinition
Tags
Process definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getProcessDefinitionInstanceStatistics()
getProcessDefinitionInstanceStatistics(
input,
consistencyManagement,
options?
): CancelablePromise<ProcessDefinitionInstanceStatisticsQueryResult>;
Get process instance statistics
Get statistics about process instances, grouped by process definition and tenant.
Parameters
input
ProcessDefinitionInstanceStatisticsQuery
consistencyManagement
getProcessDefinitionInstanceStatisticsConsistency
options?
Returns
CancelablePromise<ProcessDefinitionInstanceStatisticsQueryResult>
Example
Get process definition instance statistics
async 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`
);
}
}
Operation Id
getProcessDefinitionInstanceStatistics
Tags
Process definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getProcessDefinitionInstanceVersionStatistics()
getProcessDefinitionInstanceVersionStatistics(
input,
consistencyManagement,
options?
): CancelablePromise<ProcessDefinitionInstanceVersionStatisticsQueryResult>;
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.
Parameters
input
ProcessDefinitionInstanceVersionStatisticsQuery
consistencyManagement
getProcessDefinitionInstanceVersionStatisticsConsistency
options?
Returns
CancelablePromise<ProcessDefinitionInstanceVersionStatisticsQueryResult>
Example
Get version statistics
async 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`
);
}
}
Operation Id
getProcessDefinitionInstanceVersionStatistics
Tags
Process definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getProcessDefinitionMessageSubscriptionStatistics()
getProcessDefinitionMessageSubscriptionStatistics(
input,
consistencyManagement,
options?
): CancelablePromise<ProcessDefinitionMessageSubscriptionStatisticsQueryResult>;
Get message subscription statistics
Get message subscription statistics, grouped by process definition.
Parameters
input
ProcessDefinitionMessageSubscriptionStatisticsQuery
consistencyManagement
getProcessDefinitionMessageSubscriptionStatisticsConsistency
options?
Returns
CancelablePromise<ProcessDefinitionMessageSubscriptionStatisticsQueryResult>
Example
Get message subscription statistics
async 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`
);
}
}
Operation Id
getProcessDefinitionMessageSubscriptionStatistics
Tags
Process definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getProcessDefinitionStatistics()
getProcessDefinitionStatistics(
input,
consistencyManagement,
options?
): CancelablePromise<ProcessDefinitionElementStatisticsQueryResult>;
Get process definition statistics
Get statistics about elements in currently running process instances by process definition key and search filter. *
Parameters
input
getProcessDefinitionStatisticsInput
consistencyManagement
getProcessDefinitionStatisticsConsistency
options?
Returns
CancelablePromise<ProcessDefinitionElementStatisticsQueryResult>
Example
Get process definition element statistics
async 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}`);
}
}
Operation Id
getProcessDefinitionStatistics
Tags
Process definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getProcessDefinitionXml()
getProcessDefinitionXml(
input,
consistencyManagement,
options?
): CancelablePromise<string>;
Get process definition XML
Returns process definition as XML. *
Parameters
input
consistencyManagement
getProcessDefinitionXmlConsistency
options?
Returns
CancelablePromise<string>
Example
Get process definition XML
async function getProcessDefinitionXmlExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const xml = await camunda.getProcessDefinitionXml(
{ processDefinitionKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`XML length: ${JSON.stringify(xml).length}`);
}
Operation Id
getProcessDefinitionXML
Tags
Process definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getProcessInstance()
getProcessInstance(
input,
consistencyManagement,
options?
): CancelablePromise<ProcessInstanceResult>;
Get process instance
Get the process instance by the process instance key. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<ProcessInstanceResult>
Example
Get a process instance
async 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}`);
}
Operation Id
getProcessInstance
Tags
Process instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getProcessInstanceCallHierarchy()
getProcessInstanceCallHierarchy(
input,
consistencyManagement,
options?
): CancelablePromise<ProcessInstanceCallHierarchyEntry[]>;
Get call hierarchy
Returns the call hierarchy for a given process instance, showing its ancestry up to the root instance. *
Parameters
input
getProcessInstanceCallHierarchyInput
consistencyManagement
getProcessInstanceCallHierarchyConsistency
options?
Returns
CancelablePromise<ProcessInstanceCallHierarchyEntry[]>
Example
Get process instance call hierarchy
async function getProcessInstanceCallHierarchyExample(
processInstanceKey: ProcessInstanceKey
) {
const camunda = createCamundaClient();
const result = await camunda.getProcessInstanceCallHierarchy(
{ processInstanceKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Call hierarchy entries: ${result.length}`);
}
Operation Id
getProcessInstanceCallHierarchy
Tags
Process instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getProcessInstanceSequenceFlows()
getProcessInstanceSequenceFlows(
input,
consistencyManagement,
options?
): CancelablePromise<ProcessInstanceSequenceFlowsQueryResult>;
Get sequence flows
Get sequence flows taken by the process instance. *
Parameters
input
getProcessInstanceSequenceFlowsInput
consistencyManagement
getProcessInstanceSequenceFlowsConsistency
options?
Returns
CancelablePromise<ProcessInstanceSequenceFlowsQueryResult>
Example
Get process instance sequence flows
async 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}`);
}
}
Operation Id
getProcessInstanceSequenceFlows
Tags
Process instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getProcessInstanceStatistics()
getProcessInstanceStatistics(
input,
consistencyManagement,
options?
): CancelablePromise<ProcessInstanceElementStatisticsQueryResult>;
Get element instance statistics
Get statistics about elements by the process instance key. *
Parameters
input
getProcessInstanceStatisticsInput
consistencyManagement
getProcessInstanceStatisticsConsistency
options?
Returns
CancelablePromise<ProcessInstanceElementStatisticsQueryResult>
Example
Get process instance statistics
async 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}`);
}
}
Operation Id
getProcessInstanceStatistics
Tags
Process instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getProcessInstanceStatisticsByDefinition()
getProcessInstanceStatisticsByDefinition(
input,
consistencyManagement,
options?
): CancelablePromise<IncidentProcessInstanceStatisticsByDefinitionQueryResult>;
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.
Parameters
input
IncidentProcessInstanceStatisticsByDefinitionQuery
consistencyManagement
getProcessInstanceStatisticsByDefinitionConsistency
options?
Returns
CancelablePromise<IncidentProcessInstanceStatisticsByDefinitionQueryResult>
Example
Get instance statistics by definition
async 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`
);
}
}
Operation Id
getProcessInstanceStatisticsByDefinition
Tags
Incident
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getProcessInstanceStatisticsByError()
getProcessInstanceStatisticsByError(
input,
consistencyManagement,
options?
): CancelablePromise<IncidentProcessInstanceStatisticsByErrorQueryResult>;
Get process instance statistics by error
Returns statistics for active process instances that currently have active incidents, grouped by incident error hash code.
Parameters
input
IncidentProcessInstanceStatisticsByErrorQuery
consistencyManagement
getProcessInstanceStatisticsByErrorConsistency
options?
Returns
CancelablePromise<IncidentProcessInstanceStatisticsByErrorQueryResult>
Example
Get instance statistics by error
async 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}`
);
}
}
Operation Id
getProcessInstanceStatisticsByError
Tags
Incident
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getProcessInstanceWaitStateStatistics()
getProcessInstanceWaitStateStatistics(
input,
consistencyManagement,
options?
): CancelablePromise<ProcessInstanceWaitStateStatisticsQueryResult>;
Get wait state statistics
Get statistics about waiting element instances by the process instance key, grouped by element id. *
Parameters
input
getProcessInstanceWaitStateStatisticsInput
consistencyManagement
getProcessInstanceWaitStateStatisticsConsistency
options?
Returns
CancelablePromise<ProcessInstanceWaitStateStatisticsQueryResult>
Example
Get process instance wait state statistics
async 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}`);
}
}
Operation Id
getProcessInstanceWaitStateStatistics
Tags
Process instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getResource()
getResource(
input,
consistencyManagement,
options?
): CancelablePromise<ResourceResult>;
Get resource
Returns a deployed resource.
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.
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<ResourceResult>
Example
Get a resource
async function getResourceExample(resourceKey: ProcessDefinitionKey) {
const camunda = createCamundaClient();
const resource = await camunda.getResource(
{
resourceKey,
},
{ consistency: { waitUpToMs: 0 } }
);
console.log(`Resource: ${resource.resourceName} (${resource.resourceId})`);
}
Operation Id
getResource
Tags
Resource
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getResourceContent()
getResourceContent(
input,
consistencyManagement,
options?
): CancelablePromise<{
[key: string]: unknown;
}>;
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.
This endpoint only supports RPA resources. For generic resource content in binary format,
use the /resources/{resourceKey}/content/binary endpoint.
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<{
[key: string]: unknown;
}>
Deprecated
Example
Get resource content
async function getResourceContentExample(resourceKey: ProcessDefinitionKey) {
const camunda = createCamundaClient();
const content = await camunda.getResourceContent(
{
resourceKey,
},
{ consistency: { waitUpToMs: 0 } }
);
console.log(`Content retrieved (type: ${typeof content})`);
}
Operation Id
getResourceContent
Tags
Resource
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getResourceContentBinary()
getResourceContentBinary(
input,
consistencyManagement,
options?
): CancelablePromise<Blob>;
Get resource content as binary
Returns the content of a deployed resource in binary format (octet-stream).
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.
Parameters
input
consistencyManagement
getResourceContentBinaryConsistency
options?
Returns
CancelablePromise<Blob>
Example
Get resource content as binary
async function getResourceContentBinaryExample(
resourceKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const content = await camunda.getResourceContentBinary(
{
resourceKey,
},
{ consistency: { waitUpToMs: 0 } }
);
console.log(`Binary content retrieved (type: ${typeof content})`);
}
Operation Id
getResourceContentBinary
Tags
Resource
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getRestoreStatus()
getRestoreStatus(options?): CancelablePromise<RestoreStatusResponse>;
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. *
Parameters
options?
Returns
CancelablePromise<RestoreStatusResponse>
Example
Get restore status
async 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`
);
}
}
Operation Id
getRestoreStatus
Tags
Recovery
getRole()
getRole(
input,
consistencyManagement,
options?
): CancelablePromise<RoleResult>;
Get role
Get a role by its ID. *
Parameters
input
consistencyManagement
options?
Returns
Example
Get a role
async function getRoleExample(roleId: RoleId) {
const camunda = createCamundaClient();
const role = await camunda.getRole(
{ roleId },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Role: ${role.name}`);
}
Operation Id
getRole
Tags
Role
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getRuntimeBackup()
getRuntimeBackup(input, options?): CancelablePromise<BackupInfo>;
Get runtime backup
Returns detailed status of the runtime backup with the given id. *
Parameters
input
options?
Returns
Example
Get a runtime backup
async 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}`);
}
}
Operation Id
getRuntimeBackup
Tags
Backup
getRuntimeBackupAsClusterAdmin()
getRuntimeBackupAsClusterAdmin(input, options?): CancelablePromise<ClusterRuntimeBackupInfo>;
Get a runtime backup across physical tenants
Reports what every physical tenant of the cluster, or the one named by physicalTenantId, holds for the given backup id, plus the state aggregated over all of them. A tenant that was reached and does not hold this backup reports DOES_NOT_EXIST, which is a successful observation rather than a failure — so a backup only some tenants hold aggregates to INCOMPLETE, the same way a backup only some partitions hold does within one tenant.
The request is all-or-nothing: a physical tenant whose state cannot be read fails the whole request. Narrow the request with physicalTenantId to read the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use GET /v2/backups/runtime/{backupId} to act as a single physical tenant. *
Parameters
input
getRuntimeBackupAsClusterAdminInput
options?
Returns
CancelablePromise<ClusterRuntimeBackupInfo>
Example
Get a runtime backup (cluster admin)
async function getRuntimeBackupAsClusterAdminExample() {
const camunda = createCamundaClient();
// Looking a backup id up directly lists every targeted physical tenant,
// including the ones reporting `DOES_NOT_EXIST` — a backup that only some
// tenants hold is a supported outcome.
const backup = await camunda.getRuntimeBackupAsClusterAdmin({
backupId: 100,
});
console.log(`Cluster runtime backup ${backup.backupId}: ${backup.state}`);
for (const tenant of backup.physicalTenants) {
console.log(` [${tenant.physicalTenantId}] ${tenant.state}`);
}
}
Operation Id
getRuntimeBackupAsClusterAdmin
Tags
Backup
getRuntimeBackupState()
getRuntimeBackupState(options?): CancelablePromise<RuntimeBackupState>;
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.
Parameters
options?
Returns
CancelablePromise<RuntimeBackupState>
Example
Get the runtime backup state
async 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}`
);
}
}
Operation Id
getRuntimeBackupState
Tags
Backup
getRuntimeBackupStateAsClusterAdmin()
getRuntimeBackupStateAsClusterAdmin(input, options?): CancelablePromise<ClusterRuntimeBackupState>;
Get runtime backup state across physical tenants
Reports the checkpoint and backup state of every partition of every physical tenant of the cluster, or of the one named by physicalTenantId, grouped by physical tenant. Checkpoint ids and log positions only mean anything within one physical tenant's partitions, so nothing is aggregated across tenants.
The request is all-or-nothing: a physical tenant whose state cannot be read fails the whole request rather than contributing an empty section, which an operator making a delete or restore decision could not tell apart from "nothing to report yet". Narrow the request with physicalTenantId to read the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use GET /v2/backups/runtime/state to act as a single physical tenant. *
Parameters
input
getRuntimeBackupStateAsClusterAdminInput
options?
Returns
CancelablePromise<ClusterRuntimeBackupState>
Example
Get the runtime backup state (cluster admin)
async function getRuntimeBackupStateAsClusterAdminExample() {
const camunda = createCamundaClient();
// Returns the checkpoint and backup state of every targeted physical tenant.
// Nothing is aggregated across tenants — checkpoint ids and log positions only
// mean anything within one tenant's partitions.
const clusterState = await camunda.getRuntimeBackupStateAsClusterAdmin({});
for (const tenant of clusterState.physicalTenants) {
console.log(
`[${tenant.physicalTenantId}] ${tenant.state.checkpointStates.length} checkpoints`
);
}
}
Operation Id
getRuntimeBackupStateAsClusterAdmin
Tags
Backup
getStartProcessForm()
getStartProcessForm(
input,
consistencyManagement,
options?
): CancelablePromise<void | FormResult>;
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.
Parameters
input
consistencyManagement
getStartProcessFormConsistency
options?
Returns
CancelablePromise<void | FormResult>
Example
Get start process form
async function getStartProcessFormExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const form = await camunda.getStartProcessForm(
{ processDefinitionKey },
{ consistency: { waitUpToMs: 5000 } }
);
if (form) {
console.log(`Form key: ${form.formKey}`);
}
}
Operation Id
getStartProcessForm
Tags
Process definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getStatus()
getStatus(options?): CancelablePromise<void>;
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. *
Parameters
options?
Returns
CancelablePromise<void>
Example
Check cluster status
async function getStatusExample() {
const camunda = createCamundaClient();
await camunda.getStatus();
console.log("Cluster is healthy");
}
Operation Id
getStatus
Tags
Cluster
getSystemConfiguration()
getSystemConfiguration(options?): CancelablePromise<SystemConfigurationResponse>;
System 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.
Parameters
options?
Returns
CancelablePromise<SystemConfigurationResponse>
Example
Get system configuration
async function getSystemConfigurationExample() {
const camunda = createCamundaClient();
const config = await camunda.getSystemConfiguration();
console.log(`Configuration loaded: ${JSON.stringify(config)}`);
}
Operation Id
getSystemConfiguration
Tags
System
getTenant()
getTenant(
input,
consistencyManagement,
options?
): CancelablePromise<TenantResult>;
Get tenant
Retrieves a single tenant by tenant ID. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<TenantResult>
Example
Get a tenant
async function getTenantExample(tenantId: TenantId) {
const camunda = createCamundaClient();
const tenant = await camunda.getTenant(
{ tenantId },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Tenant: ${tenant.name}`);
}
Operation Id
getTenant
Tags
Tenant
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getTenantClusterVariable()
getTenantClusterVariable(
input,
consistencyManagement,
options?
): CancelablePromise<ClusterVariableResult>;
Get a tenant-scoped cluster variable
Get a tenant-scoped cluster variable. *
Parameters
input
consistencyManagement
getTenantClusterVariableConsistency
options?
Returns
CancelablePromise<ClusterVariableResult>
Example
Get a tenant cluster variable
async 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}`);
}
Operation Id
getTenantClusterVariable
Tags
Cluster Variable
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getTopology()
getTopology(options?): CancelablePromise<TopologyResponse>;
Get cluster topology
Obtains the current topology of the cluster the gateway is part of. *
Parameters
options?
Returns
CancelablePromise<TopologyResponse>
Example
Get cluster topology
async 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}`);
}
}
Operation Id
getTopology
Tags
Cluster
getUsageMetrics()
getUsageMetrics(
input,
consistencyManagement,
options?
): CancelablePromise<UsageMetricsResponse>;
Get usage metrics
Retrieve the usage metrics based on given criteria. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<UsageMetricsResponse>
Example
Get usage metrics
async 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)}`);
}
Operation Id
getUsageMetrics
Tags
System
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getUser()
getUser(
input,
consistencyManagement,
options?
): CancelablePromise<UserResult>;
Get user
Get a user by its username. *
Parameters
input
consistencyManagement
options?
Returns
Example
Get a user
async function getUserExample(username: Username) {
const camunda = createCamundaClient();
const user = await camunda.getUser(
{ username },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`User: ${user.name} (${user.email})`);
}
Operation Id
getUser
Tags
User
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getUserTask()
getUserTask(
input,
consistencyManagement,
options?
): CancelablePromise<UserTaskResult>;
Get user task
Get the user task by the user task key. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<UserTaskResult>
Example
Get a user task
async function getUserTaskExample(userTaskKey: UserTaskKey) {
const camunda = createCamundaClient();
const task = await camunda.getUserTask(
{ userTaskKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`Task: ${task.name} (${task.state})`);
}
Operation Id
getUserTask
Tags
User task
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getUserTaskForm()
getUserTaskForm(
input,
consistencyManagement,
options?
): CancelablePromise<void | FormResult>;
Get 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.
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<void | FormResult>
Example
Get a user task form
async function getUserTaskFormExample(userTaskKey: UserTaskKey) {
const camunda = createCamundaClient();
const form = await camunda.getUserTaskForm(
{ userTaskKey },
{ consistency: { waitUpToMs: 5000 } }
);
if (form) {
console.log(`Form key: ${form.formKey}`);
}
}
Operation Id
getUserTaskForm
Tags
User task
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getVariable()
getVariable(
input,
consistencyManagement,
options?
): CancelablePromise<VariableResult>;
Get 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. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<VariableResult>
Example
Get a variable
async function getVariableExample(variableKey: VariableKey) {
const camunda = createCamundaClient();
const variable = await camunda.getVariable(
{ variableKey },
{ consistency: { waitUpToMs: 5000 } }
);
console.log(`${variable.name} = ${variable.value}`);
}
Operation Id
getVariable
Tags
Variable
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
getWorkers()
getWorkers(): any[];
Return a read-only snapshot of currently registered job workers.
Returns
any[]
listHistoryBackups()
listHistoryBackups(input, options?): CancelablePromise<HistoryBackupInfo[]>;
List history backups
Returns a list of all available history backups of the physical tenant, with their state and additional info, most recent first by snapshot start time.
Only available on clusters whose secondary storage is Elasticsearch or OpenSearch.
Parameters
input
options?
Returns
CancelablePromise<HistoryBackupInfo[]>
Example
List history backups
async function listHistoryBackupsExample() {
const camunda = createCamundaClient();
// `prefix` must end in a single '*'. Omit it to list every history backup.
const backups = await camunda.listHistoryBackups({ prefix: "10*" });
for (const backup of backups) {
console.log(`History backup ${backup.backupId}: ${backup.state}`);
}
}
Operation Id
listHistoryBackups
Tags
Backup
listHistoryBackupsAsClusterAdmin()
listHistoryBackupsAsClusterAdmin(input, options?): CancelablePromise<ClusterHistoryBackupInfo[]>;
List history backups across physical tenants
Lists the history backups of every physical tenant of the cluster, or of the one named by physicalTenantId, grouped by backup id. A backup id that only some physical tenants hold is a supported outcome rather than a degraded one, so only the tenants that hold it are listed under it.
The request is all-or-nothing: a physical tenant whose backups cannot be read fails the whole request rather than silently dropping out of the listing. Narrow the request with physicalTenantId to list the backups of the tenants that can still be read.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Only available on clusters whose secondary storage is Elasticsearch or OpenSearch. Use GET /v2/backups/history to act as a single physical tenant. *
Parameters
input
listHistoryBackupsAsClusterAdminInput
options?
Returns
CancelablePromise<ClusterHistoryBackupInfo[]>
Example
List history backups (cluster admin)
async function listHistoryBackupsAsClusterAdminExample() {
const camunda = createCamundaClient();
// `prefix` must end in a single '*'. Omit `physicalTenantId` to span every
// physical tenant of the cluster — results are grouped by backup id, and each
// group lists only the tenants that hold that id.
const backups = await camunda.listHistoryBackupsAsClusterAdmin({
prefix: "10*",
});
for (const backup of backups) {
console.log(`Cluster history backup ${backup.backupId}:`);
for (const tenant of backup.physicalTenants) {
console.log(` [${tenant.physicalTenantId}] ${tenant.state}`);
}
}
}
Operation Id
listHistoryBackupsAsClusterAdmin
Tags
Backup
listRuntimeBackups()
listRuntimeBackups(input, options?): CancelablePromise<BackupInfo[]>;
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.
Parameters
input
options?
Returns
CancelablePromise<BackupInfo[]>
Example
List runtime backups
async 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}`);
}
}
Operation Id
listRuntimeBackups
Tags
Backup
listRuntimeBackupsAsClusterAdmin()
listRuntimeBackupsAsClusterAdmin(input, options?): CancelablePromise<ClusterRuntimeBackupInfo[]>;
List runtime backups across physical tenants
Lists the runtime backups of every physical tenant of the cluster, or of the one named by physicalTenantId, grouped by backup id. Every group reports every targeted tenant, including the ones holding nothing for that id, so a backup only some tenants hold aggregates to INCOMPLETE here exactly as it does when looked up directly — the state of a listed group can be trusted to say whether the cluster can be restored from it. A backup id that only some physical tenants hold is a supported outcome rather than a degraded one; tenants that generate their own backup ids never share one, so in that mode each backup forms its own group and the other tenants report DOES_NOT_EXIST under it.
The request is all-or-nothing: a physical tenant whose backups cannot be read fails the whole request rather than silently dropping out of the listing. Narrow the request with physicalTenantId to list the backups of the tenants that can still be read.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use GET /v2/backups/runtime to act as a single physical tenant. *
Parameters
input
listRuntimeBackupsAsClusterAdminInput
options?
Returns
CancelablePromise<ClusterRuntimeBackupInfo[]>
Example
List runtime backups (cluster admin)
async function listRuntimeBackupsAsClusterAdminExample() {
const camunda = createCamundaClient();
// `prefix` must end in a single '*'. Omit `physicalTenantId` to span every
// physical tenant — results are grouped by backup id, and each group reports
// every targeted tenant, including ones holding nothing for that id (reported
// as `DOES_NOT_EXIST`).
const backups = await camunda.listRuntimeBackupsAsClusterAdmin({
prefix: "10*",
});
for (const backup of backups) {
console.log(`Cluster runtime backup ${backup.backupId}: ${backup.state}`);
for (const tenant of backup.physicalTenants) {
console.log(` [${tenant.physicalTenantId}] ${tenant.state}`);
}
}
}
Operation Id
listRuntimeBackupsAsClusterAdmin
Tags
Backup
listSecrets()
listSecrets(input, options?): CancelablePromise<SecretListResult>;
List secrets
List the camunda.secrets.* references known for the caller's physical tenant.
Only references the caller holds SECRET:READ on are returned. This endpoint never
returns secret values, only the reference names.
The references are read from the secret stores configured for the caller's physical tenant.
A store may hold names outside the reference name charset (for example one containing a
dot); those are omitted, since /secrets/resolve would reject them and no permission can
be granted on them.
A returned reference is usable verbatim with /secrets/resolve. In a FEEL expression,
however, a name that is not a bare identifier has to be backtick-escaped, since FEEL reads
a bare dash as the minus operator: a listed camunda.secrets.db-password is written
=camunda.secrets.`db-password` in a BPMN input mapping.
Parameters
input
options?
Returns
CancelablePromise<SecretListResult>
Example
List secret references
async 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}`);
}
}
Operation Id
listSecrets
Tags
Secret
logger()
logger(scope?): Logger;
Access a scoped logger (internal & future user emission).
Parameters
scope?
string
Returns
migrateProcessInstance()
migrateProcessInstance(input, options?): CancelablePromise<void>;
Migrate 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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Migrate a process instance
async function migrateProcessInstanceExample(
processInstanceKey: ProcessInstanceKey,
targetProcessDefinitionKey: ProcessDefinitionKey,
sourceElementId: ElementId,
targetElementId: ElementId
) {
const camunda = createCamundaClient();
await camunda.migrateProcessInstance({
processInstanceKey,
targetProcessDefinitionKey,
mappingInstructions: [
{
sourceElementId,
targetElementId,
},
],
});
}
Operation Id
migrateProcessInstance
Tags
Process instance
migrateProcessInstancesBatchOperation()
migrateProcessInstancesBatchOperation(input, options?): CancelablePromise<BatchOperationCreatedResult>;
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}).
Parameters
input
ProcessInstanceMigrationBatchOperationRequest
options?
Returns
CancelablePromise<BatchOperationCreatedResult>
Example
Migrate process instances in batch
async 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}`);
}
Operation Id
migrateProcessInstancesBatchOperation
Tags
Process instance
modifyProcessInstance()
modifyProcessInstance(input, options?): CancelablePromise<void>;
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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Modify a process instance
async function modifyProcessInstanceExample(
processInstanceKey: ProcessInstanceKey,
elementId: ElementId,
elementInstanceKey: ElementInstanceKey
) {
const camunda = createCamundaClient();
await camunda.modifyProcessInstance({
processInstanceKey,
activateInstructions: [{ elementId }],
terminateInstructions: [{ elementInstanceKey }],
});
}
Operation Id
modifyProcessInstance
Tags
Process instance
modifyProcessInstancesBatchOperation()
modifyProcessInstancesBatchOperation(input, options?): CancelablePromise<BatchOperationCreatedResult>;
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}).
Parameters
input
ProcessInstanceModificationBatchOperationRequest
options?
Returns
CancelablePromise<BatchOperationCreatedResult>
Example
Modify process instances in batch
async 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}`);
}
Operation Id
modifyProcessInstancesBatchOperation
Tags
Process instance
onAuthHeaders()
onAuthHeaders(h): void;
Parameters
h
(headers) =>
| Record<string, string>
| Promise<Record<string, string>>
Returns
void
pauseClusterExporting()
pauseClusterExporting(input, options?): CancelablePromise<void>;
Pause exporting across the whole cluster
Pauses exporting on every physical tenant of the cluster in one call. With soft=true, every physical tenant is soft-paused instead.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Pause cluster exporting
async function pauseClusterExportingExample() {
const camunda = createCamundaClient();
// Cluster-admin variant: pauses exporting on every physical tenant of the
// cluster. With `soft: true` exporting keeps running but its position is not
// committed, so the log is still not compacted.
await camunda.pauseClusterExporting({ soft: true });
}
Operation Id
pauseClusterExporting
Tags
Exporting
pauseExporting()
pauseExporting(input, options?): CancelablePromise<void>;
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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Pause exporting
async 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 });
}
Operation Id
pauseExporting
Tags
Exporting
pinClock()
pinClock(input, options?): CancelablePromise<void>;
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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Pin the cluster clock
async function pinClockExample() {
const camunda = createCamundaClient();
await camunda.pinClock({
timestamp: 1735689599000,
});
console.log("Clock pinned");
}
Operation Id
pinClock
Tags
Clock
publishMessage()
publishMessage(input, options?): CancelablePromise<MessagePublicationResult>;
Publish 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.
Parameters
input
options?
Returns
CancelablePromise<MessagePublicationResult>
Example
Publish a message
async function publishMessageExample() {
const camunda = createCamundaClient();
await camunda.publishMessage({
name: "order-payment-received",
correlationKey: "ORD-12345",
timeToLive: 60000,
variables: {
paymentId: "PAY-123",
},
});
}
Operation Id
publishMessage
Tags
Message
resetClock()
resetClock(options?): CancelablePromise<void>;
Reset 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.
Parameters
options?
Returns
CancelablePromise<void>
Example
Reset the cluster clock
async function resetClockExample() {
const camunda = createCamundaClient();
await camunda.resetClock();
console.log("Clock reset");
}
Operation Id
resetClock
Tags
Clock
resolveIncident()
resolveIncident(input, options?): CancelablePromise<void>;
Resolve 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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Resolve an incident
async function resolveIncidentExample(incidentKey: IncidentKey) {
const camunda = createCamundaClient();
await camunda.resolveIncident({ incidentKey });
}
Operation Id
resolveIncident
Tags
Incident
resolveIncidentsBatchOperation()
resolveIncidentsBatchOperation(input, options?): CancelablePromise<BatchOperationCreatedResult>;
Resolve 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}).
Parameters
input
ProcessInstanceIncidentResolutionBatchOperationRequest
options?
Returns
CancelablePromise<BatchOperationCreatedResult>
Example
Resolve incidents in batch
async function resolveIncidentsBatchOperationExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const result = await camunda.resolveIncidentsBatchOperation({
filter: {
processDefinitionKey,
},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Operation Id
resolveIncidentsBatchOperation
Tags
Process instance
resolveProcessInstanceIncidents()
resolveProcessInstanceIncidents(input, options?): CancelablePromise<BatchOperationCreatedResult>;
Resolve related incidents
Creates a batch operation to resolve multiple incidents of a process instance. *
Parameters
input
resolveProcessInstanceIncidentsInput
options?
Returns
CancelablePromise<BatchOperationCreatedResult>
Example
Resolve process instance incidents
async function resolveProcessInstanceIncidentsExample(
processInstanceKey: ProcessInstanceKey
) {
const camunda = createCamundaClient();
const result = await camunda.resolveProcessInstanceIncidents({
processInstanceKey,
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Operation Id
resolveProcessInstanceIncidents
Tags
Process instance
resolveSecrets()
resolveSecrets(input, options?): CancelablePromise<SecretResolveResult>;
Resolve secrets
Resolve a deduplicated batch of camunda.secrets.* references for the caller's
physical tenant in a single round-trip.
Each reference is authorized and resolved independently. For valid requests, the endpoint
always responds with HTTP 200: successfully resolved references are returned in resolved,
while references that could not be resolved (for example not found, malformed or over-long,
or the caller lacks SECRET:REVEAL on that reference) are returned in errors. A failure of
one reference never fails the others. Only structurally invalid requests are rejected with
HTTP 400: a missing or non-array references field, more than 20 references, or a null entry.
References are resolved against the secret stores configured for the caller's physical tenant, served from the gateway's secret cache when the value is already cached and read from the store otherwise.
Parameters
input
options?
Returns
CancelablePromise<SecretResolveResult>
Example
Resolve secrets
async 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) {}
Operation Id
resolveSecrets
Tags
Secret
restore()
restore(input, options?): CancelablePromise<ClusterRestoreResponse>;
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. *
Parameters
input
options?
Returns
CancelablePromise<ClusterRestoreResponse>
Example
Restore from a backup
async function restoreExample() {
const camunda = createCamundaClient();
// The cluster must be in recovery mode before a restore is accepted. Provide
// either a list of backup IDs (one per partition) or a time range (`from`/`to`)
// that selects the backups to restore, but not both.
const change = await camunda.restore({
backupIds: [100, 101],
});
console.log(`Cluster change ${change.changeId}:`);
for (const group of change.plannedChanges) {
console.log(` ${group.physicalTenantId ?? "cluster-wide"}:`);
for (const op of group.operations) {
const mode = "mode" in op ? op.mode : undefined;
console.log(` ${op.operation}${mode ? ` -> ${mode}` : ""}`);
}
}
}
Operation Id
restore
Tags
Recovery
restoreAsClusterAdmin()
restoreAsClusterAdmin(input, options?): CancelablePromise<ClusterRestoreResponse>;
Restore one or every physical tenant from a backup
Restores physical tenants from backups. The restore is described either by a list of backup IDs or by a time range (from/to) that selects the backups to restore. Restores are only accepted while the targeted physical tenants are in recovery mode; requests are rejected otherwise. The request is validated and acknowledged, but the restore itself is performed asynchronously.
If the physicalTenantId parameter is provided, only that physical tenant is restored and overrides must be omitted.
If it is not provided, every physical tenant of the cluster is restored: those named in overrides with their own backup selection, all others with the selection at the top level of the request body.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. *
Parameters
input
options?
Returns
CancelablePromise<ClusterRestoreResponse>
Example
Restore from a backup as cluster admin
async function restoreAsClusterAdminExample() {
const camunda = createCamundaClient();
// The cluster-admin variant can target a specific physical tenant and supports
// per-tenant overrides. Omit `physicalTenantId` to restore every physical
// tenant. Provide either backup IDs (one per partition) or a time range
// (`from`/`to`), but not both.
const change = await camunda.restoreAsClusterAdmin({
backupIds: [200, 201],
physicalTenantId: "default",
dryRun: true,
});
console.log(`Cluster change ${change.changeId}:`);
for (const group of change.plannedChanges) {
console.log(` ${group.physicalTenantId ?? "cluster-wide"}:`);
for (const op of group.operations) {
const mode = "mode" in op ? op.mode : undefined;
console.log(` ${op.operation}${mode ? ` -> ${mode}` : ""}`);
}
}
}
Operation Id
restoreAsClusterAdmin
Tags
Recovery
resumeBatchOperation()
resumeBatchOperation(input, options?): CancelablePromise<void>;
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}).
Parameters
input
batchOperationKey
options?
Returns
CancelablePromise<void>
Example
Resume a batch operation
async function resumeBatchOperationExample(
batchOperationKey: BatchOperationKey
) {
const camunda = createCamundaClient();
await camunda.resumeBatchOperation({ batchOperationKey });
}
Operation Id
resumeBatchOperation
Tags
Batch operation
resumeClusterExporting()
resumeClusterExporting(options?): CancelablePromise<void>;
Resume exporting across the whole cluster
Resumes exporting on every physical tenant of the cluster in one call, after a pause or soft pause.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. *
Parameters
options?
Returns
CancelablePromise<void>
Example
Resume cluster exporting
async function resumeClusterExportingExample() {
const camunda = createCamundaClient();
await camunda.resumeClusterExporting();
}
Operation Id
resumeClusterExporting
Tags
Exporting
resumeExporting()
resumeExporting(options?): CancelablePromise<void>;
Resume exporting
Resumes exporting on all partitions of the physical tenant after a pause or soft pause.
Parameters
options?
Returns
CancelablePromise<void>
Example
Resume exporting
async function resumeExportingExample() {
const camunda = createCamundaClient();
await camunda.resumeExporting();
}
Operation Id
resumeExporting
Tags
Exporting
resumeProcessInstance()
resumeProcessInstance(input, options?): CancelablePromise<void>;
Resume process instance
Resumes a suspended process instance, returning it to the ACTIVE state and continuing processing. Only process instances in the SUSPENDED state can be resumed. A child process instance can be resumed independently of its parent or root process instance; resumption does not cascade to or from related instances.
Parameters
input
object & object
options?
Returns
CancelablePromise<void>
Example
Resume a process instance
async function resumeProcessInstanceExample(
processInstanceKey: ProcessInstanceKey
) {
const camunda = createCamundaClient();
await camunda.resumeProcessInstance({ processInstanceKey });
}
Operation Id
resumeProcessInstance
Tags
Process instance
resumeProcessInstancesBatchOperation()
resumeProcessInstancesBatchOperation(input, options?): CancelablePromise<BatchOperationCreatedResult>;
Resume process instances (batch)
Resumes multiple suspended process instances. Any given filter for state or parentProcessInstanceKey is ignored and overridden, as only SUSPENDED process instances can be resumed and resumption does not cascade between parent and child instances, so child instances are resumed independently of their parent or root instance. This is done asynchronously, the progress can be tracked using the batchOperationKey from the response and the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Parameters
input
ProcessInstanceResumptionBatchOperationRequest
options?
Returns
CancelablePromise<BatchOperationCreatedResult>
Example
Resume process instances in batch
async function resumeProcessInstancesBatchOperationExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const result = await camunda.resumeProcessInstancesBatchOperation({
filter: {
processDefinitionKey,
},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Operation Id
resumeProcessInstancesBatchOperation
Tags
Process instance
searchAgentDefinitions()
searchAgentDefinitions(
input,
consistencyManagement,
options?
): CancelablePromise<AgentDefinitionSearchQueryResult>;
Search agent definitions
Search for agent definitions based on given criteria. *
Parameters
input
consistencyManagement
searchAgentDefinitionsConsistency
options?
Returns
CancelablePromise<AgentDefinitionSearchQueryResult>
Example
Search agent definitions
async function searchAgentDefinitionsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchAgentDefinitions(
{
filter: { agentType: { $eq: "AI_AGENT_TASK" } },
sort: [{ field: "name", order: "ASC" }],
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const definition of result.items ?? []) {
console.log(
`${definition.agentDefinitionKey}: ${definition.name} (${definition.agentType})`
);
}
console.log(`Total: ${result.page.totalItems}`);
}
Operation Id
searchAgentDefinitions
Tags
Agent definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchAgentInstanceHistory()
searchAgentInstanceHistory(
input,
consistencyManagement,
options?
): CancelablePromise<AgentInstanceHistorySearchQueryResult>;
Search agent instance history
Searches the conversation history of an agent instance. Committed items are returned by default.
Parameters
input
searchAgentInstanceHistoryInput
consistencyManagement
searchAgentInstanceHistoryConsistency
options?
Returns
CancelablePromise<AgentInstanceHistorySearchQueryResult>
Example
Search agent instance history
async 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}`);
}
Operation Id
searchAgentInstanceHistory
Tags
Agent instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchAgentInstances()
searchAgentInstances(
input,
consistencyManagement,
options?
): CancelablePromise<AgentInstanceSearchQueryResult>;
Search agent instances
Search for agent instances based on given criteria. *
Parameters
input
consistencyManagement
searchAgentInstancesConsistency
options?
Returns
CancelablePromise<AgentInstanceSearchQueryResult>
Example
Search agent instances
async 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}`);
}
Operation Id
searchAgentInstances
Tags
Agent instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchAuditLogs()
searchAuditLogs(
input,
consistencyManagement,
options?
): CancelablePromise<AuditLogSearchQueryResult>;
Search audit logs
Search for audit logs based on given criteria. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<AuditLogSearchQueryResult>
Example
Search audit logs
async 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}`);
}
}
Operation Id
searchAuditLogs
Tags
Audit Log
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchAuthorizations()
searchAuthorizations(
input,
consistencyManagement,
options?
): CancelablePromise<AuthorizationSearchResult>;
Search authorizations
Search for authorizations based on given criteria. *
Parameters
input
consistencyManagement
searchAuthorizationsConsistency
options?
Returns
CancelablePromise<AuthorizationSearchResult>
Example
Search authorizations
async 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}`
);
}
}
Operation Id
searchAuthorizations
Tags
Authorization
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchBatchOperationItems()
searchBatchOperationItems(
input,
consistencyManagement,
options?
): CancelablePromise<BatchOperationItemSearchQueryResult>;
Search batch operation items
Search for batch operation items based on given criteria. *
Parameters
input
consistencyManagement
searchBatchOperationItemsConsistency
options?
Returns
CancelablePromise<BatchOperationItemSearchQueryResult>
Example
Search batch operation items
async 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})`);
}
}
Operation Id
searchBatchOperationItems
Tags
Batch operation
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchBatchOperations()
searchBatchOperations(
input,
consistencyManagement,
options?
): CancelablePromise<BatchOperationSearchQueryResult>;
Search batch operations
Search for batch operations based on given criteria. *
Parameters
input
consistencyManagement
searchBatchOperationsConsistency
options?
Returns
CancelablePromise<BatchOperationSearchQueryResult>
Example
Search batch operations
async 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})`
);
}
}
Operation Id
searchBatchOperations
Tags
Batch operation
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchClientsForGroup()
searchClientsForGroup(
input,
consistencyManagement,
options?
): CancelablePromise<GroupClientSearchResult>;
Search group clients
Search clients assigned to a group. *
Parameters
input
consistencyManagement
searchClientsForGroupConsistency
options?
Returns
CancelablePromise<GroupClientSearchResult>
Example
Search clients in a group
async 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}`);
}
}
Operation Id
searchClientsForGroup
Tags
Group
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchClientsForRole()
searchClientsForRole(
input,
consistencyManagement,
options?
): CancelablePromise<RoleClientSearchResult>;
Search role clients
Search clients with assigned role. *
Parameters
input
consistencyManagement
searchClientsForRoleConsistency
options?
Returns
CancelablePromise<RoleClientSearchResult>
Example
Search clients for a role
async 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}`);
}
}
Operation Id
searchClientsForRole
Tags
Role
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchClientsForTenant()
searchClientsForTenant(
input,
consistencyManagement,
options?
): CancelablePromise<TenantClientSearchResult>;
Search clients for tenant
Retrieves a filtered and sorted list of clients for a specified tenant. *
Parameters
input
consistencyManagement
searchClientsForTenantConsistency
options?
Returns
CancelablePromise<TenantClientSearchResult>
Example
Search clients for a tenant
async 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}`);
}
}
Operation Id
searchClientsForTenant
Tags
Tenant
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchClusterVariables()
searchClusterVariables(
input,
consistencyManagement,
options?
): CancelablePromise<ClusterVariableSearchQueryResult>;
Search for cluster variables based on given criteria. By default, long variable values in the response are truncated. *
Parameters
input
consistencyManagement
searchClusterVariablesConsistency
options?
Returns
CancelablePromise<ClusterVariableSearchQueryResult>
Example
Search cluster variables
async 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}`);
}
}
Operation Id
searchClusterVariables
Tags
Cluster Variable
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchCorrelatedMessageSubscriptions()
searchCorrelatedMessageSubscriptions(
input,
consistencyManagement,
options?
): CancelablePromise<CorrelatedMessageSubscriptionSearchQueryResult>;
Search correlated message subscriptions
Search correlated message subscriptions based on given criteria. *
Parameters
input
CorrelatedMessageSubscriptionSearchQuery
consistencyManagement
searchCorrelatedMessageSubscriptionsConsistency
options?
Returns
CancelablePromise<CorrelatedMessageSubscriptionSearchQueryResult>
Example
Search correlated message subscriptions
async 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}`);
}
}
Operation Id
searchCorrelatedMessageSubscriptions
Tags
Message subscription
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchDecisionDefinitions()
searchDecisionDefinitions(
input,
consistencyManagement,
options?
): CancelablePromise<DecisionDefinitionSearchQueryResult>;
Search decision definitions
Search for decision definitions based on given criteria. *
Parameters
input
consistencyManagement
searchDecisionDefinitionsConsistency
options?
Returns
CancelablePromise<DecisionDefinitionSearchQueryResult>
Example
Search decision definitions
async 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}`);
}
}
Operation Id
searchDecisionDefinitions
Tags
Decision definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchDecisionInstances()
searchDecisionInstances(
input,
consistencyManagement,
options?
): CancelablePromise<DecisionInstanceSearchQueryResult>;
Search decision instances
Search for decision instances based on given criteria. *
Parameters
input
consistencyManagement
searchDecisionInstancesConsistency
options?
Returns
CancelablePromise<DecisionInstanceSearchQueryResult>
Example
Search decision instances
async 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}`
);
}
}
Operation Id
searchDecisionInstances
Tags
Decision instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchDecisionRequirements()
searchDecisionRequirements(
input,
consistencyManagement,
options?
): CancelablePromise<DecisionRequirementsSearchQueryResult>;
Search decision requirements
Search for decision requirements based on given criteria. *
Parameters
input
DecisionRequirementsSearchQuery
consistencyManagement
searchDecisionRequirementsConsistency
options?
Returns
CancelablePromise<DecisionRequirementsSearchQueryResult>
Example
Search decision requirements
async 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}`
);
}
}
Operation Id
searchDecisionRequirements
Tags
Decision requirements
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchElementInstanceIncidents()
searchElementInstanceIncidents(
input,
consistencyManagement,
options?
): CancelablePromise<IncidentSearchQueryResult>;
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.
Parameters
input
searchElementInstanceIncidentsInput
consistencyManagement
searchElementInstanceIncidentsConsistency
options?
Returns
CancelablePromise<IncidentSearchQueryResult>
Example
Search element instance incidents
async 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}`);
}
}
Operation Id
searchElementInstanceIncidents
Tags
Element instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchElementInstances()
searchElementInstances(
input,
consistencyManagement,
options?
): CancelablePromise<ElementInstanceSearchQueryResult>;
Search element instances
Search for element instances based on given criteria. *
Parameters
input
consistencyManagement
searchElementInstancesConsistency
options?
Returns
CancelablePromise<ElementInstanceSearchQueryResult>
Example
Search element instances
async 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})`);
}
}
Operation Id
searchElementInstances
Tags
Element instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchElementInstanceWaitStates()
searchElementInstanceWaitStates(
input,
consistencyManagement,
options?
): CancelablePromise<ElementInstanceWaitStateQueryResult>;
Search element instance wait states
Returns the wait states for element instances matching the given filter.
Parameters
input
consistencyManagement
searchElementInstanceWaitStatesConsistency
options?
Returns
CancelablePromise<ElementInstanceWaitStateQueryResult>
Example
Search element instance wait states
async 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}`);
}
}
Operation Id
searchElementInstanceWaitStates
Tags
Element instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchGlobalTaskListeners()
searchGlobalTaskListeners(
input,
consistencyManagement,
options?
): CancelablePromise<GlobalTaskListenerSearchQueryResult>;
Search global user task listeners
Search for global user task listeners based on given criteria. *
Parameters
input
GlobalTaskListenerSearchQueryRequest
consistencyManagement
searchGlobalTaskListenersConsistency
options?
Returns
CancelablePromise<GlobalTaskListenerSearchQueryResult>
Example
Search global task listeners
async 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})`);
}
}
Operation Id
searchGlobalTaskListeners
Tags
Global listener
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchGroupIdsForTenant()
searchGroupIdsForTenant(
input,
consistencyManagement,
options?
): CancelablePromise<TenantGroupSearchResult>;
Search groups for tenant
Retrieves a filtered and sorted list of groups for a specified tenant. *
Parameters
input
consistencyManagement
searchGroupIdsForTenantConsistency
options?
Returns
CancelablePromise<TenantGroupSearchResult>
Example
Search groups for a tenant
async 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}`);
}
}
Operation Id
searchGroupIdsForTenant
Tags
Tenant
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchGroups()
searchGroups(
input,
consistencyManagement,
options?
): CancelablePromise<GroupSearchQueryResult>;
Search groups
Search for groups based on given criteria. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<GroupSearchQueryResult>
Example
Search groups
async 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}`);
}
}
Operation Id
searchGroups
Tags
Group
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchGroupsForRole()
searchGroupsForRole(
input,
consistencyManagement,
options?
): CancelablePromise<RoleGroupSearchResult>;
Search role groups
Search groups with assigned role. *
Parameters
input
consistencyManagement
searchGroupsForRoleConsistency
options?
Returns
CancelablePromise<RoleGroupSearchResult>
Example
Search groups for a role
async 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}`);
}
}
Operation Id
searchGroupsForRole
Tags
Role
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchIncidents()
searchIncidents(
input,
consistencyManagement,
options?
): CancelablePromise<IncidentSearchQueryResult>;
Search incidents
Search for incidents based on given criteria.
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<IncidentSearchQueryResult>
Example
Search incidents
async 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}`);
}
Operation Id
searchIncidents
Tags
Incident
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchJobs()
searchJobs(
input,
consistencyManagement,
options?
): CancelablePromise<JobSearchQueryResult>;
Search jobs
Search for jobs based on given criteria. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<JobSearchQueryResult>
Example
Search jobs
async 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})`);
}
}
Operation Id
searchJobs
Tags
Job
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchMappingRule()
searchMappingRule(
input,
consistencyManagement,
options?
): CancelablePromise<MappingRuleSearchQueryResult>;
Search mapping rules
Search for mapping rules based on given criteria.
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<MappingRuleSearchQueryResult>
Example
Search mapping rules
async 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}`);
}
}
Operation Id
searchMappingRule
Tags
Mapping rule
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchMappingRulesForGroup()
searchMappingRulesForGroup(
input,
consistencyManagement,
options?
): CancelablePromise<GroupMappingRuleSearchResult>;
Search group mapping rules
Search mapping rules assigned to a group. *
Parameters
input
searchMappingRulesForGroupInput
consistencyManagement
searchMappingRulesForGroupConsistency
options?
Returns
CancelablePromise<GroupMappingRuleSearchResult>
Example
Search mapping rules for a group
async 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}`);
}
}
Operation Id
searchMappingRulesForGroup
Tags
Group
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchMappingRulesForRole()
searchMappingRulesForRole(
input,
consistencyManagement,
options?
): CancelablePromise<RoleMappingRuleSearchResult>;
Search role mapping rules
Search mapping rules with assigned role. *
Parameters
input
searchMappingRulesForRoleInput
consistencyManagement
searchMappingRulesForRoleConsistency
options?
Returns
CancelablePromise<RoleMappingRuleSearchResult>
Example
Search mapping rules for a role
async 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}`);
}
}
Operation Id
searchMappingRulesForRole
Tags
Role
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchMappingRulesForTenant()
searchMappingRulesForTenant(
input,
consistencyManagement,
options?
): CancelablePromise<TenantMappingRuleSearchResult>;
Search mapping rules for tenant
Retrieves a filtered and sorted list of MappingRules for a specified tenant. *
Parameters
input
searchMappingRulesForTenantInput
consistencyManagement
searchMappingRulesForTenantConsistency
options?
Returns
CancelablePromise<TenantMappingRuleSearchResult>
Example
Search mapping rules for a tenant
async 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}`);
}
}
Operation Id
searchMappingRulesForTenant
Tags
Tenant
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchMessageSubscriptions()
searchMessageSubscriptions(
input,
consistencyManagement,
options?
): CancelablePromise<MessageSubscriptionSearchQueryResult>;
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:
- Start event subscriptions are only captured for deployments made with 8.10 or later.
- The
messageSubscriptionTypefield is only populated for data created with Camunda 8.10 or later. For pre-8.10 data, intermediate event entries have nomessageSubscriptionTypevalue stored. For convenience, the API returnsPROCESS_EVENTas a default for such search results, though. - Searching for intermediate event subscriptions including legacy data can be achieved
by filtering for
messageSubscriptionTypenot matchingSTART_EVENT.
Parameters
input
MessageSubscriptionSearchQuery
consistencyManagement
searchMessageSubscriptionsConsistency
options?
Returns
CancelablePromise<MessageSubscriptionSearchQueryResult>
Example
Search message subscriptions
async 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}`);
}
}
Operation Id
searchMessageSubscriptions
Tags
Message subscription
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchOwnAuthorizations()
searchOwnAuthorizations(
input,
consistencyManagement,
options?
): CancelablePromise<OwnAuthorizationSearchResult>;
Search own authorizations
Search for the current authenticated principal's own authorization records — including authorizations granted directly to the user or client, as well as those granted via a group, role, or mapping rule the principal belongs to. *
Parameters
input
consistencyManagement
searchOwnAuthorizationsConsistency
options?
Returns
CancelablePromise<OwnAuthorizationSearchResult>
Example
Search own authorizations
async function searchOwnAuthorizationsExample() {
const camunda = createCamundaClient();
const result = await camunda.searchOwnAuthorizations(
{
filter: { resourceType: "PROCESS_DEFINITION" },
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const auth of result.items ?? []) {
console.log(`${auth.resourceId}: ${auth.permissionTypes?.join(", ")}`);
}
}
Operation Id
searchOwnAuthorizations
Tags
Authentication
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchProcessDefinitions()
searchProcessDefinitions(
input,
consistencyManagement,
options?
): CancelablePromise<ProcessDefinitionSearchQueryResult>;
Search process definitions
Search for process definitions based on given criteria. *
Parameters
input
consistencyManagement
searchProcessDefinitionsConsistency
options?
Returns
CancelablePromise<ProcessDefinitionSearchQueryResult>
Example
Search process definitions
async 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}`
);
}
}
Operation Id
searchProcessDefinitions
Tags
Process definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchProcessDefinitionVariableNames()
searchProcessDefinitionVariableNames(
input,
consistencyManagement,
options?
): CancelablePromise<ProcessDefinitionVariableNameSearchQueryResult>;
Search process definition variable names
Search for distinct variable names defined on a process definition, optionally narrowed by the name filter. *
Parameters
input
searchProcessDefinitionVariableNamesInput
consistencyManagement
searchProcessDefinitionVariableNamesConsistency
options?
Returns
CancelablePromise<ProcessDefinitionVariableNameSearchQueryResult>
Example
Search process definition variable names
async 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}`);
}
}
Operation Id
searchProcessDefinitionVariableNames
Tags
Process definition
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchProcessInstanceIncidents()
searchProcessInstanceIncidents(
input,
consistencyManagement,
options?
): CancelablePromise<IncidentSearchQueryResult>;
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.
Parameters
input
searchProcessInstanceIncidentsInput
consistencyManagement
searchProcessInstanceIncidentsConsistency
options?
Returns
CancelablePromise<IncidentSearchQueryResult>
Example
Search process instance incidents
async 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}`);
}
}
Operation Id
searchProcessInstanceIncidents
Tags
Process instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchProcessInstances()
searchProcessInstances(
input,
consistencyManagement,
options?
): CancelablePromise<ProcessInstanceSearchQueryResult>;
Search process instances
Search for process instances based on given criteria. *
Parameters
input
consistencyManagement
searchProcessInstancesConsistency
options?
Returns
CancelablePromise<ProcessInstanceSearchQueryResult>
Example
Search process instances
async 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}`);
}
Operation Id
searchProcessInstances
Tags
Process instance
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchResources()
searchResources(
input,
consistencyManagement,
options?
): CancelablePromise<ResourceSearchQueryResult>;
Search resources
Search for deployed resources based on given criteria.
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.
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<ResourceSearchQueryResult>
Example
Search resources
async 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}`);
}
}
Operation Id
searchResources
Tags
Resource
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchRoles()
searchRoles(
input,
consistencyManagement,
options?
): CancelablePromise<RoleSearchQueryResult>;
Search roles
Search for roles based on given criteria. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<RoleSearchQueryResult>
Example
Search roles
async function searchRolesExample() {
const camunda = createCamundaClient();
const result = await camunda.searchRoles(
{
page: { limit: 10 },
},
{ consistency: { waitUpToMs: 5000 } }
);
for (const role of result.items ?? []) {
console.log(`${role.roleId}: ${role.name}`);
}
}
Operation Id
searchRoles
Tags
Role
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchRolesForGroup()
searchRolesForGroup(
input,
consistencyManagement,
options?
): CancelablePromise<GroupRoleSearchResult>;
Search group roles
Search roles assigned to a group. *
Parameters
input
consistencyManagement
searchRolesForGroupConsistency
options?
Returns
CancelablePromise<GroupRoleSearchResult>
Example
Search roles for a group
async 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}`);
}
}
Operation Id
searchRolesForGroup
Tags
Group
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchRolesForTenant()
searchRolesForTenant(
input,
consistencyManagement,
options?
): CancelablePromise<TenantRoleSearchResult>;
Search roles for tenant
Retrieves a filtered and sorted list of roles for a specified tenant. *
Parameters
input
consistencyManagement
searchRolesForTenantConsistency
options?
Returns
CancelablePromise<TenantRoleSearchResult>
Example
Search roles for a tenant
async 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}`);
}
}
Operation Id
searchRolesForTenant
Tags
Tenant
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchTenants()
searchTenants(
input,
consistencyManagement,
options?
): CancelablePromise<TenantSearchQueryResult>;
Search tenants
Retrieves a filtered and sorted list of tenants. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<TenantSearchQueryResult>
Example
Search tenants
async 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}`);
}
}
Operation Id
searchTenants
Tags
Tenant
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchUsers()
searchUsers(
input,
consistencyManagement,
options?
): CancelablePromise<UserSearchResult>;
Search users
Search for users based on given criteria. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<UserSearchResult>
Example
Search users
async 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}`);
}
}
Operation Id
searchUsers
Tags
User
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchUsersForGroup()
searchUsersForGroup(
input,
consistencyManagement,
options?
): CancelablePromise<GroupUserSearchResult>;
Search group users
Search users assigned to a group. *
Parameters
input
consistencyManagement
searchUsersForGroupConsistency
options?
Returns
CancelablePromise<GroupUserSearchResult>
Example
Search users in a group
async 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}`);
}
}
Operation Id
searchUsersForGroup
Tags
Group
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchUsersForRole()
searchUsersForRole(
input,
consistencyManagement,
options?
): CancelablePromise<RoleUserSearchResult>;
Search role users
Search users with assigned role. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<RoleUserSearchResult>
Example
Search users for a role
async 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}`);
}
}
Operation Id
searchUsersForRole
Tags
Role
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchUsersForTenant()
searchUsersForTenant(
input,
consistencyManagement,
options?
): CancelablePromise<TenantUserSearchResult>;
Search users for tenant
Retrieves a filtered and sorted list of users for a specified tenant. *
Parameters
input
consistencyManagement
searchUsersForTenantConsistency
options?
Returns
CancelablePromise<TenantUserSearchResult>
Example
Search users for a tenant
async 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}`);
}
}
Operation Id
searchUsersForTenant
Tags
Tenant
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchUserTaskAuditLogs()
searchUserTaskAuditLogs(
input,
consistencyManagement,
options?
): CancelablePromise<AuditLogSearchQueryResult>;
Search user task audit logs
Search for user task audit logs based on given criteria. *
Parameters
input
consistencyManagement
searchUserTaskAuditLogsConsistency
options?
Returns
CancelablePromise<AuditLogSearchQueryResult>
Example
Search user task audit logs
async 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}`);
}
}
Operation Id
searchUserTaskAuditLogs
Tags
User task
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchUserTaskEffectiveVariables()
searchUserTaskEffectiveVariables(
input,
consistencyManagement,
options?
): CancelablePromise<VariableSearchQueryResult>;
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.
Parameters
input
searchUserTaskEffectiveVariablesInput
consistencyManagement
searchUserTaskEffectiveVariablesConsistency
options?
Returns
CancelablePromise<VariableSearchQueryResult>
Example
Search user task effective variables
async 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}`);
}
}
Operation Id
searchUserTaskEffectiveVariables
Tags
User task
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchUserTasks()
searchUserTasks(
input,
consistencyManagement,
options?
): CancelablePromise<UserTaskSearchQueryResult>;
Search user tasks
Search for user tasks based on given criteria. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<UserTaskSearchQueryResult>
Example
Search user tasks
async 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})`);
}
}
Operation Id
searchUserTasks
Tags
User task
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchUserTaskVariables()
searchUserTaskVariables(
input,
consistencyManagement,
options?
): CancelablePromise<VariableSearchQueryResult>;
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.
Parameters
input
consistencyManagement
searchUserTaskVariablesConsistency
options?
Returns
CancelablePromise<VariableSearchQueryResult>
Example
Search user task variables
async 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}`);
}
}
Operation Id
searchUserTaskVariables
Tags
User task
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchVariables()
searchVariables(
input,
consistencyManagement,
options?
): CancelablePromise<VariableSearchQueryResult>;
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. *
Parameters
input
consistencyManagement
options?
Returns
CancelablePromise<VariableSearchQueryResult>
Example
Search variables
async 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}`);
}
}
Operation Id
searchVariables
Tags
Variable
Consistency
eventual - this endpoint is backed by data that is eventually consistent with the system state.
searchVariablesAsDto()
searchVariablesAsDto<TSchema>(schema, options): CancelablePromise<VariableMap<TSchema>>;
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.
Type Parameters
TSchema
TSchema extends AnyVariableSchema
Parameters
schema
TSchema
A Zod object schema declaring the variables to fetch.
options
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.
consistency?
{
pollIntervalMs?: number;
waitUpToMs: number;
}
consistency.pollIntervalMs?
number
consistency.waitUpToMs
number
pageSize?
number
processInstanceKey
scopeKey?
tenantId?
Returns
CancelablePromise<VariableMap<TSchema>>
Throws
when a declared variable is found at more than one
scope and no scopeKey was provided to disambiguate.
Throws
when a variable's value is not valid JSON.
Example
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 }
stopAllWorkers()
stopAllWorkers(): void;
Stop all registered job workers (best-effort) and terminate the shared thread pool.
Returns
void
suspendBatchOperation()
suspendBatchOperation(input, options?): CancelablePromise<void>;
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}).
Parameters
input
batchOperationKey
options?
Returns
CancelablePromise<void>
Example
Suspend a batch operation
async function suspendBatchOperationExample(
batchOperationKey: BatchOperationKey
) {
const camunda = createCamundaClient();
await camunda.suspendBatchOperation({ batchOperationKey });
}
Operation Id
suspendBatchOperation
Tags
Batch operation
suspendProcessInstance()
suspendProcessInstance(input, options?): CancelablePromise<void>;
Suspend process instance
Suspends a running process instance, pausing further processing until it is resumed. Only process instances in the ACTIVE state can be suspended. A child process instance can be suspended independently of its parent or root process instance; suspension does not cascade to or from related instances.
Parameters
input
object & object
options?
Returns
CancelablePromise<void>
Example
Suspend a process instance
async function suspendProcessInstanceExample(
processInstanceKey: ProcessInstanceKey
) {
const camunda = createCamundaClient();
await camunda.suspendProcessInstance({ processInstanceKey });
}
Operation Id
suspendProcessInstance
Tags
Process instance
suspendProcessInstancesBatchOperation()
suspendProcessInstancesBatchOperation(input, options?): CancelablePromise<BatchOperationCreatedResult>;
Suspend process instances (batch)
Suspends multiple running process instances. Any given filter for state or parentProcessInstanceKey is ignored and overridden, as only ACTIVE process instances can be suspended and suspension does not cascade between parent and child instances, so child instances are suspended independently of their parent or root instance. This is done asynchronously, the progress can be tracked using the batchOperationKey from the response and the batch operation status endpoint (/batch-operations/{batchOperationKey}).
Parameters
input
ProcessInstanceSuspensionBatchOperationRequest
options?
Returns
CancelablePromise<BatchOperationCreatedResult>
Example
Suspend process instances in batch
async function suspendProcessInstancesBatchOperationExample(
processDefinitionKey: ProcessDefinitionKey
) {
const camunda = createCamundaClient();
const result = await camunda.suspendProcessInstancesBatchOperation({
filter: {
processDefinitionKey,
},
});
console.log(`Batch operation key: ${result.batchOperationKey}`);
}
Operation Id
suspendProcessInstancesBatchOperation
Tags
Process instance
syncRuntimeBackupState()
syncRuntimeBackupState(options?): CancelablePromise<RuntimeBackupState>;
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.
Parameters
options?
Returns
CancelablePromise<RuntimeBackupState>
Example
Force-write the runtime backup state
async 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`);
}
Operation Id
syncRuntimeBackupState
Tags
Backup
syncRuntimeBackupStateAsClusterAdmin()
syncRuntimeBackupStateAsClusterAdmin(input, options?): CancelablePromise<ClusterRuntimeBackupState>;
Force-write runtime backup state across physical tenants
Force-writes the checkpoint and backup metadata of every partition of every physical tenant of the cluster, or of the one named by physicalTenantId, to that tenant's backup store, independent of any backup being taken or confirmed, and returns the updated state per physical tenant.
The request is all-or-nothing: a physical tenant whose metadata cannot be written fails the whole request, and the writes that already succeeded on other tenants are not undone. The operation is idempotent, so retrying the same call is the correct remedy. Narrow the request with physicalTenantId to write the tenants that can still be reached.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use POST /v2/backups/runtime/state/sync to act as a single physical tenant. *
Parameters
input
syncRuntimeBackupStateAsClusterAdminInput
options?
Returns
CancelablePromise<ClusterRuntimeBackupState>
Example
Force-write the runtime backup state (cluster admin)
async function syncRuntimeBackupStateAsClusterAdminExample() {
const camunda = createCamundaClient();
// Force-writes checkpoint and backup metadata of every partition to the backup
// store on every targeted physical tenant, independent of any backup being
// taken, and returns the updated per-tenant state.
const clusterState = await camunda.syncRuntimeBackupStateAsClusterAdmin({});
console.log(`Synced ${clusterState.physicalTenants.length} physical tenants`);
}
Operation Id
syncRuntimeBackupStateAsClusterAdmin
Tags
Backup
takeHistoryBackup()
takeHistoryBackup(input, options?): CancelablePromise<TakeHistoryBackupResponse>;
Take a history backup
Triggers a backup of the physical tenant's history, by scheduling a snapshot of every secondary storage index it owns.
Unlike runtime backups, history backups have no generated-id mode: backupId is always
required.
Only available on clusters whose secondary storage is Elasticsearch or OpenSearch.
Parameters
input
options?
Returns
CancelablePromise<TakeHistoryBackupResponse>
Example
Take a history backup
async function takeHistoryBackupExample() {
const camunda = createCamundaClient();
// Backups are logically ordered by id, so each successive backup must use a
// higher id than the previous one.
const backup = await camunda.takeHistoryBackup({ backupId: 100 });
console.log(`Scheduled history backup ${backup.backupId}`);
for (const snapshot of backup.scheduledSnapshots) {
console.log(` ${snapshot}`);
}
}
Operation Id
takeHistoryBackup
Tags
Backup
takeHistoryBackupAsClusterAdmin()
takeHistoryBackupAsClusterAdmin(input, options?): CancelablePromise<ClusterTakeHistoryBackupResponse>;
Take a history backup on one or every physical tenant
Triggers a history backup on every physical tenant of the cluster, or on the one named by physicalTenantId. Every targeted tenant uses the same caller-supplied backupId, but the backups are independent: they are neither coordinated nor rolled back together.
The request is all-or-nothing: the backupId is checked on every targeted tenant before any snapshot is scheduled, so a tenant that already holds this id, or that cannot be reached, fails the whole request and no backup is started anywhere. There is no aggregated cluster-level state in the response.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Only available on clusters whose secondary storage is Elasticsearch or OpenSearch. Use POST /v2/backups/history to act as a single physical tenant. *
Parameters
input
takeHistoryBackupAsClusterAdminInput
options?
Returns
CancelablePromise<ClusterTakeHistoryBackupResponse>
Example
Take a history backup (cluster admin)
async function takeHistoryBackupAsClusterAdminExample() {
const camunda = createCamundaClient();
// Cluster-admin variant: fans the backup out to every physical tenant of the
// cluster (or a single one when `physicalTenantId` is given). Requires a
// separate cluster-admin security chain — Orchestration Cluster user
// credentials are NOT accepted. Each backup must use a higher id than the last.
const backup = await camunda.takeHistoryBackupAsClusterAdmin({
backupId: 100,
});
console.log(`Scheduled cluster history backup ${backup.backupId}`);
for (const tenant of backup.physicalTenants) {
console.log(
` [${tenant.physicalTenantId}] scheduled ${tenant.scheduledSnapshots.length} snapshots`
);
}
}
Operation Id
takeHistoryBackupAsClusterAdmin
Tags
Backup
takeRuntimeBackup()
takeRuntimeBackup(input, options?): CancelablePromise<TakeRuntimeBackupResponse>;
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.
Parameters
input
options?
Returns
CancelablePromise<TakeRuntimeBackupResponse>
Example
Take a runtime backup
async 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}`);
}
Operation Id
takeRuntimeBackup
Tags
Backup
takeRuntimeBackupAsClusterAdmin()
takeRuntimeBackupAsClusterAdmin(input, options?): CancelablePromise<ClusterTakeRuntimeBackupResponse>;
Take a runtime backup on one or every physical tenant
Triggers a runtime backup on every physical tenant of the cluster, or on the one named by physicalTenantId. A cluster-wide backup is a set of independent per-tenant backups, not an atomic snapshot of the cluster: they are neither coordinated nor rolled back together, and each tenant stores its own, so the same backupId can be used for all of them.
Every targeted physical tenant must be in the same backup-id mode. backupId must be omitted when every targeted tenant generates its own ids (because continuous backups and/or a backup or checkpoint schedule is enabled for it), and is required when none of them does. A cluster whose targeted tenants mix the two modes is rejected with 400 and has to be driven one tenant at a time through POST /v2/backups/runtime. In generated-id mode each tenant generates its own id, so the response reports an id per physical tenant rather than one for the cluster.
The trigger is all-or-error, and never silent about a partial trigger: if any targeted tenant cannot be triggered the response carries an error status, but its body still lists every targeted tenant — which ones were triggered, under which backupId to monitor or delete them, and why the others failed. Nothing is rolled back, so the backups that were triggered keep running and have to be deleted explicitly. A request rejected before any tenant was triggered answers with a problem detail instead, and nothing is running.
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. Use POST /v2/backups/runtime to act as a single physical tenant. *
Parameters
input
takeRuntimeBackupAsClusterAdminInput
options?
Returns
CancelablePromise<ClusterTakeRuntimeBackupResponse>
Example
Take a runtime backup (cluster admin)
async function takeRuntimeBackupAsClusterAdminExample() {
const camunda = createCamundaClient();
// Cluster-admin variant: triggers a runtime backup on every physical tenant of
// the cluster (or a single one when `physicalTenantId` is given). Requires the
// separate cluster-admin security chain — Orchestration Cluster user
// credentials are NOT accepted. Passing an explicit `backupId` is manual-id
// mode: every targeted tenant must share that id (omit it for generated-id
// mode, where each tenant generates its own). Either way the response lists the
// outcome per physical tenant rather than cluster-wide.
const backup = await camunda.takeRuntimeBackupAsClusterAdmin({
backupId: 100,
});
for (const tenant of backup.physicalTenants) {
console.log(
`[${tenant.physicalTenantId}] ${tenant.outcome} (backupId ${tenant.backupId})`
);
}
}
Operation Id
takeRuntimeBackupAsClusterAdmin
Tags
Backup
throwJobError()
throwJobError(input, options?): CancelablePromise<void>;
Throw error for job
Reports a business error (i.e. non-technical) that occurs while processing a job.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Throw a job error
async function throwJobErrorExample(jobKey: JobKey) {
const camunda = createCamundaClient();
await camunda.throwJobError({
jobKey,
errorCode: "PAYMENT_FAILED",
errorMessage: "Payment provider returned error",
});
}
Operation Id
throwJobError
Tags
Job
triggerClusterRebalance()
triggerClusterRebalance(input, options?): CancelablePromise<ClusterBalanceResponse>;
Trigger a cluster-wide leadership rebalance
Transfers leadership of every partition that is not led by its highest-priority replica towards that replica, one partition at a time. Returns as soon as the rebalance has been accepted (poll GET /cluster/v2/rebalance to monitor progress).
Each rebalance can specify overrides for the configured rebalance settings (e.g. maximum replication lag to allow). An absent request body means "use the configured settings".
Requires the cluster-admin security chain. Although this operation lists bearerAuth / basicAuth like the rest of the Orchestration Cluster API, it does not accept an Orchestration Cluster user's credentials — only the separate cluster-admin credentials are valid here. *
Parameters
input
options?
Returns
CancelablePromise<ClusterBalanceResponse>
Example
Trigger a cluster-wide leadership rebalance
async function triggerClusterRebalanceExample() {
const camunda = createCamundaClient();
const balance = await camunda.triggerClusterRebalance({
replicationLagThreshold: 10_000_000,
maxTransferAttempts: 3,
});
console.log(`Cluster balance state: ${balance.state}`);
if (balance.runningRebalance) {
console.log(
`Rebalance started: id=${balance.runningRebalance.rebalanceId}`
);
}
}
Operation Id
triggerClusterRebalance
Tags
Cluster
unassignClientFromGroup()
unassignClientFromGroup(input, options?): CancelablePromise<void>;
Unassign a client from a group
Unassigns a client from a group. The client is removed as a group member, with associated authorizations, roles, and tenant assignments no longer applied.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Unassign a client from a group
async function unassignClientFromGroupExample(
groupId: GroupId,
clientId: ClientId
) {
const camunda = createCamundaClient();
await camunda.unassignClientFromGroup({
groupId,
clientId,
});
}
Operation Id
unassignClientFromGroup
Tags
Group
unassignClientFromTenant()
unassignClientFromTenant(input, options?): CancelablePromise<void>;
Unassign a client from a tenant
Unassigns the client from the specified tenant. The client can no longer access tenant data.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Unassign a client from a tenant
async function unassignClientFromTenantExample(
tenantId: TenantId,
clientId: ClientId
) {
const camunda = createCamundaClient();
await camunda.unassignClientFromTenant({
tenantId,
clientId,
});
}
Operation Id
unassignClientFromTenant
Tags
Tenant
unassignGroupFromTenant()
unassignGroupFromTenant(input, options?): CancelablePromise<void>;
Unassign 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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Unassign a group from a tenant
async function unassignGroupFromTenantExample(
tenantId: TenantId,
groupId: GroupId
) {
const camunda = createCamundaClient();
await camunda.unassignGroupFromTenant({
tenantId,
groupId,
});
}
Operation Id
unassignGroupFromTenant
Tags
Tenant
unassignMappingRuleFromGroup()
unassignMappingRuleFromGroup(input, options?): CancelablePromise<void>;
Unassign a mapping rule from a group
Unassigns a mapping rule from a group. *
Parameters
input
unassignMappingRuleFromGroupInput
options?
Returns
CancelablePromise<void>
Example
Unassign a mapping rule from a group
async function unassignMappingRuleFromGroupExample(
groupId: GroupId,
mappingRuleId: MappingRuleId
) {
const camunda = createCamundaClient();
await camunda.unassignMappingRuleFromGroup({
groupId,
mappingRuleId,
});
}
Operation Id
unassignMappingRuleFromGroup
Tags
Group
unassignMappingRuleFromTenant()
unassignMappingRuleFromTenant(input, options?): CancelablePromise<void>;
Unassign a mapping rule from a tenant
Unassigns a single mapping rule from a specified tenant without deleting the rule. *
Parameters
input
unassignMappingRuleFromTenantInput
options?
Returns
CancelablePromise<void>
Example
Unassign a mapping rule from a tenant
async function unassignMappingRuleFromTenantExample(
tenantId: TenantId,
mappingRuleId: MappingRuleId
) {
const camunda = createCamundaClient();
await camunda.unassignMappingRuleFromTenant({
tenantId,
mappingRuleId,
});
}
Operation Id
unassignMappingRuleFromTenant
Tags
Tenant
unassignRoleFromClient()
unassignRoleFromClient(input, options?): CancelablePromise<void>;
Unassign a role from a client
Unassigns the specified role from the client. The client will no longer inherit the authorizations associated with this role. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Unassign a role from a client
async function unassignRoleFromClientExample(
roleId: RoleId,
clientId: ClientId
) {
const camunda = createCamundaClient();
await camunda.unassignRoleFromClient({
roleId,
clientId,
});
}
Operation Id
unassignRoleFromClient
Tags
Role
unassignRoleFromGroup()
unassignRoleFromGroup(input, options?): CancelablePromise<void>;
Unassign 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. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Unassign a role from a group
async function unassignRoleFromGroupExample(roleId: RoleId, groupId: GroupId) {
const camunda = createCamundaClient();
await camunda.unassignRoleFromGroup({
roleId,
groupId,
});
}
Operation Id
unassignRoleFromGroup
Tags
Role
unassignRoleFromMappingRule()
unassignRoleFromMappingRule(input, options?): CancelablePromise<void>;
Unassign a role from a mapping rule
Unassigns a role from a mapping rule. *
Parameters
input
unassignRoleFromMappingRuleInput
options?
Returns
CancelablePromise<void>
Example
Unassign a role from a mapping rule
async function unassignRoleFromMappingRuleExample(
roleId: RoleId,
mappingRuleId: MappingRuleId
) {
const camunda = createCamundaClient();
await camunda.unassignRoleFromMappingRule({
roleId,
mappingRuleId,
});
}
Operation Id
unassignRoleFromMappingRule
Tags
Role
unassignRoleFromTenant()
unassignRoleFromTenant(input, options?): CancelablePromise<void>;
Unassign 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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Unassign a role from a tenant
async function unassignRoleFromTenantExample(
tenantId: TenantId,
roleId: RoleId
) {
const camunda = createCamundaClient();
await camunda.unassignRoleFromTenant({
tenantId,
roleId,
});
}
Operation Id
unassignRoleFromTenant
Tags
Tenant
unassignRoleFromUser()
unassignRoleFromUser(input, options?): CancelablePromise<void>;
Unassign a role from a user
Unassigns a role from a user. The user will no longer inherit the authorizations associated with this role. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Unassign a role from a user
async function unassignRoleFromUserExample(roleId: RoleId, username: Username) {
const camunda = createCamundaClient();
await camunda.unassignRoleFromUser({
roleId,
username,
});
}
Operation Id
unassignRoleFromUser
Tags
Role
unassignUserFromGroup()
unassignUserFromGroup(input, options?): CancelablePromise<void>;
Unassign 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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Unassign a user from a group
async function unassignUserFromGroupExample(
groupId: GroupId,
username: Username
) {
const camunda = createCamundaClient();
await camunda.unassignUserFromGroup({
groupId,
username,
});
}
Operation Id
unassignUserFromGroup
Tags
Group
unassignUserFromTenant()
unassignUserFromTenant(input, options?): CancelablePromise<void>;
Unassign a user from a tenant
Unassigns the user from the specified tenant. The user can no longer access tenant data.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Unassign a user from a tenant
async function unassignUserFromTenantExample(
tenantId: TenantId,
username: Username
) {
const camunda = createCamundaClient();
await camunda.unassignUserFromTenant({
tenantId,
username,
});
}
Operation Id
unassignUserFromTenant
Tags
Tenant
unassignUserTask()
unassignUserTask(input, options?): CancelablePromise<void>;
Unassign 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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Unassign a user task
async function unassignUserTaskExample(userTaskKey: UserTaskKey) {
const camunda = createCamundaClient();
await camunda.unassignUserTask({ userTaskKey });
}
Operation Id
unassignUserTask
Tags
User task
updateAgentInstance()
updateAgentInstance(input, options?): CancelablePromise<AgentInstanceUpdateResult>;
Update agent instance
Updates the status of an agent instance and appends a batch of history items to its conversation history. Each history item created for this request is echoed back in the response.
Parameters
input
options?
Returns
CancelablePromise<AgentInstanceUpdateResult>
Example
Update an agent instance
async function updateAgentInstanceExample(
agentInstanceKey: AgentInstanceKey,
elementInstanceKey: ElementInstanceKey,
jobKey: JobKey,
jobLeaseToken: JobLeaseToken
) {
const camunda = createCamundaClient();
await camunda.updateAgentInstance({
agentInstanceKey,
elementInstanceKey,
jobKey,
jobLeaseToken,
status: "THINKING",
history: [
{
historyItemId: HistoryItemId.assumeExists("assistant-1"),
loopIteration: 1,
role: "ASSISTANT",
content: [{ contentType: "TEXT", text: "How can I help you?" }],
producedAt: new Date().toISOString(),
metrics: { inputTokens: 150, outputTokens: 50, durationMs: 820 },
},
],
});
console.log(`Updated agent instance: ${agentInstanceKey}`);
}
Operation Id
updateAgentInstance
Tags
Agent instance
updateAuthorization()
updateAuthorization(input, options?): CancelablePromise<void>;
Update authorization
Update the authorization with the given key. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Update an authorization
async 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",
],
});
}
Operation Id
updateAuthorization
Tags
Authorization
updateGlobalClusterVariable()
updateGlobalClusterVariable(input, options?): CancelablePromise<ClusterVariableResult>;
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.
Parameters
input
updateGlobalClusterVariableInput
options?
Returns
CancelablePromise<ClusterVariableResult>
Example
Update a global cluster variable
async function updateGlobalClusterVariableExample(name: ClusterVariableName) {
const camunda = createCamundaClient();
await camunda.updateGlobalClusterVariable({
name,
value: { darkMode: false },
});
}
Operation Id
updateGlobalClusterVariable
Tags
Cluster Variable
updateGlobalTaskListener()
updateGlobalTaskListener(input, options?): CancelablePromise<GlobalTaskListenerResult>;
Update global user task listener
Updates a global user task listener. *
Parameters
input
options?
Returns
CancelablePromise<GlobalTaskListenerResult>
Example
Update a global task listener
async function updateGlobalTaskListenerExample(id: GlobalListenerId) {
const camunda = createCamundaClient();
await camunda.updateGlobalTaskListener({
id,
eventTypes: ["completing"],
type: "updated-audit-listener",
});
}
Operation Id
updateGlobalTaskListener
Tags
Global listener
updateGroup()
updateGroup(input, options?): CancelablePromise<GroupUpdateResult>;
Update group
Update a group with the given ID. *
Parameters
input
options?
Returns
CancelablePromise<GroupUpdateResult>
Example
Update a group
async function updateGroupExample(groupId: GroupId) {
const camunda = createCamundaClient();
await camunda.updateGroup({
groupId,
name: "Engineering Team",
});
}
Operation Id
updateGroup
Tags
Group
updateJob()
updateJob(input, options?): CancelablePromise<void>;
Update job
Update a job with the given key. *
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Update a job
async function updateJobExample(jobKey: JobKey) {
const camunda = createCamundaClient();
await camunda.updateJob({
jobKey,
changeset: { retries: 5, timeout: 60000 },
});
}
Operation Id
updateJob
Tags
Job
updateJobsBatchOperation()
updateJobsBatchOperation(input, options?): CancelablePromise<BatchOperationCreatedResult>;
Update 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}).
Parameters
input
options?
Returns
CancelablePromise<BatchOperationCreatedResult>
Example
Update jobs in batch
async 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}`);
}
Operation Id
updateJobsBatchOperation
Tags
Job
updateMappingRule()
updateMappingRule(input, options?): CancelablePromise<MappingRuleCreateUpdateResult>;
Update mapping rule
Update a mapping rule.
Parameters
input
options?
Returns
CancelablePromise<MappingRuleCreateUpdateResult>
Example
Update a mapping rule
async function updateMappingRuleExample(mappingRuleId: MappingRuleId) {
const camunda = createCamundaClient();
await camunda.updateMappingRule({
mappingRuleId,
name: "LDAP Group Mapping",
claimName: "groups",
claimValue: "engineering-team",
});
}
Operation Id
updateMappingRule
Tags
Mapping rule
updateRole()
updateRole(input, options?): CancelablePromise<RoleUpdateResult>;
Update role
Update a role with the given ID. *
Parameters
input
options?
Returns
CancelablePromise<RoleUpdateResult>
Example
Update a role
async function updateRoleExample(roleId: RoleId) {
const camunda = createCamundaClient();
await camunda.updateRole({
roleId,
name: "Process Administrator",
});
}
Operation Id
updateRole
Tags
Role
updateTenant()
updateTenant(input, options?): CancelablePromise<TenantUpdateResult>;
Update tenant
Updates an existing tenant. *
Parameters
input
options?
Returns
CancelablePromise<TenantUpdateResult>
Example
Update a tenant
async function updateTenantExample(tenantId: TenantId) {
const camunda = createCamundaClient();
await camunda.updateTenant({
tenantId,
name: "Customer Service Team",
});
}
Operation Id
updateTenant
Tags
Tenant
updateTenantClusterVariable()
updateTenantClusterVariable(input, options?): CancelablePromise<ClusterVariableResult>;
Update 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.
Parameters
input
updateTenantClusterVariableInput
options?
Returns
CancelablePromise<ClusterVariableResult>
Example
Update a tenant cluster variable
async function updateTenantClusterVariableExample(
tenantId: TenantId,
name: ClusterVariableName
) {
const camunda = createCamundaClient();
await camunda.updateTenantClusterVariable({
tenantId,
name,
value: { region: "eu-west-1" },
});
}
Operation Id
updateTenantClusterVariable
Tags
Cluster Variable
updateUser()
updateUser(input, options?): CancelablePromise<UserUpdateResult>;
Update user
Updates a user. *
Parameters
input
options?
Returns
CancelablePromise<UserUpdateResult>
Example
Update a user
async function updateUserExample(username: Username) {
const camunda = createCamundaClient();
await camunda.updateUser({
username,
name: "Alice Jones",
email: "alice.jones@example.com",
});
}
Operation Id
updateUser
Tags
User
updateUserTask()
updateUserTask(input, options?): CancelablePromise<void>;
Update 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.
Parameters
input
options?
Returns
CancelablePromise<void>
Example
Update a user task
async function updateUserTaskExample(userTaskKey: UserTaskKey) {
const camunda = createCamundaClient();
await camunda.updateUserTask({
userTaskKey,
changeset: {
candidateUsers: ["alice", "bob"],
dueDate: "2025-12-31T23:59:59Z",
priority: 80,
},
});
}
Operation Id
updateUserTask
Tags
User task
withCorrelation()
withCorrelation<T>(id, fn): Promise<T>;
Type Parameters
T
T
Parameters
id
string
fn
() => T | Promise<T>
Returns
Promise<T>