@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-data-fetching.user-task-support-advanced-search-filters.md

@@ -0,0 +1,44 @@
+# Data fetching — User task support — Advanced search filters
+
+To provide an easy yet expressive way for users to search for and filter resources, search requests can contain more advanced filter criteria than fields being _equal_ to a target value.
+
+For example, this allows searching using logical (and, in) and comparison operators (greater than, less than). The list of generally supported advanced filter operators is described below. The supported operators depend on the endpoint and the type of the filter attribute. All endpoints document available operators for each attribute in the Orchestration Cluster REST API specification.
+
+#### Conditional Operators
+
+| Operator  | Syntax                                         | Description                                                                                                                                                                                                                      |
+| --------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `$eq`     | `field: { "$eq": value }`                      | Filter where `field` is equal to `value`. Abbreviated form `field: value` is also allowed.                                                                                                                                       |
+| `$neq`    | `field: { "$neq": value }`                     | Filter where `field` is not equal to `value`.                                                                                                                                                                                    |
+| `$exists` | `field: { "$exists": value }`                  | Filter where `field` does or does not exist. The `value` is a boolean and can be either `true` or `false`.                                                                                                                       |
+| `$gt`     | `field: { "$gt": value }`                      | Filter where `field` is greater than `value`.                                                                                                                                                                                    |
+| `$gte`    | `field: { "$gte": value }`                     | Filter where `field` is greater than or equal to `value`.                                                                                                                                                                        |
+| `$lt`     | `field: { "$lt": value }`                      | Filter where `field` is less than `value`.                                                                                                                                                                                       |
+| `$lte`    | `field: { "$lte": value }`                     | Filter where `field` is less than or equal to `value`.                                                                                                                                                                           |
+| `$like`   | `field: { "$like": value }`                    | Filter where `field` contains a string like `value`. The wildcard characters `*` (zero, one, or multiple characters) and `?` (a single character) are allowed in `value`. They can be escaped with a backslash, like in `my \*`. |
+| `$in`     | `field: { "$in": [ value1, value2, ... ] }`    | Filter where `field` is equal to at least one of the `value`s in the provided array.                                                                                                                                             |
+| `$notIn`  | `field: { "$notIn": [ value1, value2, ... ] }` | Filter where `field` is not equal to any one of the `value`s in the provided array.                                                                                                                                              |
+
+Example
+
+```
+POST /v2/user-tasks/search
+
+{
+  "filter": {
+    "candidateGroups": { "$like": "external-*", "$neq": "external-supervisor" }
+  }
+}
+```
+
+This filters by `candidateGroups` that start with `"external-"` but do not match `"external-supervisor"`.
+
+#### Logical Operators
+
+| Operator | Syntax                                                        | Description                                                                                                                   |
+| -------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `$or`    | `"$or": [ { condition1 }, { condition2 }, ... ]`              | Filter where at least one of the conditions is true.                                                                          |
+| and      | `{ field: { "$lt": value1 }, field: { "$gt": value2 }, ... }` | All conditions outside of `$or` operators will be considered as combined by an `AND` operator. There is no explicit operator. |
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-data-fetching

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-data-fetching.user-task-support-filter.md

@@ -0,0 +1,21 @@
+# Data fetching — User task support — Filter
+
+The filter object defines which fields should match. Only items that match the given fields will be returned. The available fields vary by object and are described in the respective search endpoint. Filtering by a unique identifier is usually available in filtering options. Beyond that, the filter options don’t have to comprise all the returned items’ attributes.
+
+Example
+
+```
+POST /v2/user-tasks/search
+
+{
+  "filter": {
+    "assignee": "demo",
+    "processInstanceKey": "22456786958"
+  }
+}
+```
+
+This filters by the attributes `assignee` and `processInstanceKey`, looking for exact matches with the provided values.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-data-fetching

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-data-fetching.user-task-support-page.md

@@ -0,0 +1,30 @@
+# Data fetching — User task support — Page
+
+The page object details how to slice the result set. An initial search request can omit the page object or define the `limit`. This specifies the maximum number of results to retrieve per request. Subsequent requests can either use **cursor** or **offset pagination** to iterate through the result set.
+
+Cursor pagination bases on the value of the [search response's](#search-responses) `startCursor` and `endCursor`. Copy `startCursor` into `before` or `endCursor` into `after` to page through results respectively. The [search example](#search-example) showcases how to use these attributes for cursor pagination.
+
+Offset pagination uses the `from` attribute to define the starting point of the next set of items in the overall result set.
+
+**Note**
+Choosing the right pagination type depends on the specific use case. The expected result set size and intended usage of the results have the biggest influence. The expected reliability and performance of the search request affect this decision as well.
+
+Consider using cursor pagination for larger result sets and displaying result list that scroll infinitely.
+Paged result sets can be realized with offset pagination in a straightforward way but come with performance penalties for larger result sets.
+
+Example
+
+```
+POST /v2/user-tasks/search
+
+{
+  "page": {
+    "limit": 3
+  }
+}
+```
+
+This limits the result set returned in the response to 3 items, no matter how many overall results exist.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-data-fetching

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-data-fetching.user-task-support-sort.md

@@ -0,0 +1,20 @@
+# Data fetching — User task support — Sort
+
+The sort array specifies by which `field`s to sort the result items and whether this happens in ascending (ASC) or descending (DESC) `order`.
+
+Example
+
+```
+POST /v2/user-tasks/search
+
+{
+  "sort": [
+    { "field": "state", "order": "ASC" }
+  ]
+}
+```
+
+This sorts the overall result set by the `state` attribute in ascending order.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-data-fetching

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-data-fetching.user-task-support.md

@@ -0,0 +1,11 @@
+# Data fetching — User task support
+
+The Orchestration Cluster REST API only supports Camunda user tasks (previously referred to as [Zeebe user tasks](https://docs.camunda.io/docs/next/apis-tools/migration-manuals/migrate-to-camunda-user-tasks), which may still appear as `zeebe:userTask` in your XML content).
+
+
+## Search requests
+
+Search requests consist of the components for **filter**, **sort**, and **page**.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-data-fetching

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-overview.api-reference-base-urls.md

@@ -0,0 +1,20 @@
+# Orchestration Cluster REST API — API reference — Base URLs
+
+#### SaaS
+
+In the Camunda Console, go to your cluster, and in the Cluster Details, find your **Region Id** and **Cluster Id**.
+
+- For public connectivity (default), use this pattern as your `${BASE_URL}`: `https://${REGION_ID}.api.camunda.io/${CLUSTER_ID}/v2/`
+
+- For secure connectivity (AWS PrivateLink), use the private base URL shown in Console. For the Orchestration Cluster REST API, the pattern is:
+
+  `${BASE_URL} = https://${CLUSTER_ID}.${REGION_ID}.privateconnectivity.camunda.io/api/v2/`
+
+  For example: `https://b4102386-6818-43c6-a880-d21c968a883f.ork-1.privateconnectivity.camunda.io/api/v2/topology`
+
+#### Self-Managed
+
+Use the host and path defined for your [Zeebe Gateway](https://docs.camunda.io/docs/next/reference/glossary#zeebe-gateway). For Ingress and routing details, see the [configuration guide](https://docs.camunda.io/docs/next/self-managed/deployment/helm/configure/ingress/ingress-setup). If you're using the default setup, the `${BASE_URL}` is `http://localhost:8080/v2/`.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-overview.api-reference-date-formats.md

@@ -0,0 +1,6 @@
+# Orchestration Cluster REST API — API reference — Date formats
+
+Date values in the Orchestration Cluster REST API follow the [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) notation. This applies to all requests and responses. The endpoints validate requests and transform responses accordingly.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-overview.api-reference-http-status-codes-error-handling.md

@@ -0,0 +1,27 @@
+# Orchestration Cluster REST API — API reference — HTTP status codes & error handling
+
+The Orchestration Cluster REST API uses standard HTTP status codes and returns error responses following the [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) format. 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 detailed explanation of the issue
+- `instance`: A URI reference identifying the specific occurrence of the problem
+
+#### Common error codes
+
+| Error code | Meaning                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 200        | OK                                                                                                                                                                                                                                                                                                                                                                                                        |
+| 204        | No content                                                                                                                                                                                                                                                                                                                                                                                                |
+| 400        | Bad request. Generic error with further description in the problem detail.                                                                                                                                                                                                                                                                                                                                |
+| 401        | Unauthorized. The client is not authenticated. Retry with a modified authorization header.                                                                                                                                                                                                                                                                                                                |
+| 403        | Forbidden. The client has insufficient permissions for the request.                                                                                                                                                                                                                                                                                                                                       |
+| 404        | Not found                                                                                                                                                                                                                                                                                                                                                                                                 |
+| 409        | Conflict. The request attempts to modify a resource that is not in the correct state.                                                                                                                                                                                                                                                                                                                     |
+| 412        | Precondition failed. The client should check the cluster status.                                                                                                                                                                                                                                                                                                                                          |
+| 500        | Internal server error. Generic error with further description in the problem detail.                                                                                                                                                                                                                                                                                                                      |
+| 503        | The service is currently unavailable. This may happen when the system signals backpressure to prevent the server's compute resources from being exhausted, avoiding more severe failures. Clients are recommended to eventually retry those requests after a backoff period. You can learn more about the backpressure mechanism [here](https://docs.camunda.io/docs/next/components/zeebe/technical-concepts/internal-processing) |
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-overview.api-reference-naming-conventions.md

@@ -0,0 +1,33 @@
+# Orchestration Cluster REST API — API reference — Naming conventions
+
+Naming across the Orchestration Cluster REST API is simple, intuitive, and consistent to reduce friction when working with multiple endpoints.
+
+The conventions include:
+
+- **Nouns over verbs** – e.g., `assignment` instead of `assign`
+- **Plural terms** for top-level resources – e.g., `user-tasks`
+- **Kebab-case** for multiple words in path parameters – e.g., `user-tasks`
+- **camelCase** for multiple words in query parameters – e.g., `userTaskKey`
+
+These conventions are illustrated 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.
+
+| Term | Usage                                      |
+| ---- | ------------------------------------------ |
+| ID   | `id` (standalone) or `processDefinitionId` |
+| URL  | `url` (standalone) or `externalUrl`        |
+| UUID | `uuid` (standalone) or `clusterUuid`       |
+
+Identifiers follow a naming convention for parameters and data attributes alike:
+
+- Unique technical identifiers are suffixed with **key**, for example, `userTaskKey`, `processInstanceKey`, or `userKey`. These are usually numeric values.
+- Other identifiers, such as those copied from the BPMN XML, are typically suffixed with **id**, for example, `processDefinitionId`.
+- Key and id fields contain the entity as a prefix, for example, `userTaskKey` or `processDefinitionId`. This 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 name is used as the prefix to avoid confusion, for example, `processDefinitionKey` instead of `processKey`, which could be interpreted as a process instance or process definition.
+- Other entity attributes do not have a prefix to avoid clutter, such as `version` in the process definition entity. However, references to other resources require a prefix, like `processDefinitionVersion` in the process instance entity.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-overview.api-reference-request-size-limits.md

@@ -0,0 +1,6 @@
+# Orchestration Cluster REST API — API reference — Request size limits
+
+The default maximum request size for all requests (for example, to `POST /v2/deployments`) is 4MB. It can be configured in the Zeebe Gateway configuration using the `maxMessageSize` property. For more information, see the [Zeebe Gateway configuration reference](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/zeebe/configuration/configuration#gateway-configuration).
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-overview.api-reference-variables.md

@@ -0,0 +1,8 @@
+# Orchestration Cluster REST API — API reference — Variables
+
+Variables in the Orchestration Cluster REST API are JSON objects, where `key` defines the variable name and `value` specifies the variable value.
+
+For full details on variable filtering and structure, see [search requests](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-data-fetching#variables).
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-overview.api-reference-versioning.md

@@ -0,0 +1,13 @@
+# Orchestration Cluster REST API — API reference — Versioning
+
+Camunda uses semantic versioning (SemVer) to ensure API changes are predictable and compatible. This helps you upgrade safely without unexpected breaking changes.
+
+The API version is determined 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 may coexist—for example, both `v2` and `v3` versions of `/user-tasks/search` may be available in the same release.
+
+**Note**
+Adding new endpoints or attributes to existing responses is **not** considered a breaking change.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-overview.api-reference.md

@@ -0,0 +1,6 @@
+# Orchestration Cluster REST API — API reference
+
+This section covers the technical details and conventions you need to understand when working with the Orchestration Cluster REST API.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-overview.getting-started.md

@@ -0,0 +1,82 @@
+# Orchestration Cluster REST API — Getting started
+
+This section helps you get up and running in minutes.
+
+### Prerequisites
+
+- **A Camunda 8 Orchestration Cluster**
+  - For local development, use [Camunda 8 Run](https://docs.camunda.io/docs/next/self-managed/quickstart/developer-quickstart/c8run) or [Docker Compose](https://docs.camunda.io/docs/next/self-managed/quickstart/developer-quickstart/docker-compose), which expose the API without requiring credentials or tokens by default.
+  - For production or advanced development, use [Helm/Kubernetes](https://docs.camunda.io/docs/next/self-managed/deployment/helm/install/quick-install) or [manual installation](https://docs.camunda.io/docs/next/self-managed/deployment/manual/install).
+  - Alternatively, sign up for a free [Camunda 8 SaaS trial](https://accounts.camunda.io/signup) to get a managed cluster with the API enabled.
+
+- **A client to send API requests**
+  - Quick testing: Use the [Swagger](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-swagger) interface
+  - Programmatic access: Use the [Java client](https://docs.camunda.io/docs/next/apis-tools/java-client/getting-started) or [Camunda Spring Boot Starter](https://docs.camunda.io/docs/next/apis-tools/camunda-spring-boot-starter/getting-started)
+  - Custom client: [Download the OpenAPI spec](https://github.com/camunda/camunda/blob/main/zeebe/gateway-protocol/src/main/proto/rest-api.yaml) to generate your own client
+  - Universal client: [Postman collection](https://www.postman.com/camundateam/camunda-8-postman/collection/apl78x9/camunda-8-api-rest)
+
+### Authentication
+
+Authentication for the Orchestration Cluster REST API depends on your environment and how you deploy Camunda 8. Authenticate your Client requests based on your setup.
+
+**Supported authentication methods**
+
+- No authentication – For local development only
+- Basic authentication – Username/password for simple setups
+- OIDC-based authentication – Use OAuth2/OIDC tokens for production environments
+
+**Quick reference**
+
+- See the [authentication support matrix](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-authentication#authentication-support-matrix) for details on supported methods by deployment type
+- If you're using the Java or Spring clients, token management is handled automatically. See [client authentication configuration](https://docs.camunda.io/docs/next/apis-tools/camunda-spring-boot-starter/getting-started#configuring-the-camunda-8-connection)
+
+For detailed authentication setup, follow the step-by-step guide in [Authentication](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-authentication) based on your deployment type.
+
+### Test your connection
+
+Once you're set up, verify your connection works by making your first API call:
+
+#### Using curl
+
+Local (Camunda 8 Run / Docker Compose):
+
+```bash
+curl http://localhost:8080/v2/topology
+```
+
+SaaS, public connectivity:
+
+```bash
+curl https://${REGION_ID}.api.camunda.io/${CLUSTER_ID}/v2/topology
+```
+
+SaaS, secure connectivity (AWS PrivateLink):
+
+```bash
+curl https://${CLUSTER_ID}.${REGION_ID}.privateconnectivity.camunda.io/api/v2/topology
+```
+
+Replace the placeholders with the values for your environment.
+See [Base URLs](#base-urls) for details on SaaS (public and secure connectivity) and self-managed setups.
+
+#### Using Postman
+
+Try the [get cluster topology](https://www.postman.com/camundateam/camunda-8-postman/request/en495q6/get-cluster-typology) request or browse the full collection.
+
+This request returns information about your cluster topology, confirming that your setup is working correctly.
+
+### Try your first workflow
+
+If you're just getting started with process automation, try this simple workflow:
+
+1. **Model a process** – Create a simple BPMN process with a user task using [Camunda Modeler](https://camunda.com/download/modeler/)
+2. **Deploy the process** – Use [`POST /deployments`](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/create-deployment.api) to deploy your BPMN file
+3. **Start a process instance** – Use [`POST /process-instances`](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/create-process-instance.api) to create a new process instance
+4. **Complete a user task** – Use [`POST /user-tasks/{userTaskKey}/completion`](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/complete-user-task.api) to complete the task
+
+For a complete walkthrough with code examples, see our [Getting Started Tutorial](https://docs.camunda.io/docs/next/guides/getting-started-example).
+
+### Explore the API
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-overview.key-features.md

@@ -0,0 +1,22 @@
+# Orchestration Cluster REST API — Key features
+
+This API is designed to make it easy to [find resources](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-data-fetching#advanced-search-filters) with a consistent experience, while ensuring all endpoints are secure with [authentication](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-authentication) and fine-grained [resource authorization](https://docs.camunda.io/docs/next/components/concepts/access-control/authorizations).
+
+Key features include:
+
+| Feature                           | Description                                           |
+| :-------------------------------- | :---------------------------------------------------- |
+| Full process lifecycle management | Deploy, start, and monitor BPMN processes.            |
+| User task operations              | Claim, complete, and manage human tasks.              |
+| Variable management               | Read and update process variables.                    |
+| Incident resolution               | Handle and resolve process incidents.                 |
+| Advanced search and filtering     | Query process data with powerful search capabilities. |
+
+**Info**
+
+- This API is part of the Camunda 8 [public API](https://docs.camunda.io/docs/next/reference/public-api) and is covered by our SemVer stability guarantees (except for clearly marked alpha endpoints). You can rely on backward compatibility for production use.
+- To learn more about the Orchestration Cluster, see [Orchestration Cluster](https://docs.camunda.io/docs/next/components/orchestration-cluster).
+- In Self-Managed clusters running [Physical Tenants](https://docs.camunda.io/docs/next/self-managed/concepts/multi-tenancy/physical-tenants), most endpoints below are addressed per tenant by prefixing the path with `/physical-tenants/{physicalTenantId}`, while cluster-wide operations use the `/cluster/v2/...` prefix instead. See [API routing for Physical Tenants](https://docs.camunda.io/docs/next/self-managed/concepts/physical-tenants/api-routing).
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-overview.md

@@ -0,0 +1,19 @@
+# Orchestration Cluster REST API
+
+Use the Orchestration Cluster API to manage and interact with Camunda 8 Orchestration Clusters.
+
+
+## About
+
+You can use the Orchestration Cluster REST API to interact programmatically with process orchestration capabilities in Camunda 8. For example, you can start, manage, and query process instances, complete user tasks, resolve incidents, and manage variables.
+
+Use this API to:
+
+| Use case                                    | Description                                                                       |
+| :------------------------------------------ | :-------------------------------------------------------------------------------- |
+| Build process-driven applications           | Create applications to orchestrate processes and integrate with existing systems. |
+| Integrate user tasks into custom UIs        | Build task management interfaces that connect to Camunda's user task engine.      |
+| Start and monitor external system processes | Trigger process instances and track progress from any application or service.     |
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-overview.what-s-next.md

@@ -0,0 +1,11 @@
+# Orchestration Cluster REST API — What's next?
+
+Now that you're familiar with the Orchestration Cluster REST API, here are some useful next steps:
+
+- [Build a job worker using the Spring SDK](https://docs.camunda.io/docs/next/apis-tools/camunda-spring-boot-starter/getting-started)
+- [Test your process definitions using Camunda Process Test](https://docs.camunda.io/docs/next/apis-tools/testing/getting-started)
+- [Migrate from v1 component REST APIs to the v2 Orchestration Cluster REST API](https://docs.camunda.io/docs/next/apis-tools/migration-manuals/migrate-to-camunda-api)
+- [Download the OpenAPI spec](https://github.com/camunda/camunda/blob/main/zeebe/gateway-protocol/src/main/proto/rest-api.yaml) to generate a client or explore the raw schema
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-secrets.list-secrets.md

@@ -0,0 +1,17 @@
+# Secrets — List secrets
+
+`POST /v2/secrets/list` returns the names of references the caller is authorized to view. It never returns secret values.
+
+Unauthorized references are omitted from the response rather than causing the request to fail.
+
+The request body is optional and can be empty. The endpoint does not currently support filtering or pagination. Pagination is marked in the OpenAPI specification as a pre-GA follow-up.
+
+
+## Grant required permissions
+
+Resolving a reference requires `SECRET:REVEAL`. Listing requires `SECRET:READ`. Neither permission grants the other.
+
+See [Authorizations](https://docs.camunda.io/docs/next/components/concepts/access-control/authorizations) for details about permissions on the `SECRET` resource and who receives them by default.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-secrets

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-secrets.md

@@ -0,0 +1,10 @@
+# Secrets
+
+Learn about the shared request and response contract for the resolve and list secrets endpoints.
+
+`POST /v2/secrets/resolve` and `POST /v2/secrets/list` use a shared request and response contract that differs from most of the Orchestration Cluster REST API.
+
+For the complete request and response schema for each endpoint, see [Resolve secrets](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/resolve-secrets.api) and [List secrets](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/list-secrets.api). To understand what a `camunda.secrets.<name>` reference is and how Camunda resolves it elsewhere in the cluster, see [Secret resolution](https://docs.camunda.io/docs/next/components/concepts/secret-resolution). For Java client usage, see [Secrets](https://docs.camunda.io/docs/next/apis-tools/java-client/secrets).
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-secrets

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-secrets.understand-resolve-responses.md

@@ -0,0 +1,35 @@
+# Secrets — Understand resolve responses
+
+`POST /v2/secrets/resolve` accepts a batch of references and resolves each reference independently. A structurally valid request always returns HTTP 200, even if every reference in the batch fails.
+
+Successfully resolved references are returned in `resolved`. References that cannot be resolved are returned in `errors`. A failure for one reference does not affect the others in the same batch.
+
+### Review per-reference errors
+
+Each entry in `errors` uses one of the following codes:
+
+| Code                | Meaning                                                                       |
+| ------------------- | ----------------------------------------------------------------------------- |
+| `NOT_FOUND`         | No secret exists for this reference.                                          |
+| `ACCESS_DENIED`     | The caller lacks `SECRET:REVEAL` for this reference.                          |
+| `INVALID_REFERENCE` | The reference is malformed or exceeds the length limit.                       |
+| `UNREADABLE`        | The store contains a secret for this reference, but its value cannot be read. |
+
+`UNREADABLE` does not mean that the secret is absent. Handle it differently from `NOT_FOUND` when responding to a failure.
+
+### Check batch limits
+
+A request can contain up to 20 references, with a maximum length of 256 characters per reference. The server deduplicates duplicate references within the same request and resolves each unique reference once.
+
+### Understand HTTP 400 responses
+
+`POST /v2/secrets/resolve` returns HTTP 400 only when the request itself is malformed. Examples include:
+
+- A missing or non-array `references` field.
+- More than 20 references.
+- A `null` entry.
+
+A well-formed request that fails to resolve every reference still returns HTTP 200 with `errors` populated.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-secrets

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-swagger.authentication-in-swagger-ui.md

@@ -0,0 +1,35 @@
+# Try with Swagger — Authentication in Swagger UI
+
+Swagger UI supports the same authentication methods as the REST API. Choose the method that matches your deployment:
+
+### Automatic authentication
+
+- **Session-based authentication**: If you're already logged into Camunda (for example, through Operate), Swagger UI automatically authenticates you using your session cookie
+
+### Manual authentication
+
+Click the **Authorize** button in Swagger UI to manually configure authentication:
+
+#### Bearer Token (Recommended for production)
+
+1. Click **Authorize** in Swagger UI
+2. In the **Bearer** section, enter your JWT access token
+3. Click **Authorize** to apply
+
+**To obtain a Bearer token:**
+
+- **SaaS**: Follow the [OIDC-based Authentication guide](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-authentication#oidc-access-token-authentication-using-client-credentials) for SaaS
+- **Self-Managed**: Follow the [OIDC-based Authentication guide](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-authentication#oidc-access-token-authentication-using-client-credentials) for Self-Managed
+
+#### Basic Authentication
+
+1. Click **Authorize** in Swagger UI
+2. In the **Basic** section, enter your username and password
+3. Click **Authorize** to apply
+
+**Note:** Basic Authentication is only available for Self-Managed deployments.
+
+For detailed authentication setup instructions, see the [Authentication guide](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-authentication).
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-swagger

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-swagger.managing-swagger-ui-availability.md

@@ -0,0 +1,40 @@
+# Try with Swagger — Managing Swagger UI availability
+
+### SaaS
+
+Control Swagger UI access through the Camunda Console:
+
+1. Navigate to your cluster in the Camunda Console
+2. Go to **Cluster Settings**
+3. Toggle **Enable Swagger** on or off
+4. Changes apply automatically to your orchestration cluster
+
+### Self-Managed
+
+Configure Swagger UI availability using environment variables:
+
+**Enable Swagger UI (default):**
+
+```bash
+CAMUNDA_REST_SWAGGER_ENABLED=true
+```
+
+**Disable Swagger UI:**
+
+```bash
+CAMUNDA_REST_SWAGGER_ENABLED=false
+```
+
+**Alternative property format:**
+
+```yaml
+camunda:
+  rest:
+    swagger:
+      enabled: true
+```
+
+**Security consideration:** In production environments, consider disabling Swagger UI and using it only in development environments.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-swagger

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-swagger.md

@@ -0,0 +1,17 @@
+# Try with Swagger
+
+Explore and test the Orchestration Cluster REST API endpoints interactively with Swagger UI.
+
+The Orchestration Cluster REST API is documented using the [OpenAPI specification](https://github.com/camunda/camunda/blob/main/zeebe/gateway-protocol/src/main/proto/rest-api.yaml). You can explore, test, and interact with all API endpoints directly using [Swagger UI](https://swagger.io/tools/swagger-ui/) - an interactive documentation interface.
+
+**Use Swagger UI to:**
+
+- Explore available endpoints - Browse all REST API operations with detailed parameter descriptions
+- Test API calls interactively - Execute real API requests directly from your browser
+- Understand request/response formats - See example payloads and response schemas
+- Authenticate and authorise - Test with your actual credentials in a secure environment
+
+Swagger UI is particularly useful for API discovery, development, and testing workflows before integrating the API into your applications.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-swagger

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-swagger.next-steps.md

@@ -0,0 +1,14 @@
+# Try with Swagger — Next steps
+
+After exploring the API with Swagger UI:
+
+- **Build production integrations** using the [Java client](https://docs.camunda.io/docs/next/apis-tools/java-client/getting-started) or [Camunda Spring Boot Starter](https://docs.camunda.io/docs/next/apis-tools/camunda-spring-boot-starter/getting-started)
+- **Review the complete API reference** in the [Overview](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview)
+- **Set up proper authentication** following the [Authentication guide](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-authentication)
+- **Learn advanced querying** with [Data Fetching and Search](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-data-fetching)
+- **Download the OpenAPI specification** for [custom client generation](https://github.com/camunda/camunda/blob/main/zeebe/gateway-protocol/src/main/proto/rest-api.yaml)
+
+**Need help?** Try the [Getting Started Tutorial](https://docs.camunda.io/docs/next/guides/getting-started-example) for a complete workflow walkthrough, or browse the [Postman collection](https://www.postman.com/camundateam/camunda-8-postman/collection/apl78x9/camunda-8-api-rest) for additional examples.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-swagger