Skip to main content
Version: 8.8 (unreleased)

Overview

Welcome to the Camunda Orchestration Cluster API​

The Orchestration Cluster API lets you interact programmatically with process orchestration capabilities in Camunda 8. You can use it to start, manage, and query process instances. It also lets you complete user tasks, resolve incidents, and manage variables, at scale and with confidence.

You can use this API to:

  • Build process-driven applications
  • Integrate Camunda's User Tasks into custom task UIs
  • Start and monitor processes from external systems

This API is designed to make it easy to find resources with a consistent experience, while ensuring all endpoints are secure with authentication and fine-grained resource authorization.

We're committed to delivering high performance and reliability with our APIs. This API is part of the Camunda 8 public API and is covered by our SemVer stability guarantees (except for clearly marked alpha endpoints).

To learn more about orchestration clusters, see What is an Orchestration Cluster?.

Ready to dive in? Head to Getting started section below to make your first API call.

Getting started​

This section helps you get up and running in minutes. To begin using the Orchestration Cluster API, you'll need the following:

Prerequisites​

  • A Camunda 8 Orchestration Cluster
  • Authentication
    • For local development, authentication is optional. For production or shared environments, authentication is required. See Authentication for supported methods and setup instructions.
  • A client to send API requests

Once you’re set up, try your first call using Postman or curl: Get cluster topology to confirm your setup is working.

Explore the API​

If you're just getting started, try these next steps:

Authorize your requests​

Authentication for the Orchestration Cluster API depends on your environment and how you deploy Camunda 8. Supported authentication methods include No Authentication (for local development), Basic Authentication, OIDC Access Tokens.

  • See the Authentication support matrix for details on which authentication methods are supported for each distribution (C8 Run, Docker Compose, Helm/Kubernetes, SaaS).
  • For advanced security, OIDC with X.509 client certificates is supported in Self-Managed environments and handled by the Java client. See OIDC with X.509.

When authentication is enabled, all API requests must include a valid access token. These tokens are short-lived and must be refreshed periodically depending on your client configuration. If you're using the Java or Spring clients, token handling can be configured easily.

To learn how to authenticate, follow the step-by-step guide in Authentication based on your setup (SaaS or Self-Managed).

Context paths​

SaaS​

In the Camunda Console, go to your cluster, and in the Cluster Details, find your Region Id and Cluster Id. Use this pattern as your ${BASE_URL}: https://${REGION_ID}.zeebe.camunda.io/${CLUSTER_ID}/v2/

Self-Managed​

Use the host and path defined in your Zeebe Gateway configuration. If you’re using the default setup, the ${BASE_URL} is: http://localhost:8080/v2/

Versioning​

Camunda uses semantic versioning (SemVer) to ensure that API changes are predictable and compatible. This helps you safely upgrade without unexpected breaking changes.

The API version is defined by the API version number (v2) and the product version, for example, POST /v2/user-tasks/search in Camunda 8.8.0.

Camunda versions the entire API rather than individual endpoints. If a breaking change occurs in any endpoint, the entire API is versioned. During migration periods, multiple API versions will coexist - for example, both v2 and v3 versions of /user-tasks/search may be available in the same product release.

note

Adding new endpoints or attributes to existing responses is not considered a breaking change.

API structure and conventions​

Request size limits​

The default maximum request size for deployment-related requests (such as POST /v2/deployments) is 4MB.

Naming conventions​

Naming is simple, intuitive, and consistent across the Orchestration Cluster API to reduce friction when working across multiple endpoints.

The API overall applies the following naming conventions:

  • Nouns over verbs, for example, assignment over assign.
  • Plural terms for top-level resources, for example, user-tasks.
  • Kebab-case for multiple words in path parameters, and a hyphen (-) where a space would exist, for example, user-tasks.
  • camelCase for multiple words in query parameters. Camunda capitalizes the first letter of words after the first. The first letter in the first word is lowercase, for example, userTaskKey.

These conventions can be observed in the following endpoint example:

POST /user-tasks/{userTaskKey}/assignment

For IDs or similar short 2- or 3-letter words or acronyms, Camunda only capitalizes the first letter. If standalone, all letters are lowercase.

TermUsage
IDid (standalone) or processDefinitionId
URLurl (standalone) or externalUrl
UUIDuuid (standalone) or clusterUuid

Identifiers follow a naming rule in parameters and data attributes alike:

  • Unique technical identifiers are suffixed with key, for example, userTaskKey, processInstanceKey, or userKey. These are numeric values in most cases.
  • Other identifiers, such as copied identifiers from the BPMN XML, may be arbitrarily named but are usually suffixed with id, for example, processDefinitionId.
  • Key and id fields contain the entity as a prefix, for example, userTaskKey or processDefinitionId. This also applies when referencing other resources like formKey in the user task entity and the respective entities themselves like userTaskKey in the user task entity.
  • The full entity is the prefix to avoid confusion, for example, processDefinitionKey instead of processKey; the latter could be interpreted as process instance or process definition.
  • Other attributes of entities have no prefix to avoid clutter, such as version in the process definition entity. However, other resources have to be referenced with a prefix, like processDefinitionVersion in the process instance entity.

HTTP status codes & error handling​

The Orchestration Cluster API uses standard HTTP status codes and returns error responses following the RFC 9457 format. This format ensures consistency across endpoints and simplifies error parsing and handling.

Each error response includes the following fields:

  • type: A URI identifier for the error type
  • status: The HTTP status code (e.g., 400, 404)
  • title: A short, human-readable summary of the error
  • detail: A more detailed explanation of the issue
  • instance: A URI reference identifying the specific occurrence of the problem

Common error codes​

Error codeMeaning
200OK
204No content
400Bad request. Generic error that contains further description in the problem detail.
401Unauthorized. The client is not authenticated yet. The client should try again with a modified authorization header.
403Forbidden. The client has incorrect or insufficient permissions for the request.
404Not found
409Conflict. The request is trying to modify a resource that is currently not in the right state.
412Precondition failed. The client should check the cluster status.
429Rate limit exceeded. The client exceeds a defined limit of requests, for example, Zeebe signaling backpressure due to more requests than the broker can currently process.
500Internal server error. Generic error that contains further description in the problem detail.

Date formats​

Date values in the Orchestration Cluster API follow the RFC 3339 notation. This includes all requests and responses. The endpoints validate requests and transform responses accordingly.

Variables​

Variables in the Orchestration Cluster API are JSON objects, where the key defines the variable name and the value specifies the variable value.

For full details on variable filtering and structure, see search requests.

What's next?​

Now that you're familiar with the Orchestration Cluster API, here are some useful next steps: