Camunda REST API: how to use Camunda API in automations

How can an external application communicate with Camunda, and which interface should an enterprise team choose? That is the practical question behind many searches for the camunda REST API. The answer is not simply “send an HTTP request.” Teams must align the right API with the Camunda version, deployment model, authentication requirements, transaction volume, and ownership boundaries between systems.

This article focuses on Camunda 8 and explains REST integration from an implementation and architecture perspective. It covers where the API fits within process orchestration, which endpoint categories matter most, how to authenticate requests, how to start a process from an external system, and when a Zeebe client may be a better fit. It also addresses reliability, observability, Camunda 7 migration, and the criteria required to move an integration into production.

These decisions should be understood within the broader context of Camunda and process orchestration. In complex environments, the platform coordinates applications, APIs, microservices, people, and increasingly AI-enabled capabilities. The move toward agentic orchestration makes it even more important to establish an integration layer that is controlled, observable, and governable, without turning the API into a difficult-to-evolve coupling point.

In short: the Camunda REST API can be an effective entry point for integrating applications with Camunda 8, but interface selection, access control, failure handling, and operational ownership must be treated as architecture decisions.

What it is and where it fits in Camunda 8

The REST API is the HTTP interface that allows applications, services, administrative tools, and enterprise platforms to interact programmatically with Camunda 8 orchestration capabilities. Depending on the resources available in the selected version and environment, it can be used to deploy processes, start and query instances, manage variables, operate user tasks, search process information, and handle incidents. Current documentation describes the Orchestration Cluster REST API as an interface for managing and interacting with Camunda 8 orchestration clusters .

Two concepts should be kept separate. Orchestration is the platform capability that coordinates flows, rules, waits, events, services, and human work. The API is the access mechanism for part of that capability. Therefore, the API does not replace the BPMN process, define the entire integration architecture, or serve as a substitute for domain logic owned by enterprise systems.

A simplified architecture can be represented as follows:

External application / CRM / portal / legacy system | | HTTPS + authentication + controlled payload v Camunda 8 Orchestration Cluster REST API | v BPMN processes, instances, user tasks, variables, and incidents | v Workers, enterprise APIs, microservices, people, and AI services

This layer is used by application developers, platform engineers, integration teams, solution architects, and DevOps professionals. Each group may have a different requirement: a portal starts a process; an operations tool queries incidents; middleware transforms data; a platform team automates deployments; or a custom application presents human tasks.

When BPMN appears in this architecture, it represents the process execution model. Readers who need to understand that foundation before the integration layer can consult what is BPMN.

Does Camunda 8 have a REST API?

Yes. Camunda 8 provides REST capabilities, and current documentation presents the Orchestration Cluster REST API as an interface for starting, managing, querying, and monitoring orchestration resources. In recent versions, endpoint organization is evolving toward a more unified experience, with versioned paths—such as resources under /v2—and a consistent approach to search, authentication, and authorization .

The answer does not mean that teams can copy old examples without checking the version. Resource names, payload formats, authentication models, and endpoint availability may vary across releases, Camunda SaaS, Self-Managed, Camunda 8 Run, and legacy components. 

Before implementation, confirm the camunda 8 api documentation that applies to the target release and deployment model.

Camunda 7 versus Camunda 8

From an integration perspective, Camunda 7 and Camunda 8 should not be treated as interchangeable versions of the same API. Camunda 7 historically exposed REST endpoints associated with the engine and platform resources. Camunda 8 introduces a distributed architecture based on Zeebe and is consolidating interfaces around the Orchestration Cluster REST API, while also providing clients and APIs for different interaction patterns.

The following table summarizes the differences that most affect integration teams. It is a starting point, not a replacement for the documentation of the installed release.

Migration should therefore not begin with BPMN model conversion alone. The team should inventory called endpoints, custom REST clients, operational scripts, credentials, IDs stored in external systems, integrations tied to engine-specific behavior, reporting tools, and automated tests. The plan should include integration and operational testing, not only process execution tests. 

NT Consult’s guide to Camunda 7 to 8 migration provides additional context.

Key endpoints and enterprise use cases

A long endpoint catalog is less useful than an organization based on intent. The primary question should be: what outcome does the application need from Camunda? Exact names and fields must be confirmed in the camunda REST API documentation for the applicable release.

This approach connects camunda api integration to a business outcome. Instead of creating a client that knows every resource, the team defines a clear boundary: which operations are required, which data crosses the boundary, and which actions remain the responsibility of Camunda or the source system.

Process definitions and process instances

The first group of resources allows an application to discover a deployed process definition and start an instance. The scenario is common: a customer portal completes a request; a CRM qualifies an opportunity; a claims system accepts a notification; or a telecom platform confirms a provisioning event. The external application calls Camunda, sends the required data, and receives an identifier for correlation and follow-up.

The conceptual flow is to identify the process definition and version, send a request to create the instance, include only the required variables, store the process identifier together with the business identifier, and provide a strategy for status tracking through polling, events, callbacks, or a separate status service. Current documentation lists POST /v2/process-instances among the Orchestration Cluster REST API reference endpoints .

For example, consider a customer onboarding portal. After the customer submits the minimum information and the system validates eligibility, the portal starts an onboarding process in Camunda. Camunda coordinates checks, risk-service calls, human approval when necessary, and notifications. The portal does not need to understand the complete sequence; it needs a reliable correlation identifier and an appropriate status interface.

Process variables should not become an indiscriminate data repository. Full documents, secrets, personal data that is not required for execution, and large downstream responses should remain in appropriate systems, with a secure reference stored in the process when necessary. The payload should carry the minimum data required for the next decision, while the source system remains the owner of the data whenever that is the correct domain responsibility.

User tasks, variables, incidents, and operational data

Operational integrations commonly combine four needs: interacting with human work, querying process state, accessing permitted variables, and investigating failures. A custom application may display a task queue for a specific operation, while a support tool may show that an instance is waiting because an external dependency is unavailable.

Current Camunda 8 documentation includes user-task operations, variable management, advanced search, and incident resolution among the capabilities of the Orchestration Cluster REST API . However, teams should not assume that every resource previously exposed by Operate, Tasklist, Optimize, or component APIs has immediate parity in every version and deployment. When a capability is not exposed through the selected REST interface, use the officially recommended client, API, or component for that use case.

This distinction is critical when designing an operational application. An interface that queries process state should not automatically assume responsibility for modifying business data. Similarly, completing a user task may require specific authorization, domain validation, and an audit record identifying the responsible user. In high-criticality environments such as financial services, insurance, and digital infrastructure, operational visibility must be linked to an explicit authorization and audit model.

For a perspective on Camunda in a complex operational environment, see the NASA Camunda case study. The case study provides context about complexity, scale, and operational demands; it should not be presented as evidence of a specific REST implementation unless the source explicitly supports that claim.

Authentication and secure access

Authentication is not a configuration detail to postpone until after the first prototype. It determines how an application proves its identity, how tokens are obtained and renewed, which permissions are granted, where secrets are stored, and how access is separated across development, staging, and production.

The model depends on the deployment. Current documentation indicates that Camunda 8 SaaS requires OIDC-based authentication; Helm uses Basic Authentication by default, with configuration options; and Camunda 8 Run or Docker Compose may run without authentication by default for local development . This flexibility is useful, but it also creates risk: a request that works on localhost without credentials does not demonstrate that the integration is ready for a production cluster.

How authentication works

In an OIDC-based flow, the application obtains client credentials from the identity provider, requests an access token, and sends that token in the Authorization header as a Bearer Token. The authenticated identity must also have the required authorization for the requested resource. In other words, authentication answers who is calling; authorization answers what that identity is allowed to do.

A secure design keeps client secrets out of source code and repositories. Use a secret manager, limit scope, rotate credentials, log failures without exposing tokens, and maintain separate configurations for each environment. In Java and Spring applications, official clients can automate token acquisition and renewal; for manual calls, the team must implement the token lifecycle correctly .

For Self-Managed environments, validate the identity provider, audience, scopes, certificates, and gateway configuration. For SaaS, confirm the URLs, client credentials, and permissions for the relevant environment. NT Consult’s Camunda services provide a starting point for organizations that need to turn these decisions into a sustainable operating architecture.

Common authentication mistakes

When the first request fails, troubleshooting should separate credentials, environment, authorization, and request construction. Common problems include:

• Invalid, expired, or revoked credentials;
• Incorrect audience, scope, or authorization configuration;
• A cluster, base URL, or environment mismatch;
• A missing, malformed, or incorrectly routed Authorization header;
• Permissions that are broader than necessary or insufficient for the resource;
• A secret embedded in source code, logs, pipelines, or versioned configuration;
• A difference between the identity used locally and the identity used by the production workload.

Before expanding permissions, confirm the endpoint, version, host, token, and authorization policy. In particular, a 403 Forbidden response may indicate that authentication succeeded but the token subject lacks the required authorization. A specialized review of Camunda services can help prevent the use of excessive privileges as a workaround.

How to make the first API call

The first test should be small, version-aware, and observable. Its purpose is not to prove every business scenario, but to confirm the basic sequence: obtain credentials, reach the correct endpoint, send a valid request, interpret the response, and record correlation information without exposing sensitive data.

H3: First request with cURL or an API client

For a local connectivity test, the documentation provides a topology query. In Camunda 8 Run or Docker Compose with authentication disabled for local development, the structure may look like this:

curl --request GET \ --url "${CAMUNDA_BASE_URL}/v2/topology" \ --header "Accept: application/json"

In environments that require a Bearer Token, add the authorization header:

curl --request GET \ --url "${CAMUNDA_BASE_URL}/v2/topology" \ --header "Accept: application/json" \ --header "Authorization: Bearer ${ACCESS_TOKEN}"

Use placeholders for the URL and token. Never replace them with real credentials in a tutorial, pipeline, or repository. The validated example reflects the current Camunda 8.9 documentation, but teams should confirm the method and path for their own release . A 2xx status indicates successful processing; 4xx responses generally point to request, authentication, or authorization issues; and 5xx responses require investigation of the service, gateway, or a dependency. 

The HTTP status, error body, request ID, and environment context should be logged securely.

Starting a process from an external system

Starting a process follows a similar pattern, but the payload represents a business intent. Consider a CRM that changes an opportunity to “ready for provisioning.” The CRM calls a process-instance endpoint; Camunda receives an opportunity reference, service type, customer identifier, and the minimum data required for the next steps; and the CRM persists the relationship between the opportunity ID and the process-instance ID.

An illustrative payload, which must be adjusted and validated against the contract of the selected release, could look like this:

curl --request POST \ --url "${CAMUNDA_BASE_URL}/v2/process-instances" \ --header "Authorization: Bearer ${ACCESS_TOKEN}" \ --header "Content-Type: application/json" \ --data '{ "processDefinitionId": "service-provisioning", "variables": { "businessKey": "CRM-12345", "customerId": "customer-987", "serviceType": "fiber" } }'

The example is intentionally illustrative: field names, identifiers, and response properties must be verified against the OpenAPI specification for the selected release. The application should inspect the returned identifier, associate it with the business identifier, and decide whether follow-up will use controlled polling, events, a callback, or a dedicated status service.

The integration boundary must also define what happens when Camunda is unavailable, when a downstream system rejects the operation, or when the request is repeated. A queue or middleware layer may absorb transient unavailability; an idempotency key or deduplication strategy may prevent duplicate activations; and an exception path may route the case to human review. For scenarios that combine orchestration with intelligent services, see integrating Camunda and AI workflow automation.

REST versus the Camunda Zeebe API

REST and Zeebe are not synonyms. Both can enable interaction with the Camunda 8 ecosystem, but they address different needs. The camunda zeebe api generally refers to APIs and clients associated with Zeebe, including the gateway model and official clients. REST provides HTTP interoperability and is accessible to almost any application; Zeebe clients and workers may fit better with command, job, and high-volume execution patterns.

The choice should consider latency, throughput, communication style, available languages, operating model, observability, and official support for the selected version. There is no universally superior interface, only a better fit for a given architectural boundary. 

NT Consult’s Camunda vs n8n comparison can help teams evaluating automation models, but the REST-versus-Zeebe decision should remain grounded in the Camunda 8 technical contract.

Camunda REST API: when REST is the better fit

The REST API is often a good fit when the source system already communicates through HTTP, when the integration must pass through an API gateway, or when a simple application does not justify introducing a dedicated client. It is also attractive for language-independent integrations, selected query and administrative use cases, and custom tools built on supported REST resources.

Favorable criteria include interoperability, easy inspection through cURL or Postman, alignment with enterprise gateway policies, and a clear separation between the consuming application and the cluster. Transport simplicity does not remove the need to control timeouts, retries, authentication, authorization, payloads, and correlation.

When Zeebe clients or other interfaces may be preferable

A Zeebe client or another officially supported mechanism may be preferable when the interaction is oriented around workers, jobs, and execution commands; when the workload has strong throughput or latency requirements; or when the application already uses official libraries that automate connection and authentication. For long-running processes, the architecture may separate the command that starts a journey from the asynchronous work performed by specialized workers.

The decision also depends on the release. The Camunda 8 API surface continues to evolve, and Camunda is consolidating resources that were previously distributed across component APIs. Teams should therefore test the selected pattern against the documentation and official client for the target release instead of assuming immediate parity among REST endpoints, RPCs, and component resources.

Practical external-system integration patterns

An isolated HTTP call rarely represents a real enterprise integration. The design should identify the systems involved, communication direction, Camunda’s responsibility, failure behavior, and operational indicators. That is the difference between a prototype that works under ideal conditions and a camunda api integration that can withstand change, unavailability, and growth.

Integrating a CRM, ERP, or legacy application

In a common pattern, the CRM or ERP owns customer, order, or contract data while Camunda coordinates a sequence spanning multiple domains. An API gateway or middleware layer can handle authentication, transformation, rate limiting, and routing. Camunda invokes specialized services through workers or connectors, and each system remains responsible for its own domain transaction.

The choice between synchronous and asynchronous communication should reflect the expected duration of the work. A fast validation may be synchronous; provisioning, approval, legacy integration, or event waiting generally benefit from an asynchronous model. Correlation IDs should follow the journey without replacing the business identifier. The process should retain enough context to operate, but it should not duplicate the entire ERP database.

This pattern reduces coupling when Camunda coordinates the flow without assuming responsibilities that belong to the CRM, ERP, or legacy system. It also improves testing: each boundary contract can be validated independently while the process is tested with success, timeout, rejection, and unavailability responses. For architecture and implementation decisions, consider Camunda services.

Connecting AI services and AI-enabled workflows

When a process calls an AI service, the architecture must control more than availability and response format. Deterministic logic should remain explicit: eligibility rules, approval limits, segregation of duties, and termination conditions should not depend exclusively on a probabilistic response.

Camunda can coordinate the AI service, create human-review checkpoints, record the decision, enforce authorization, and define a fallback path. In a claims process, for example, a model may classify documents or suggest a risk level; the process can route cases above a threshold to an analyst, block unauthorized actions, and require confirmation before a financial consequence is triggered.

The architecture should answer concrete questions: which data can the service access; which action can it request; how is the output audited; what happens when the response is inconsistent; and how does the process continue when the model is unavailable? AI is not merely another API: it increases the importance of governance, observability, and recovery. NT Consult’s article on integrating Camunda and AI workflow automation explores this topic in greater depth.

Designing reliable production integrations

A production-ready integration must behave predictably under imperfect conditions. The team should measure workload behavior, test failure scenarios, review the identity model, and define production support ownership. In regulated environments, evidence of control, traceability, and team stability matters as much as functional validation.

The NASA Camunda case study provides context about orchestration in a complex environment. Its value is in reinforcing the need for reliability and governance in critical operations; specific REST API outcomes should only be attributed when documented by the source.

Retries, idempotency, and error handling

A distributed integration must distinguish transient failures from permanent failures. A timeout, temporary unavailability, or network error may justify a bounded retry; an invalid payload, insufficient permission, or rejected business rule generally requires correction or routing rather than automatic repetition.

A retry policy should include limits, backoff, and jitter to avoid a request storm. The application must also control duplicate-request risk: a lost response after the server has processed the call may cause the client to send the same operation again. Use an idempotency strategy supported by the contract or implement deduplication with a business key, request registry, and appropriate transactional state.

Log correlation IDs, status, latency, failure type, and process stage, but never log tokens, passwords, or sensitive data unnecessarily. Around Camunda, a queue, dead-letter queue, compensation flow, or exception-handling path can separate a technical failure from an operational decision. This level of design is part of Camunda services, not an afterthought.

Scalability and performance considerations

There is no universal requests-per-second figure that determines whether an integration is scalable. Results depend on the environment, payload size, network, gateway, authentication, concurrency, and downstream dependencies. The team should measure its own workload and validate documented limits for the applicable deployment.

The test plan should observe request volume, concurrency, payload size, network latency, dependency response time, token-acquisition overhead, timeout behavior, queue depth, CPU and memory use, and total process duration. Load and failure tests should be completed before rollout, with explicit acceptance criteria.

Performance evaluation must remain connected to business value: a fast integration that creates duplicates, outages, or high operating costs is not a successful outcome. NT Consult’s article on Camunda platform: how to achieve a high ROI helps connect architectural quality with sustainable return.

Monitoring and observability

Monitoring HTTP status codes alone is insufficient. Operations teams need to connect API behavior to process impact: how many instances were affected, which stages are accumulating incidents, which dependency is causing timeouts, and which client is generating authorization failures.

A strong strategy combines structured logs, request IDs, correlation IDs, latency and error-rate metrics, authentication-failure counts, process-level indicators, alerts, and distributed tracing where supported by the architecture. Dashboards should allow operators to navigate from an integration failure to the affected instance and business impact without exposing data they are not authorized to view.

When AI services participate in the workflow, monitor integration availability, process behavior, and the operational quality of responses separately. Record human review, fallback paths, rejections, and assisted decisions. The orchestration layer should make operations explainable and recoverable, not merely automated. For long-term platform support, see Camunda services.

Migration considerations from Camunda 7 to 8

For organizations still running Camunda 7 Community Edition, the October 2025 end of life is no longer a future risk: it is an unsupported-platform reality. Camunda 7 Enterprise Edition has an extended security-support date through April 2030, but no new features will be added. For most organizations, the question is no longer whether migration is necessary, but when and how it should be executed .

Migration should address integration incompatibilities before processes are moved. Endpoints, authentication, identifiers, reporting, and assumptions about engine behavior may break even when a BPMN model appears equivalent. The plan should include discovery, prioritization, contract testing, load testing, coexistence where necessary, and a support strategy.

What integration teams should inventory before migration

Before selecting a technical path, the team should create a verifiable inventory of assets that depend on Camunda 7. The minimum scope includes:

• REST endpoints called by applications, jobs, scripts, and tools;
• Custom REST clients and libraries embedded in products;
• Credentials, identity providers, proxies, and authorization rules;
• External applications that store process IDs, business keys, or task IDs;
• Integrations tied to engine-specific behavior;
• Monitoring, reporting, audit, and support tools;
• Automated tests that depend on legacy responses, status codes, or payloads.

The inventory should record owner, criticality, frequency, dependencies, data exchanged, and expected failure behavior. The organization can then prioritize critical integrations, define replacements, and execute the Camunda 7 to 8 migration strategy based on evidence rather than assumptions.

Architecture checklist before production

Before recommending the solution to technology leadership, the team should be able to answer the questions below with documented evidence, test results, and named owners. The purpose is not to repeat every endpoint, but to validate whether the integration is sustainable.

• Which Camunda 8 capabilities does the application actually require?
• Is REST the appropriate interface for each interaction, or would a Zeebe client or worker better fit part of the flow?
• How will authentication, authorization, and credential rotation work in every environment?
• Where will secrets be stored, and how will access be audited?
• Which system owns each piece of business data?
• What happens when Camunda or a downstream dependency is temporarily unavailable?
• How will duplicate requests be detected or neutralized?
• Which logs, metrics, traces, and alerts will show operational impact?
• How will version and contract changes be tested?
• Which volume, concurrency, and latency targets must be validated?
• Does the solution create unnecessary coupling with legacy systems?
• Who owns production support for the integration?

If some answers are simply “we will find out later,” the architecture is not ready for production. A review with Camunda services specialists can help turn the checklist into decisions, tests, and an operating model.

Camunda REST API: Building a Production-Ready Integration Strategy

The camunda REST API is an important integration layer for connecting Camunda 8 with portals, CRMs, ERPs, legacy systems, operational tools, and enterprise services. Consistent implementation begins with architecture: define the required capabilities, select REST or Zeebe according to the interaction pattern, secure access, limit the data crossing the boundary, and establish how failures, duplicates, and version changes will be handled.

Feasibility must be tested in the organization’s actual environment, including enterprise security requirements, volume, latency, downstream dependencies, data ownership, and support responsibility. For organizations that still depend on Camunda 7 integrations, migration should be treated as an active risk, with inventory and integration testing completed before process changes.

The next stage of enterprise orchestration also includes AI capabilities and agents. The challenge is not merely to add AI to automation, but to ensure that deterministic workflows, AI-assisted decisions, enterprise systems, and human interactions remain observable, secure, governable, and recoverable. A well-designed API and disciplined orchestration layer are fundamental to that evolution.

If your organization has validated Camunda 8 conceptually and needs to define its API strategy, plan a migration, or implement a production-grade integration. Explore NTConsult Camunda services. The conversation should begin with the requirements, risks, and evidence from your environment—not with a generic promise of automation.