CamundaClient

Technical Preview

The C# SDK is a technical preview available from Camunda 8.9. It will become fully supported in Camunda 8.10. Its API surface may change in future releases without following semver.

Creating a Client

Factory method for creating CamundaClient instances.

public static CamundaClient CreateClient(CamundaOptions? options = null)

Create a new CamundaClient.

Parameter	Type	Description
options	CamundaOptions

Dependency Injection

Extension methods for registering in an .

AddCamundaClient(IServiceCollection)

public static IServiceCollection AddCamundaClient(this IServiceCollection services)

Registers a singleton using zero-config (environment variables only).

Parameter	Type	Description
services	IServiceCollection

AddCamundaClient(IServiceCollection, IConfiguration)

public static IServiceCollection AddCamundaClient(this IServiceCollection services, IConfiguration configurationSection)

Registers a singleton using an section.

Typically called as services.AddCamundaClient(configuration.GetSection("Camunda")). PascalCase keys in the section are mapped to canonical CAMUNDA_* env-var names internally. Environment variables still apply as a base layer; section values override them.

Parameter	Type	Description
services	IServiceCollection
configurationSection	IConfiguration

AddCamundaClient(IServiceCollection, Action)

public static IServiceCollection AddCamundaClient(this IServiceCollection services, Action<CamundaOptions> configure)

Registers a singleton with an options callback for full control.

Parameter	Type	Description
services	IServiceCollection
configure	Action<CamundaOptions>

Overview

Primary Camunda client. Provides typed methods for all Camunda 8 REST API operations.

Auto-generated operation methods are added in the Generated/ partial class files. This class provides the infrastructure: configuration, auth, retry, backpressure.

public class CamundaClient : IDisposable, IAsyncDisposable

Constructor

public CamundaClient(CamundaOptions? options = null)

Create a new CamundaClient with the given options.

Parameter	Type	Description
options	CamundaOptions

Properties

Property	Type	Description
Config	CamundaConfig	The current hydrated configuration (read-only).

Methods

Other

Create(CamundaOptions?)

public static CamundaClient Create(CamundaOptions? options = null)

Create a new CamundaClient.

Parameter	Type	Description
options	CamundaOptions

Returns: CamundaClient

Dispose()

public void Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

DisposeAsync()

public ValueTask DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

Returns: ValueTask — A task that represents the asynchronous dispose operation.

CreateAdminUserAsync(UserRequest, CancellationToken)

public Task<UserCreateResult> CreateAdminUserAsync(UserRequest body, CancellationToken ct = default)

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.

Parameter	Type	Description
body	UserRequest
ct	CancellationToken

Returns: Task<UserCreateResult>

Example

public static async Task CreateAdminUserExample(Username username)
{
    using var client = CamundaClient.Create();

    var result = await client.CreateAdminUserAsync(new UserRequest
    {
        Username = username,
        Name = "Admin User",
        Email = "admin@example.com",
        Password = "admin-password",
    });

    Console.WriteLine($"Admin user key: {result.Username}");
}

CreateAgentInstanceAsync(AgentInstanceCreationRequest, CancellationToken)

public Task<AgentInstanceCreationResult> CreateAgentInstanceAsync(AgentInstanceCreationRequest body, CancellationToken ct = default)

Create agent instance Creates a new agent instance. The returned key identifies the instance and must be used in subsequent update and query calls.

Parameter	Type	Description
body	AgentInstanceCreationRequest
ct	CancellationToken

Returns: Task<AgentInstanceCreationResult>

Example

public static async Task CreateAgentInstanceExample(ElementInstanceKey elementInstanceKey)
{
    using var client = CamundaClient.Create();

    var result = await client.CreateAgentInstanceAsync(new AgentInstanceCreationRequest
    {
        ElementInstanceKey = elementInstanceKey,
        Definition = new AgentInstanceDefinition
        {
            Model = "gpt-4o",
            Provider = "openai",
            SystemPrompt = "You are a helpful assistant.",
        },
    });

    Console.WriteLine($"Created agent instance: {result.AgentInstanceKey}");
}

CreateGlobalTaskListenerAsync(CreateGlobalTaskListenerRequest, CancellationToken)

public Task<GlobalTaskListenerResult> CreateGlobalTaskListenerAsync(CreateGlobalTaskListenerRequest body, CancellationToken ct = default)

Create global user task listener Create a new global user task listener.

Parameter	Type	Description
body	CreateGlobalTaskListenerRequest
ct	CancellationToken

Returns: Task<GlobalTaskListenerResult>

Example

public static async Task CreateGlobalTaskListenerExample(GlobalListenerId id)
{
    using var client = CamundaClient.Create();

    var result = await client.CreateGlobalTaskListenerAsync(
        new CreateGlobalTaskListenerRequest
        {
            EventTypes = new List<GlobalTaskListenerEventTypeEnum> { GlobalTaskListenerEventTypeEnum.Completing },
            Id = id,
        });

    Console.WriteLine($"Task listener: {result.Id}");
}

CreateUserAsync(UserRequest, CancellationToken)

public Task<UserCreateResult> CreateUserAsync(UserRequest body, CancellationToken ct = default)

Create user Create a new user.

Parameter	Type	Description
body	UserRequest
ct	CancellationToken

Returns: Task<UserCreateResult>

Example

public static async Task CreateUserExample(Username username)
{
    using var client = CamundaClient.Create();

    var result = await client.CreateUserAsync(new UserRequest
    {
        Username = username,
        Name = "Jane Doe",
        Email = "jdoe@example.com",
        Password = "secure-password",
    });

    Console.WriteLine($"User key: {result.Username}");
}

DeleteGlobalTaskListenerAsync(GlobalListenerId, CancellationToken)

public Task DeleteGlobalTaskListenerAsync(GlobalListenerId id, CancellationToken ct = default)

Delete global user task listener Deletes a global user task listener.

Parameter	Type	Description
id	GlobalListenerId
ct	CancellationToken

Returns: Task

Example

public static async Task DeleteGlobalTaskListenerExample(GlobalListenerId globalListenerId)
{
    using var client = CamundaClient.Create();

    await client.DeleteGlobalTaskListenerAsync(
        globalListenerId);
}

DeleteUserAsync(Username, CancellationToken)

public Task DeleteUserAsync(Username username, CancellationToken ct = default)

Delete user Deletes a user.

Parameter	Type	Description
username	Username
ct	CancellationToken

Returns: Task

Example

public static async Task DeleteUserExample(Username username)
{
    using var client = CamundaClient.Create();

    await client.DeleteUserAsync(username);
}

EvaluateConditionalsAsync(ConditionalEvaluationInstruction, CancellationToken)

public Task<EvaluateConditionalResult> EvaluateConditionalsAsync(ConditionalEvaluationInstruction body, CancellationToken ct = default)

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.

Parameter	Type	Description
body	ConditionalEvaluationInstruction
ct	CancellationToken

Returns: Task<EvaluateConditionalResult>

Example

public static async Task EvaluateConditionalsExample()
{
    using var client = CamundaClient.Create();

    var result = await client.EvaluateConditionalsAsync(
        new ConditionalEvaluationInstruction());

    Console.WriteLine($"Result: {result}");
}

EvaluateExpressionAsync(ExpressionEvaluationRequest, CancellationToken)

public Task<ExpressionEvaluationResult> EvaluateExpressionAsync(ExpressionEvaluationRequest body, CancellationToken ct = default)

Evaluate an expression Evaluates a FEEL expression and returns the result. Supports references to tenant scoped cluster variables when a tenant ID is provided.

Parameter	Type	Description
body	ExpressionEvaluationRequest
ct	CancellationToken

Returns: Task<ExpressionEvaluationResult>

Example

public static async Task EvaluateExpressionExample()
{
    using var client = CamundaClient.Create();

    var result = await client.EvaluateExpressionAsync(
        new ExpressionEvaluationRequest
        {
            Expression = "= 1 + 2",
        });

    Console.WriteLine($"Result: {result.Result}");
}

GetAgentInstanceAsync(AgentInstanceKey, ConsistencyOptions?, CancellationToken)

public Task<AgentInstanceResult> GetAgentInstanceAsync(AgentInstanceKey agentInstanceKey, ConsistencyOptions<AgentInstanceResult>? consistency = null, CancellationToken ct = default)

Get agent instance Returns agent instance as JSON.

Parameter	Type	Description
agentInstanceKey	AgentInstanceKey
consistency	ConsistencyOptions<AgentInstanceResult>
ct	CancellationToken

Returns: Task<AgentInstanceResult>

Example

public static async Task GetAgentInstanceExample(AgentInstanceKey agentInstanceKey)
{
    using var client = CamundaClient.Create();

    var result = await client.GetAgentInstanceAsync(agentInstanceKey);
    Console.WriteLine($"Agent instance: {result.AgentInstanceKey}, status: {result.Status}");
}

GetFormByKeyAsync(FormKey, ConsistencyOptions?, CancellationToken)

public Task<FormResult> GetFormByKeyAsync(FormKey formKey, ConsistencyOptions<FormResult>? consistency = null, CancellationToken ct = default)

Get form by key Get a form by its unique form key.

Parameter	Type	Description
formKey	FormKey
consistency	ConsistencyOptions<FormResult>
ct	CancellationToken

Returns: Task<FormResult>

Example

public static async Task GetFormByKeyExample(FormKey formKey)
{
    using var client = CamundaClient.Create();

    var result = await client.GetFormByKeyAsync(formKey);
    Console.WriteLine($"Form: {result.FormId}, version: {result.Version}");
}

GetGlobalTaskListenerAsync(GlobalListenerId, ConsistencyOptions?, CancellationToken)

public Task<GlobalTaskListenerResult> GetGlobalTaskListenerAsync(GlobalListenerId id, ConsistencyOptions<GlobalTaskListenerResult>? consistency = null, CancellationToken ct = default)

Get global user task listener Get a global user task listener by its id.

Parameter	Type	Description
id	GlobalListenerId
consistency	ConsistencyOptions<GlobalTaskListenerResult>
ct	CancellationToken

Returns: Task<GlobalTaskListenerResult>

Example

public static async Task GetGlobalTaskListenerExample(GlobalListenerId globalListenerId)
{
    using var client = CamundaClient.Create();

    var result = await client.GetGlobalTaskListenerAsync(
        globalListenerId);

    Console.WriteLine($"Task listener: {result.EventTypes}");
}

GetStatusAsync(CancellationToken)

public Task GetStatusAsync(CancellationToken ct = default)

Get cluster status Checks the health status of the cluster by verifying if there's at least one partition with a healthy leader.

Parameter	Type	Description
ct	CancellationToken

Returns: Task

Example

public static async Task GetStatusExample()
{
    using var client = CamundaClient.Create();

    await client.GetStatusAsync();
    Console.WriteLine("Cluster is healthy");
}

GetSystemConfigurationAsync(CancellationToken)

public Task<SystemConfigurationResponse> GetSystemConfigurationAsync(CancellationToken ct = default)

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.

Parameter	Type	Description
ct	CancellationToken

Returns: Task<SystemConfigurationResponse>

Example

public static async Task GetSystemConfigurationExample()
{
    using var client = CamundaClient.Create();

    var result = await client.GetSystemConfigurationAsync();
    Console.WriteLine($"System config: {result}");
}

GetUserAsync(Username, ConsistencyOptions?, CancellationToken)

public Task<UserResult> GetUserAsync(Username username, ConsistencyOptions<UserResult>? consistency = null, CancellationToken ct = default)

Get user Get a user by its username.

Parameter	Type	Description
username	Username
consistency	ConsistencyOptions<UserResult>
ct	CancellationToken

Returns: Task<UserResult>

SearchAgentInstancesAsync(AgentInstanceSearchQuery, ConsistencyOptions?, CancellationToken)

public Task<AgentInstanceSearchQueryResult> SearchAgentInstancesAsync(AgentInstanceSearchQuery body, ConsistencyOptions<AgentInstanceSearchQueryResult>? consistency = null, CancellationToken ct = default)

Search agent instances Search for agent instances based on given criteria.

Parameter	Type	Description
body	AgentInstanceSearchQuery
consistency	ConsistencyOptions<AgentInstanceSearchQueryResult>
ct	CancellationToken

Returns: Task<AgentInstanceSearchQueryResult>

Example

public static async Task SearchAgentInstancesExample()
{
    using var client = CamundaClient.Create();

    var result = await client.SearchAgentInstancesAsync(new AgentInstanceSearchQuery());

    foreach (var instance in result.Items)
    {
        Console.WriteLine($"Agent instance: {instance.AgentInstanceKey}, status: {instance.Status}");
    }
}

SearchGlobalTaskListenersAsync(GlobalTaskListenerSearchQueryRequest, ConsistencyOptions?, CancellationToken)

public Task<GlobalTaskListenerSearchQueryResult> SearchGlobalTaskListenersAsync(GlobalTaskListenerSearchQueryRequest body, ConsistencyOptions<GlobalTaskListenerSearchQueryResult>? consistency = null, CancellationToken ct = default)

Search global user task listeners Search for global user task listeners based on given criteria.

Parameter	Type	Description
body	GlobalTaskListenerSearchQueryRequest
consistency	ConsistencyOptions<GlobalTaskListenerSearchQueryResult>
ct	CancellationToken

Returns: Task<GlobalTaskListenerSearchQueryResult>

Example

public static async Task SearchGlobalTaskListenersExample()
{
    using var client = CamundaClient.Create();

    var result = await client.SearchGlobalTaskListenersAsync(
        new GlobalTaskListenerSearchQueryRequest());

    foreach (var listener in result.Items)
    {
        Console.WriteLine($"Listener: {listener.Id}");
    }
}

SearchUsersAsync(UserSearchQueryRequest, ConsistencyOptions?, CancellationToken)

public Task<UserSearchResult> SearchUsersAsync(UserSearchQueryRequest body, ConsistencyOptions<UserSearchResult>? consistency = null, CancellationToken ct = default)

Search users Search for users based on given criteria.

Parameter	Type	Description
body	UserSearchQueryRequest
consistency	ConsistencyOptions<UserSearchResult>
ct	CancellationToken

Returns: Task<UserSearchResult>

UpdateAgentInstanceAsync(AgentInstanceKey, AgentInstanceUpdateRequest, CancellationToken)

public Task UpdateAgentInstanceAsync(AgentInstanceKey agentInstanceKey, AgentInstanceUpdateRequest body, CancellationToken ct = default)

Update agent instance Updates the mutable fields of an agent instance: status, metric counters, and tools. Metric values are treated as deltas and applied immediately to the aggregate counters. Tool updates replace the existing tool list. At least one of status, metrics, or tools must be provided.

Parameter	Type	Description
agentInstanceKey	AgentInstanceKey
body	AgentInstanceUpdateRequest
ct	CancellationToken

Returns: Task

Example

public static async Task UpdateAgentInstanceExample(AgentInstanceKey agentInstanceKey)
{
    using var client = CamundaClient.Create();

    await client.UpdateAgentInstanceAsync(
        agentInstanceKey,
        new AgentInstanceUpdateRequest
        {
            Status = AgentInstanceStatusEnum.THINKING,
            Metrics = new AgentInstanceMetricsDelta
            {
                InputTokens = 150,
                OutputTokens = 50,
                ModelCalls = 1,
            },
        });

    Console.WriteLine($"Updated agent instance: {agentInstanceKey}");
}

UpdateGlobalTaskListenerAsync(GlobalListenerId, UpdateGlobalTaskListenerRequest, CancellationToken)

public Task<GlobalTaskListenerResult> UpdateGlobalTaskListenerAsync(GlobalListenerId id, UpdateGlobalTaskListenerRequest body, CancellationToken ct = default)

Update global user task listener Updates a global user task listener.

Parameter	Type	Description
id	GlobalListenerId
body	UpdateGlobalTaskListenerRequest
ct	CancellationToken

Returns: Task<GlobalTaskListenerResult>

Example

public static async Task UpdateGlobalTaskListenerExample(GlobalListenerId globalListenerId)
{
    using var client = CamundaClient.Create();

    var result = await client.UpdateGlobalTaskListenerAsync(
        globalListenerId,
        new UpdateGlobalTaskListenerRequest
        {
            EventTypes = new List<GlobalTaskListenerEventTypeEnum> { GlobalTaskListenerEventTypeEnum.Completing },
            Type = "updated-task-listener",
        });

    Console.WriteLine($"Updated listener: {result.Id}");
}

UpdateUserAsync(Username, UserUpdateRequest, CancellationToken)

public Task<UserUpdateResult> UpdateUserAsync(Username username, UserUpdateRequest body, CancellationToken ct = default)

Update user Updates a user.

Parameter	Type	Description
username	Username
body	UserUpdateRequest
ct	CancellationToken

Returns: Task<UserUpdateResult>

Example

public static async Task UpdateUserExample(Username username)
{
    using var client = CamundaClient.Create();

    await client.UpdateUserAsync(
        username,
        new UserUpdateRequest
        {
            Name = "Jane Smith",
            Email = "jsmith@example.com",
        });
}

Cluster

GetBackpressureState()

public BackpressureState GetBackpressureState()

Current backpressure state snapshot.

Returns: BackpressureState

Example

public static void GetBackpressureStateExample()
{
    using var client = CamundaClient.Create();

    var state = client.GetBackpressureState();
    Console.WriteLine($"Severity: {state.Severity}, Permits: {state.PermitsMax}");
}

GetAuthenticationAsync(CancellationToken)

public Task<CamundaUserResult> GetAuthenticationAsync(CancellationToken ct = default)

Get current user Retrieves the current authenticated user.

Parameter	Type	Description
ct	CancellationToken

Returns: Task<CamundaUserResult>

Example

public static async Task GetAuthenticationExample()
{
    using var client = CamundaClient.Create();

    var result = await client.GetAuthenticationAsync();
    Console.WriteLine($"Authenticated user: {result.Username}");
}

GetLicenseAsync(CancellationToken)

public Task<LicenseResponse> GetLicenseAsync(CancellationToken ct = default)

Get license status Obtains the status of the current Camunda license.

Parameter	Type	Description
ct	CancellationToken

Returns: Task<LicenseResponse>

Example

public static async Task GetLicenseExample()
{
    using var client = CamundaClient.Create();

    var result = await client.GetLicenseAsync();
    Console.WriteLine($"License type: {result.LicenseType}");
}

GetTopologyAsync(CancellationToken)

public Task<TopologyResponse> GetTopologyAsync(CancellationToken ct = default)

Get cluster topology Obtains the current topology of the cluster the gateway is part of.

Parameter	Type	Description
ct	CancellationToken

Returns: Task<TopologyResponse>

Example

public static async Task GetTopologyExample()
{
    using var client = CamundaClient.Create();

    var topology = await client.GetTopologyAsync();
    Console.WriteLine($"Cluster size: {topology.ClusterSize}");
}

PinClockAsync(ClockPinRequest, CancellationToken)

public Task PinClockAsync(ClockPinRequest body, CancellationToken ct = default)

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.

Parameter	Type	Description
body	ClockPinRequest
ct	CancellationToken

Returns: Task

Example

public static async Task PinClockExample()
{
    using var client = CamundaClient.Create();

    await client.PinClockAsync(new ClockPinRequest
    {
        Timestamp = 1700000000000,
    });
}

ResetClockAsync(CancellationToken)

public Task ResetClockAsync(CancellationToken ct = default)

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.

Parameter	Type	Description
ct	CancellationToken

Returns: Task

Example

public static async Task ResetClockExample()
{
    using var client = CamundaClient.Create();

    await client.ResetClockAsync();
}

Resources

DeployResourcesFromFilesAsync(string[], string?, CancellationToken)

public Task<ExtendedDeploymentResponse> DeployResourcesFromFilesAsync(string[] resourceFilePaths, string? tenantId = null, CancellationToken ct = default)

Deploy resources from local filesystem paths. Reads the specified files, infers MIME types from their extensions, and calls with the loaded content.

Parameter	Type	Description
resourceFilePaths	String[]	Absolute or relative file paths to BPMN, DMN, form, or resource files.
tenantId	String	Optional tenant ID for multi-tenant deployments.
ct	CancellationToken	Cancellation token.

Returns: Task<ExtendedDeploymentResponse> — An with typed access to deployed artifacts.

Example

public static async Task DeployResourcesFromFilesExample()
{
    using var client = CamundaClient.Create();

    var result = await client.DeployResourcesFromFilesAsync(
        ["process.bpmn", "decision.dmn"]);
    Console.WriteLine($"Deployment key: {result.DeploymentKey}");
}

DeleteResourceAsync(ResourceKey, DeleteResourceRequest, CancellationToken)

public Task<DeleteResourceResponse> DeleteResourceAsync(ResourceKey resourceKey, DeleteResourceRequest body, CancellationToken ct = default)

Delete resource Deletes a deployed resource. This can be a process definition, decision requirements definition, or form definition deployed using the deploy resources endpoint. Specify the resource you want to delete in the resourceKey parameter.

Once a resource has been deleted it cannot be recovered. If the resource needs to be available again, a new deployment of the resource is required.

By default, only the resource itself is deleted from the runtime state. To also delete the historic data associated with a resource, set the deleteHistory flag in the request body to true. The historic data is deleted asynchronously via a batch operation. The details of the created batch operation are included in the response. Note that history deletion is only supported for process resources; for other resource types this flag is ignored and no history will be deleted.

Parameter	Type	Description
resourceKey	ResourceKey
body	DeleteResourceRequest
ct	CancellationToken

Returns: Task<DeleteResourceResponse>

Example

public static async Task DeleteResourceExample(ResourceKey resourceKey)
{
    using var client = CamundaClient.Create();

    await client.DeleteResourceAsync(
        resourceKey,
        new DeleteResourceRequest());
}

GetResourceAsync(ResourceKey, ConsistencyOptions?, CancellationToken)

public Task<ResourceResult> GetResourceAsync(ResourceKey resourceKey, ConsistencyOptions<ResourceResult>? consistency = null, CancellationToken ct = default)

Get resource Returns a deployed resource.

info

This endpoint does not return BPMN process definitions, DMN decision definitions, or form resources. To query BPMN process definitions or DMN decision definitions, use their respective APIs.

Parameter	Type	Description
resourceKey	ResourceKey
consistency	ConsistencyOptions<ResourceResult>
ct	CancellationToken

Returns: Task<ResourceResult>

GetResourceContentAsync(ResourceKey, ConsistencyOptions