@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.intermediate-tutorial.create-and-start-a-process-instance-post.md

@@ -0,0 +1,51 @@
+# Intermediate tutorial — Create and start a process instance (POST)
+
+To create and start a process instance based on the process instance key obtained in the request above, take the following steps:
+
+1. Outline your function, similar to the steps above:
+
+```javascript
+async function createInstance([processDefinitionKey]) {
+  const accessToken = await getAccessToken(authorizationConfiguration);
+  const camundaApiUrl = process.env.CAMUNDA_REST_ADDRESS;
+  const url = `${camundaApiUrl}/process-instances`;
+}
+```
+
+2. Build the payload you will send to the endpoint:
+
+```javascript
+const payload = {
+  processDefinitionKey,
+  variables: {
+    total: 90.0,
+  },
+};
+```
+
+**Note**
+The request will succeed if the variable names are different, but the process instance itself will not function as expected.
+
+3. Call the endpoint, process the results from the API call, and emit an error message from the server if necessary:
+
+```javascript
+try {
+  const response = await axios.post(url, payload, {
+    headers: {
+      Accept: "application/json",
+      Authorization: `Bearer ${accessToken}`,
+    },
+  });
+
+  const processInstance = response.data;
+
+  console.log(`Process Instance Key: ${processInstance.processInstanceKey}`);
+} catch (error) {
+  console.error(`Error creating process instance: ${error.message}`);
+}
+```
+
+4. In your terminal, run `node cli.js processInstances create <key>`, where `<key>` is the process definition key. The `processInstanceKey` will now display in the output. Capture this key for a future method.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/intermediate-tutorial

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.intermediate-tutorial.deploy-resources-post.md

@@ -0,0 +1,89 @@
+# Intermediate tutorial — Deploy resources (POST)
+
+First, let's script an API call to deploy a resource.
+
+To do this, take the following steps:
+
+1. In the file named `camunda-process-instances.js`, outline the authentication and authorization configuration in the first few lines. This will pull in your `.env` variables to obtain an access token before making any API calls:
+
+```javascript
+const authorizationConfiguration = {
+  clientId: process.env.CAMUNDA_CLIENT_ID,
+  clientSecret: process.env.CAMUNDA_CLIENT_SECRET,
+  // These settings come from your .env file. Note that CAMUNDA_TOKEN_AUDIENCE is represented by ZEEBE_TOKEN_AUDIENCE in the Console UI.
+  audience: process.env.CAMUNDA_TOKEN_AUDIENCE,
+};
+```
+
+2. Examine the function `async function deployResources()` below this configuration. This is where you will script out your API call.
+3. Within the function, you must first generate an access token for this request, so your function should now look like the following:
+
+```javascript
+async function deployResources() {
+  const accessToken = await getAccessToken(authorizationConfiguration);
+}
+```
+
+4. Using your generated client credentials from [prerequisites](#prerequisites), capture your Orchestration Cluster REST API URL beneath your call for an access token by defining `camundaApiUrl`:
+
+```javascript
+const camundaApiUrl = process.env.CAMUNDA_REST_ADDRESS;
+```
+
+5. On the next line, script the API endpoint to deploy the resources:
+
+```javascript
+const url = `${camundaApiUrl}/deployments`;
+```
+
+6. We will now configure the variables representing the BPMN file and its form data. This may look different depending on which resources you choose to deploy, but reflects the block-scoped local variables and append method to insert a set of objects for the BPMN resource of this tutorial:
+
+```javascript
+const formData = new FormData();
+// Read the BPMN file and add it to the form data
+const bpmnFilePath = path.resolve("resources/calculate-sales-tax.bpmn");
+const fileContent = fs.readFileSync(bpmnFilePath);
+formData.append("resources", fileContent, {
+  filename: "calculate-sales-tax.bpmn",
+  contentType: "application/xml",
+});
+```
+
+**Note**
+The `resources` name must be exact according to the API requirements, the path to the file (`const bpmnFilePath = path.resolve("resources/calculate-sales-tax.bpmn");`) must be correct, and `contentType` must be `application/xml` to ensure the upload will not fail.
+
+7. Call the endpoint, process the results from the API call, and emit an error message from the server if necessary:
+
+```javascript
+try {
+  const response = await axios.post(url, formData, {
+    headers: {
+      Accept: "application/json",
+      Authorization: `Bearer ${accessToken}`,
+      ...formData.getHeaders(),
+    },
+  });
+
+  const deployedResources = response.data.deployments || [];
+
+  // Emit deployed resources
+  deployedResources.forEach((x) =>
+    console.log(
+      `Process Definition Key: ${x.processDefinition.processDefinitionKey}; Process Definition Id: ${x.processDefinition.processDefinitionId}`
+    )
+  );
+} catch (error) {
+  // Emit an error from the server.
+  console.error(`Error deploying resources: ${error.message}`);
+}
+```
+
+8. In your terminal, run `node cli.js processInstances deploy`.
+
+**Note**
+This `deploy` command is connected to the `deployResources` function at the bottom of the `camunda-process-instances.js` file, and executed by the `cli.js` file. While we will work with process instances in this tutorial, you may add additional arguments depending on the API requests you want to make.
+
+The existing process definition key and ID will now output. If you have an invalid API name or action name, or no arguments provided, or improper/insufficient credentials configured, an error message will output as outlined in the `cli.js` file.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/intermediate-tutorial

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

@@ -0,0 +1,12 @@
+# Intermediate tutorial
+
+Step through this intermediate Orchestration Cluster REST API tutorial to deploy resources, create and start a process instance, and view a process instance by its key.
+
+Intermediate
+
+In this tutorial, we'll step through examples to highlight the capabilities of the Orchestration Cluster REST API, such as deploying resources, creating and starting a process instance, and viewing a process instance by its key.
+
+This tutorial is intended for intermediate users of the Orchestration Cluster REST API, using more sophisticated API calls and multipart requests. If you are new to the Orchestration Cluster REST API, we recommend starting with the [beginner tutorial](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/tutorial).
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/intermediate-tutorial

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.intermediate-tutorial.prerequisites-set-up-authentication.md

@@ -0,0 +1,21 @@
+# Intermediate tutorial — Prerequisites — Set up authentication
+
+If you're interested in how we use a library to handle auth for our code, or to get started, examine the `auth.js` file in the GitHub repository. This file contains a function named `getAccessToken` which executes an OAuth 2.0 protocol to retrieve authentication credentials based on your client ID and client secret. Then, we return the actual token that can be passed as an authorization header in each request.
+
+To set up your credentials, create an `.env` file which will be protected by the `.gitignore` file. Add the following environment variables:
+
+- `CAMUNDA_CLIENT_ID`
+- `CAMUNDA_CLIENT_SECRET`
+- `CAMUNDA_REST_ADDRESS` (after creating a client and downloading the .env variables, this is reflected in the Console UI as `ZEEBE_REST_ADDRESS`)
+- `CAMUNDA_TOKEN_AUDIENCE` (represented as `ZEEBE_TOKEN_AUDIENCE` in the Console UI), which is `zeebe.camunda.io` in a Camunda 8 SaaS environment. For example, your audience may be defined as `CAMUNDA_TOKEN_AUDIENCE=zeebe.camunda.io`.
+
+These keys will be consumed by the `auth.js` file to execute the OAuth protocol, and should be saved when you generate your client credentials in [prerequisites](#prerequisites).
+
+See the existing `.env.example` file for an example of how your `.env` file should look upon completion. Do not place your credentials in the `.env.example` file, as this example file is not protected by the `.gitignore`.
+
+**Note**
+
+In this tutorial, we will execute arguments to deploy a resource, create and start a process instance, and view a process instance by its key. You can examine the framework for processing these arguments in the `cli.js` file before getting started.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/intermediate-tutorial

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.intermediate-tutorial.prerequisites.md

@@ -0,0 +1,13 @@
+# Intermediate tutorial — Prerequisites
+
+| Requirement                                                                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| :------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Create a cluster](https://docs.camunda.io/docs/next/components/hub/organization/manage-clusters/create-cluster)                             | If you haven't done so already, create a cluster.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| [Create your first client](https://docs.camunda.io/docs/next/components/hub/organization/manage-clusters/manage-api-clients#create-a-client) | Upon cluster creation, create your first client. Ensure you check the `Orchestration Cluster API` client scope box. Make sure you keep the generated client credentials in a safe place. The **Client secret** will not be shown again. For your convenience, you can also download the client information to your computer.                                                                                                                                                                                                                                          |
+| Clone the [GitHub repository](https://github.com/camunda/camunda-api-tutorials)                                | In this tutorial, we use a JavaScript-written [GitHub repository](https://github.com/camunda/camunda-api-tutorials) to write and run requests. Clone this repo before getting started.                                                                                                                                                                                                                                                                                                                                                                                |
+| Prepare resources                                                                                              | The first request we will run is a request to deploy one or more resources (such as processes, decision models, or forms). For the purposes of this tutorial, we have preconfigured a BPMN diagram and converted this into XML. This diagram, `calculate-sales-tax.bpmn`, can be found in the GitHub repository above within the `resources` folder. The BPMN diagram itself represents a process to calculate the total sales tax for a given purchase. You can take a closer look at this diagram by opening it in [Modeler](https://docs.camunda.io/docs/next/components/modeler/about-modeler). |
+| [Node.js](https://nodejs.org/en/download)                                                                      | Ensure you have [Node.js](https://nodejs.org/en/download) installed as this will be used for methods that can be called by the CLI (outlined later in this guide). Run `npm install` to ensure you have updated dependencies.                                                                                                                                                                                                                                                                                                                                         |
+| Authenticate                                                                                                   | You need authentication to access the API endpoints. Find more information in [Camunda 8 authentication](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-authentication), and the section below.                                                                                                                                                                                                                                                                                                                                                                                  |
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/intermediate-tutorial

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.intermediate-tutorial.retrieve-a-process-instance-get.md

@@ -0,0 +1,39 @@
+# Intermediate tutorial — Retrieve a process instance (GET)
+
+To retrieve a process instance by the process instance key, take the following steps:
+
+1. Outline your function, similar to the steps above:
+
+```javascript
+async function viewInstance([processInstanceKey]) {
+  const accessToken = await getAccessToken(authorizationConfiguration);
+  const camundaApiUrl = process.env.CAMUNDA_REST_ADDRESS;
+  const url = `${camundaApiUrl}/process-instances/${processInstanceKey}`;
+}
+```
+
+2. Call the endpoint, process the results from the API call, and emit an error message from the server if necessary:
+
+```javascript
+try {
+  const response = await axios.get(url, {
+    headers: {
+      Accept: "application/json",
+      Authorization: `Bearer ${accessToken}`,
+    },
+  });
+
+  const results = response.data;
+
+  console.log(
+    `Process instance name: ${results.processDefinitionName}; State: ${results.state};`
+  );
+} catch (error) {
+  console.error(`Error retrieving process instance: ${error.message}`);
+}
+```
+
+3. In your terminal, run `node cli.js processInstances view <key>`, where `<key>` is the process instance key. The `processDefinitionName` and `state` will then display in the output.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/intermediate-tutorial

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.intermediate-tutorial.troubleshooting.md

@@ -0,0 +1,11 @@
+# Intermediate tutorial — Troubleshooting
+
+Having trouble configuring your API calls or want to examine an example of the completed tutorial? Navigate to the `completed` folder in the [GitHub repository](https://github.com/camunda/camunda-api-tutorials/tree/main/completed), where you can view an example `camunda-process-instances.js` file.
+
+
+## Next steps
+
+You can script several additional API calls as outlined in the [Orchestration Cluster REST API reference material](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview).
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/intermediate-tutorial

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-authentication.authenticate-api-calls.md

@@ -0,0 +1,33 @@
+# Authentication — Authenticate API calls
+
+### No authentication (local development)
+
+By default, Camunda 8 Run and Docker Compose expose the Orchestration Cluster REST API without authentication for local development. You can make API requests directly:
+
+```shell
+curl http://localhost:8080/v2/topology
+```
+
+### Basic Authentication
+
+Basic Authentication uses username and password credentials.
+
+**For Camunda 8 Run:**  
+Enable Basic Auth by configuring authentication in your `application.yaml`. See [Camunda 8 Run documentation](https://docs.camunda.io/docs/next/self-managed/quickstart/developer-quickstart/c8run/configuration#enable-authentication-and-authorization) for details.
+
+**For Helm:**  
+Basic Auth is enabled by default for the Orchestration Cluster API.
+
+Include your username and password in each API request:
+
+```shell
+curl --user username:password \
+     http://localhost:8080/v2/topology
+```
+
+**Note**
+Basic Authentication checks the password with every request, limiting the number of requests per second. It may not be suitable for production.  
+See [Camunda components troubleshooting](https://docs.camunda.io/docs/next/self-managed/operational-guides/troubleshooting)
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-authentication

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

@@ -0,0 +1,23 @@
+# Authentication
+
+Step through authentication options for accessing the Orchestration Cluster REST API.
+
+This page explains how to authenticate requests to the Orchestration Cluster REST API across different deployment environments.
+
+
+## Authentication support matrix
+
+| Distribution                                                                      | Default Authentication | No auth support         | Basic auth support | OIDC-based auth support |
+| --------------------------------------------------------------------------------- | ---------------------- | ----------------------- | ------------------ | ----------------------- |
+| [Camunda 8 Run](https://docs.camunda.io/docs/next/self-managed/quickstart/developer-quickstart/c8run)           | None                   | ✅ (default)            | ✅ (when enabled)  | ✅ (when configured)    |
+| [Docker Compose](https://docs.camunda.io/docs/next/self-managed/quickstart/developer-quickstart/docker-compose) | None                   | ✅ (default)            | ✅ (when enabled)  | ✅ (when configured)    |
+| [Helm](https://docs.camunda.io/docs/next/self-managed/deployment/helm/install/quick-install)                    | Basic Auth             | ✅ (when auth disabled) | ✅ (default)       | ✅ (when configured)    |
+| SaaS                                                                              | OIDC-based Auth        | ❌                      | ❌                 | ✅ (required)           |
+
+**Info: Authentication vs. authorization**
+Authentication establishes who is calling the Orchestration Cluster REST API (for example, using basic authentication or an OIDC access token). Authorization determines what that caller can do, based on authorizations configured in Admin.
+
+To learn more about authorization resources, permissions, and precedence (including user task permissions), see [Orchestration Cluster authorization](https://docs.camunda.io/docs/next/components/concepts/access-control/authorizations).
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-authentication

package/.llms/chunks/apis-tools.orchestration-cluster-api-rest.orchestration-cluster-api-rest-authentication.using-a-token-oidc-jwt.md

@@ -0,0 +1,88 @@
+# Authentication — Using a token (OIDC/JWT)
+
+OIDC-based authentication is recommended for production and required for SaaS. Obtain an access token and pass it as an OAuth 2.0 Bearer Token in the `Authorization` header of each request. The token's subject (user or client) must also have the required authorizations. Otherwise, requests fail with `403 Forbidden` even if authentication succeeds.
+
+<Tabs groupId="environment" defaultValue="saas" queryString values={[
+{label: 'SaaS', value: 'saas' },
+{label: 'Self-Managed', value: 'self-managed' },
+]}>
+
+### saas
+
+1. [Create client credentials](https://docs.camunda.io/docs/next/components/hub/organization/manage-clusters/manage-api-clients#create-a-client) in the Camunda Console.
+2. Request an access token using the credentials:
+
+```shell
+curl --request POST ${CAMUNDA_OAUTH_URL} \
+    --header 'Content-Type: application/x-www-form-urlencoded' \
+    --data-urlencode 'grant_type=client_credentials' \
+    --data-urlencode "audience=${CAMUNDA_TOKEN_AUDIENCE}" \
+    --data-urlencode "client_id=${CAMUNDA_CLIENT_ID}" \
+    --data-urlencode "client_secret=${CAMUNDA_CLIENT_SECRET}"
+```
+
+3. Use the access token from the response in your API requests:
+
+```shell
+curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
+     ${BASE_URL}/topology
+```
+
+### self-managed
+
+**Prerequisites for OIDC-based authentication**
+
+- Your Orchestration Cluster must already be configured with your Identity Provider. See [Set up OIDC-based Authentication](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/admin/connect-external-identity-provider).
+- You must have a registered client in your IdP with a **client ID**, **client secret**, and authorization endpoint.
+- Note the configured **audience** and **scope** for token requests (variables `OC_AUDIENCE` and `SCOPE`). Depends on IdP configuration.
+
+**Request an access token using client credentials**
+
+Example for Keycloak; adjust the authorization URI and parameters for your IdP:
+
+```shell
+curl --location --request POST 'http://<IDP_HOST>/auth/realms/<REALM>/protocol/openid-connect/token' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--data-urlencode "client_id=${CLIENT_ID}" \
+--data-urlencode "client_secret=${CLIENT_SECRET}" \
+--data-urlencode "audience=${OC_AUDIENCE}" \
+--data-urlencode "scope=${SCOPE}" \
+--data-urlencode 'grant_type=client_credentials'
+```
+
+> **Microsoft Entra ID**: Use `scope=${SCOPE}/.default` instead of `scope=${SCOPE}`. The Authorization URI is typically `https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token`.
+
+**Use the access token in API requests**
+
+```shell
+curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
+     ${BASE_URL}/topology
+```
+
+### OIDC-based authentication using X.509 client certificates
+
+For advanced security scenarios, you can obtain OIDC access tokens using X.509 client certificates. This is typically required in Self-Managed environments where your IdP enforces mutual TLS (mTLS).
+
+**For Java applications**  
+The Java client supports automatic OIDC access token retrieval using X.509 client certificates. Configure the necessary keystore and truststore via code or environment variables. See [Java client authentication](https://docs.camunda.io/docs/next/apis-tools/java-client/getting-started#oidc-access-token-authentication-with-x509-client-certificate) for details.
+
+**For other clients**  
+Refer to your IdP documentation for obtaining tokens using X.509 certificates.
+
+### Automatic token management in official clients
+
+Official Camunda clients (Java client or Spring Boot Starter) handle token acquisition and renewal automatically. You do not need to manually obtain or refresh tokens.
+
+### Troubleshooting
+
+- Check logs for authentication errors.
+- Verify your access token includes the correct audience if audience validation is enabled.
+
+### Learn more
+
+- [Camunda Java client authentication and token management](https://docs.camunda.io/docs/next/apis-tools/java-client/getting-started)
+- [Camunda Spring Boot Starter: Configuring the Camunda 8 connection](https://docs.camunda.io/docs/next/apis-tools/camunda-spring-boot-starter/getting-started#configuring-the-camunda-8-connection)
+- [Orchestration Cluster authorization: Resources, permissions, and configuration](https://docs.camunda.io/docs/next/components/concepts/access-control/authorizations)
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-authentication

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

@@ -0,0 +1,22 @@
+# Data fetching
+
+Learn about fetching data using the Orchestration Cluster REST API.
+
+The Orchestration Cluster REST API allows you to retrieve data from key resources like process definitions, user tasks, users, and tenants. Each search-enabled endpoint supports rich filtering, sorting, and pagination so you can quickly find the data that matters most.
+
+The sections below explain how to structure a search request and interpret the response format.
+
+
+## Searchable resources
+
+The following examples support search via POST endpoints, each with its own set of filterable fields:
+
+- Process instances (`POST /v2/process-instances/search`)
+- User tasks (`POST /v2/user-tasks/search`)
+- Users (`POST /v2/users/search`)
+- Batch operations (`POST /v2/batch-operations/search`)
+
+Refer to the [interactive Orchestration Cluster REST API Explorer](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/orchestration-cluster-api.info) for the full attribute lists.
+
+---
+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.search-example.md

@@ -0,0 +1,91 @@
+# Data fetching — Search example
+
+Querying for the first three user tasks with certain criteria and sorted by state could look as follows:
+
+```
+POST /v2/user-tasks/search
+
+{
+  "filter": {
+    "assignee": "demo",
+    "processInstanceKey": "22456786958",
+    "candidateGroups": { "$like": "external-*", "$neq": "external-supervisor" },
+    "localVariables" :  [
+      { "name": "orderVolume", "value": "10000" },
+      { "name": "price", "value": { "$lt": "500" } },
+      { "name": "skipped", "value": { "$exists": false } }
+    ],
+  },
+  "sort": [
+    { "field": "state", "order": "ASC" }
+  ],
+  "page": {
+    "limit": 3
+  }
+}
+```
+
+This could yield the following example result:
+
+```
+200 OK
+
+{
+  "items": [
+    {
+      "state": "CREATED",
+      "processInstanceKey": "22456786958",
+      "userTaskKey": "22456786345",
+      ...
+    },
+    {
+      "state": "CREATED",
+      "processInstanceKey": "22456786958",
+      "userTaskKey": "22456786456",
+      ...
+    },
+    {
+      "state": "COMPLETED",
+      "processInstanceKey": "22456786958",
+      "userTaskKey": "22456786678",
+      ...
+    }
+  ],
+  "page": {
+    "totalItems":  345,
+    "startCursor": "jfenj8vhekgj98uzfafhu7",
+    "endCursor": "negbkjeh84tzh4gk0kwegj"
+  }
+}
+```
+
+A follow-up request to receive the next three items could then look as follows:
+
+```
+POST /v2/user-tasks/search
+
+{
+  "filter": {
+    "assignee": "demo",
+    "processInstanceKey": "22456786958",
+    "candidateGroups": { "$like": "external-*", "$neq": "external-supervisor" },
+    "localVariables" :  [
+      { "name": "orderVolume", "value": "10000" },
+      { "name": "price", "value": { "$lt": "500" } },
+      { "name": "skipped", "value": { "$exists": false } }
+    ],
+  },
+  "sort": [
+    { "field": "state", "order": "ASC" }
+  ],
+  "page": {
+    "limit":  3,
+    "after": "negbkjeh84tzh4gk0kwegj"
+  }
+}
+```
+
+This yields the next three user task instances after the last one from the first search request’s result.
+
+---
+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.search-responses.md

@@ -0,0 +1,49 @@
+# Data fetching — Search responses
+
+Search responses consist of two components: **`items`** and **`page`**.
+
+- The **`items`** array contains instances of the respective endpoint’s resource.  
+  The structure and attributes of these instances vary by endpoint and are detailed in the corresponding endpoint documentation.
+
+- The **`page`** object includes pagination details for navigating through results in subsequent search requests:
+  - **`totalItems`**: Indicates the total number of results for the query.
+    > **Note:** In Elasticsearch/OpenSearch, this value is capped at **10,000**, even if more results are available.
+  - **`startCursor`**: A reference to the **first** entry on the current page.  
+    Use this value in the `before` parameter to page **backward** in a subsequent [search request](#search-requests).
+  - **`endCursor`**: A reference to the **last** entry on the current page.  
+    Use this value in the `after` parameter to page **forward** in a subsequent [search request](#search-requests).
+
+Example
+
+```
+{
+  "items": [
+    {
+      "state": "CREATED",
+      "processInstanceKey": "22456786958",
+      "userTaskKey": "22456786345",
+      ...
+    },
+    {
+      "state": "CREATED",
+      "processInstanceKey": "22456786958",
+      "userTaskKey": "22456786456",
+      ...
+    },
+    {
+      "state": "COMPLETED",
+      "processInstanceKey": "22456786958",
+      "userTaskKey": "22456786678",
+      ...
+    }
+  ],
+  "page": {
+    "totalItems":  345,
+    "startCursor": "jfenj8vhekgj98uzfafhu7",
+    "endCursor": "negbkjeh84tzh4gk0kwegj"
+  }
+}
+```
+
+---
+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.supported-operations.md

@@ -0,0 +1,45 @@
+# Data fetching — Supported operations
+
+Most searchable resources allow:
+
+- Filtering based on properties or variables
+- Sorting results
+- Paginating with either offset or cursor methods
+- Accessing nested resources (e.g., group users)
+
+> Example: You can search for groups using `POST /v2/groups/search`, and for the users in a group using `POST /v2/groups/:groupId/users/search`.
+
+You can also fetch single resources using `GET` endpoints with unique identifiers, such as:
+
+```shell
+GET /v2/user-tasks/:userTaskKey
+```
+
+
+## Data consistency
+
+Endpoints in the Orchestration Cluster API are classified as either **strongly consistent** or **eventually consistent**.  
+This distinction applies to the _data behind the endpoint_, not the endpoint's functionality itself.
+
+- **Strongly consistent endpoints** return data that reflects the real-time state of the system.
+- **Eventually consistent endpoints** return data exported by the [Camunda Exporter](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/zeebe/exporters/camunda-exporter). This data may lag behind the real-time state until the exporter processes it, so it becomes consistent only after a delay.
+
+Each endpoint is clearly labeled with its consistency type so you can account for this behavior in your applications.
+
+### Why consistency matters
+
+If eventual consistency is not handled properly, it can lead to unexpected results.
+
+For example:
+
+1. A resource is created using a strongly consistent endpoint.
+2. An _immediate_ request to an eventually consistent endpoint for the same resource might return:
+   - `404 Not Found` for a `GET` request, or
+   - an empty result set for a search request.
+
+This happens because the eventually consistent endpoint has not yet synced the new data. A later request will return the correct result once the data export completes.
+
+If your application does not account for eventual consistency, you may encounter **non-deterministic runtime behavior**. Code paths that work reliably during development or testing may fail intermittently in production, especially under load, if this characteristic is ignored.
+
+---
+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-advanced-search-filters-2.md

@@ -0,0 +1,44 @@
+# Data fetching — User task support — Advanced search filters (2)
+
+Example
+
+```
+POST /v2/user-tasks/search
+
+{
+  "filter": {
+    "assignee": "demo",
+    "processInstanceKey": "22456786958",
+    "candidateGroups": { "$neq": "external-supervisor", "$like": "external-*" }
+  }
+}
+```
+
+The top-level filters `assignee`, `processInstanceKey`, and `candidateGroups` are connected by an AND operator. Likewise, the `$neq` and `$like` advanced filter operators inside the top-level `candidateGroups` filter are combined by an AND operator.
+
+#### Variables
+
+Search endpoints can support filtering by variable values. This allows querying for process-related resources based on the values of specific variables that exist in their respective scope. For example, user task search supports filtering using the `localVariables` array and defining filter criteria for specific variables.
+
+For variable values, the advanced filter criteria outlined above for fields apply.
+
+Example
+
+```
+POST /v2/user-tasks/search
+
+{
+  "filter": {
+    "localVariables" :  [
+      { "name": "orderVolume", "value": "10000" },
+      { "name": "price", "value": { "$lt": "500" } },
+      { "name": "skipped", "value": { "$exists": false } }
+    ]
+  }
+}
+```
+
+This filters for user tasks containing at least the variables `orderVolume` with a value of `10000` and `price` with a value lower than `500`, not containing variable `skipped`.
+
+---
+Source: https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-data-fetching