openapi: 3.0.0

info:
  title: ZenBPM OpenAPI
  description: REST API for ZenBPM
  version: 1.1.0
  contact:
    name: API Support
    email: info@pbinitiative.org
  license:
    name: AGPL
    url: https://www.gnu.org/licenses/agpl-3.0.en.html

servers:
  - url: http://localhost:8080/v1

tags:
  - name: process-definition
  - name: process-instance
  - name: dmn-resource-definition
  - name: decision-definition
  - name: decision-instance
  - name: job
  - name: message
  - name: incident
  - name: test

paths:
  /dmn-resource-definitions:
    post:
      operationId: createDmnResourceDefinition
      summary: Deploy a new dmn resource definition
      tags:
        - dmn-resource-definition
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: string
              format: xml
            example: |
              <?xml version="1.0" encoding="UTF-8"?>
              <definitions>
                <decision id="loan-approval" name="Loan Approval">
                  ...
                </decision>
              </definitions>
      responses:
        201:
          description: Dmn resource definition deployed
          content:
            application/json:
              schema:
                type: object
                required:
                  - dmnResourceDefinitionKey
                properties:
                  dmnResourceDefinitionKey:
                    type: integer
                    format: int64
              example:
                dmnResourceDefinitionKey: 4503599627370495
        200:
          description: >
            DMN resource definition with the same dmnResourceDefinitionId and version already exists
            and the content is identical — deployment ignored, returns the key of the existing definition.
            If the content differs for the same ID and version, a new version is deployed and 201 is returned instead.
          content:
            application/json:
              schema:
                type: object
                required:
                  - dmnResourceDefinitionKey
                properties:
                  dmnResourceDefinitionKey:
                    type: integer
                    format: int64
              example:
                dmnResourceDefinitionKey: 4503599627370495
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    get:
      operationId: getDmnResourceDefinitions
      summary: Get list of dmn resource definitions
      tags:
        - dmn-resource-definition
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          description: Page number (1-based indexing)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
          description: Number of items per page (max 100)
          example: 10
        - name: onlyLatest
          in: query
          schema:
            type: boolean
            default: false
          description: If true, returns only the latest version of each DMN resource definition grouped by dmnResourceDefinitionId
        - name: sortBy
          in: query
          schema:
            type: string
            enum: [dmnDefinitionName, dmnResourceDefinitionId, version, key]
          description: Sort field
        - $ref: "#/components/parameters/sortOrder"
        - name: dmnResourceDefinitionId
          in: query
          schema:
            type: string
          description: Filter by DMN resource definition ID to get all versions
        - name: dmnDefinitionName
          in: query
          schema:
            type: string
          description: Filter by name (partial match)
        - name: search
          in: query
          schema:
            type: string
          description: Search by DMN resource definition ID or DMN definition name
      responses:
        200:
          description: List of dmn resource definitions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DmnResourceDefinitionsPage"
              example:
                items:
                  - key: 4503599627370496
                    version: 2
                    dmnResourceDefinitionId: "loan-approval"
                    dmnDefinitionName: "Loan Approval Decision"
                  - key: 4503599627370497
                    version: 1
                    dmnResourceDefinitionId: "credit-score-check"
                    dmnDefinitionName: "Credit Score Check"
                page: 1
                size: 10
                count: 2
                totalCount: 2
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dmn-resource-definitions/{dmnResourceDefinitionKey}:
    get:
      operationId: getDmnResourceDefinition
      summary: Get dmn resource definition
      tags:
        - dmn-resource-definition
      parameters:
        - name: dmnResourceDefinitionKey
          required: true
          in: path
          schema:
            type: integer
            format: int64
          example: 4503599627370495
      responses:
        200:
          description: Dmn resource definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DmnResourceDefinitionDetail"
              example:
                key: 4503599627370495
                version: 2
                dmnResourceDefinitionId: "loan-approval"
                dmnDefinitionName: "Loan Approval Decision"
                dmnData: |
                  <?xml version="1.0" encoding="UTF-8"?>
                  <definitions>
                    <decision id="loan-approval" name="Loan Approval">
                      ...
                    </decision>
                  </definitions>
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /decision-definitions/{decisionId}/evaluate:
    post:
      operationId: evaluateDecision
      summary: Evaluate latest version of decision definition directly in engine
      tags:
        - decision-definition
      parameters:
        - name: decisionId
          required: true
          in: path
          schema:
            type: string
          example: "loan-approval"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - bindingType
              properties:
                bindingType:
                  type: string
                  enum:
                    - latest
                    - deployment #TODO: unsupported
                    - versionTag
                dmnResourceDefinitionId:
                  description: Can be used in combination with bindingType latest
                  type: string
                versionTag:
                  description: Is used in combination with bindingType versionTag
                  type: string
                variables:
                  type: object
            example:
              bindingType: "latest"
              variables:
                age: 25
                income: 50000
      responses:
        200:
          description: Decision Evaluated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvaluatedDRDResult"
              example:
                evaluatedDecisions:
                  - decisionId: "loan-approval"
                    decisionName: "Loan Approval"
                    decisionType: "DECISION_TABLE"
                    decisionDefinitionVersion: 1
                    dmnResourceDefinitionKey: 4503599627370495
                    dmnResourceDefinitionId: "loan-approval"
                    matchedRules:
                      - ruleId: "rule1"
                        ruleIndex: 0
                        evaluatedOutputs:
                          - outputId: "output1"
                            outputName: "approved"
                            outputValue: { "approved": true }
                    decisionOutput: { "approved": true }
                    evaluatedInputs:
                      - inputId: "input1"
                        inputName: "Age"
                        inputExpression: "age"
                        inputValue: { "age": 25 }
                      - inputId: "input2"
                        inputName: "Income"
                        inputExpression: "income"
                        inputValue: { "income": 50000 }
                decisionOutput: { "approved": true }
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_REQUEST"
                message: "The request parameters are invalid"
        404:
          description: Not Found (e.g. decision definition was not found)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "NOT_FOUND"
                message: "No decision definition found for the given decisionId"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "INTERNAL_SERVER_ERROR"
                message: "An unexpected error occurred while evaluating the decision"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_GATEWAY"
                message: "Failed to redirect request to responsible node"

  /decision-instances:
    get:
      operationId: getDecisionInstances
      summary: Get list of decision instances
      tags:
        - decision-instance
      parameters:
        - name: dmnResourceDefinitionKey
          in: query
          schema:
            type: integer
            format: int64
          description: Filter by DMN resource definition key
        - name: dmnResourceDefinitionId
          in: query
          schema:
            type: string
          description: Filter by DMN resource definition ID
        - name: processInstanceKey
          in: query
          schema:
            type: integer
            format: int64
          description: Filter by process instance
        - name: evaluatedFrom
          in: query
          schema:
            type: string
            format: date-time
          description: Filter - evaluated after this date
        - name: evaluatedTo
          in: query
          schema:
            type: string
            format: date-time
          description: Filter - evaluated before this date
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          description: Page number (1-based indexing)
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
          description: Number of items per page (max 100)
        - name: sortBy
          in: query
          schema:
            type: string
            enum: [evaluatedAt, key]
          description: Sort field
        - $ref: "#/components/parameters/sortOrder"
      responses:
        200:
          description: List of decision instances
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionInstancePartitionPage"
              example:
                partitions:
                  - partition: 1
                    count: 156
                    items:
                      - key: 4503599627370600
                        dmnResourceDefinitionKey: 4503599627370495
                        dmnResourceDefinitionId: "loan-approval"
                        processInstanceKey: 4503599627370501
                        flowElementInstanceKey: 4503599627370550
                        evaluatedAt: "2025-08-22T14:30:25Z"
                        inputCount: 3
                        outputCount: 2
                  - partition: 2
                    count: 98
                    items:
                      - key: 9007199254740995
                        dmnResourceDefinitionKey: 4503599627370495
                        dmnResourceDefinitionId: "loan-approval"
                        processInstanceKey: 9007199254740992
                        flowElementInstanceKey: 9007199254740980
                        evaluatedAt: "2025-08-22T15:45:33Z"
                        inputCount: 3
                        outputCount: 2
                page: 1
                size: 10
                count: 2
                totalCount: 254
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_REQUEST"
                message: "The request parameters are invalid"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "INTERNAL_SERVER_ERROR"
                message: "An unexpected error occurred while retrieving decision instances"
        502:
          description: Failed to collect data from responsible nodes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_GATEWAY"
                message: "Failed to collect data from responsible nodes"

  /decision-instances/{decisionInstanceKey}:
    get:
      operationId: getDecisionInstance
      summary: Get decision instance details
      tags:
        - decision-instance
      parameters:
        - name: decisionInstanceKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 4503599627370600
      responses:
        200:
          description: Decision instance details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionInstanceDetail"
              example:
                key: 4503599627370600
                dmnResourceDefinitionKey: 4503599627370495
                dmnResourceDefinitionId: "loan-approval"
                dmnResourceDefinitionVersion: 1
                processInstanceKey: 4503599627370501
                flowElementInstanceKey: 4503599627370550
                evaluatedAt: "2025-08-22T14:30:25Z"
                decisionRequirementsKey: 4503599627370490
                decisionRequirementsId: "loan-drd"
                evaluatedDecisions:
                  - decisionId: "loan-approval"
                    decisionName: "Loan Approval"
                    decisionType: "DECISION_TABLE"
                    evaluationOrder: 1
                    inputs:
                      - inputId: "input_amount"
                        inputName: "Loan Amount"
                        inputExpression: "loanAmount"
                        inputValue: 50000
                    outputs:
                      - outputId: "output_approved"
                        outputName: "Approved"
                        outputValue: true
                    matchedRules:
                      - ruleId: "rule_1"
                        ruleIndex: 0
                        evaluatedOutputs:
                          - outputId: "output_approved"
                            outputName: "Approved"
                            outputValue: true
                decisionOutput:
                  approved: true
        404:
          description: Decision instance not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "NOT_FOUND"
                message: "No decision instance found for the given key"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "INTERNAL_SERVER_ERROR"
                message: "An unexpected error occurred while retrieving decision instance"
        502:
          description: Failed to collect data from responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_GATEWAY"
                message: "Failed to collect data from responsible node"

  /process-definitions:
    post:
      operationId: createProcessDefinition
      summary: Deploy a new process definition
      tags:
        - process-definition
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - resource
              properties:
                resource:
                  type: string
                  format: binary
                  description: BPMN process definition file (.bpmn format only, max 4MB)
            encoding:
              resource:
                contentType: application/octet-stream
      responses:
        201:
          description: Process definition deployed
          content:
            application/json:
              schema:
                type: object
                required:
                  - processDefinitionKey
                properties:
                  processDefinitionKey:
                    type: integer
                    format: int64
              example:
                processDefinitionKey: 4503599627370498
        200:
          description: >
            Process definition with the same BPMN process ID and version already exists
            and the content is identical — deployment ignored, returns the key of the existing definition.
            If the content differs for the same ID and version, a new version is deployed and 201 is returned instead.
          content:
            application/json:
              schema:
                type: object
                required:
                  - processDefinitionKey
                properties:
                  processDefinitionKey:
                    type: integer
                    format: int64
              example:
                processDefinitionKey: 4503599627370498
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_REQUEST"
                message: "The provided BPMN file is invalid: missing required 'process' element"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "INTERNAL_SERVER_ERROR"
                message: "An unexpected error occurred while processing the BPMN file"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_GATEWAY"
                message: "Failed to redirect request to responsible node"
    get:
      operationId: getProcessDefinitions
      summary: Get list of process definitions
      tags:
        - process-definition
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          description: Page number (1-based indexing)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
          description: Number of items per page (max 100)
          example: 10
        - name: onlyLatest
          in: query
          schema:
            type: boolean
            default: false
          description: If true, returns only the latest version of each process definition grouped by bpmnProcessId
        - name: sortBy
          in: query
          schema:
            type: string
            enum: [name, bpmnProcessId, bpmnProcessName, version, key]
          description: Sort field
        - $ref: "#/components/parameters/sortOrder"
        - name: bpmnProcessId
          in: query
          schema:
            type: string
          description: Filter by BPMN process ID to get all versions of a specific process
        - name: search
          in: query
          schema:
            type: string
          description: Filter by BPMN process ID or BPMN process name (partial match)
      responses:
        200:
          description: List of process definitions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessDefinitionsPage"
              example:
                items:
                  - key: 4503599627370498
                    version: 1
                    bpmnProcessId: "loan-application"
                  - key: 4503599627370499
                    version: 2
                    bpmnProcessId: "loan-application"
                  - key: 4503599627370500
                    version: 1
                    bpmnProcessId: "credit-check"
                page: 1
                size: 10
                count: 2
                totalCount: 2
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_REQUEST"
                message: "The request parameters are invalid"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "INTERNAL_SERVER_ERROR"
                message: "An unexpected error occurred while retrieving process definitions"

  /process-definitions/{processDefinitionKey}:
    get:
      operationId: getProcessDefinition
      summary: Get process definition
      tags:
        - process-definition
      parameters:
        - name: processDefinitionKey
          required: true
          in: path
          schema:
            type: integer
            format: int64
          example: 4503599627370498
      responses:
        200:
          description: Process definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessDefinitionDetail"
              example:
                key: 4503599627370498
                version: 1
                bpmnProcessId: "loan-application"
                bpmnData: |
                  <?xml version="1.0" encoding="UTF-8"?>
                  <bpmn:definitions>
                    <bpmn:process id="loan-application" name="Loan Application Process" isExecutable="true">
                      ...
                    </bpmn:process>
                  </bpmn:definitions>
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_REQUEST"
                message: "The provided processDefinitionKey is invalid"
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "NOT_FOUND"
                message: "No process definition found for the given key"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "INTERNAL_SERVER_ERROR"
                message: "An unexpected error occurred while retrieving the process definition"

  /process-definitions/{processDefinitionKey}/statistics:
    get:
      operationId: getProcessDefinitionElementStatistics
      summary: Get running and incident counts per BPMN element
      tags:
        - process-definition
      parameters:
        - name: processDefinitionKey
          required: true
          in: path
          schema:
            type: integer
            format: int64
          example: 4503599627370498
      responses:
        200:
          description: Element statistics as a map of elementId to counts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ElementStatisticsPartitions"
              example:
                partitions:
                  - partition: 1
                    items:
                      Task_CheckApplication:
                        activeCount: 5
                        incidentCount: 2
                      Task_CreditCheck:
                        activeCount: 3
                        incidentCount: 1
                  - partition: 2
                    items:
                      Task_CheckApplication:
                        activeCount: 4
                        incidentCount: 0
                      Task_CreditCheck:
                        activeCount: 6
                        incidentCount: 3
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_REQUEST"
                message: "The provided processDefinitionKey is invalid"
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "NOT_FOUND"
                message: "No process definition found for the given key"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "INTERNAL_SERVER_ERROR"
                message: "An unexpected error occurred while retrieving process definition statistics"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_GATEWAY"
                message: "Failed to redirect request to responsible node"

  /process-definitions/statistics:
    get:
      operationId: getProcessDefinitionStatistics
      summary: Get process definition statistics
      tags:
        - process-definition
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          description: Page number (1-based indexing)
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
          description: Number of items per page (max 100)
        - name: onlyLatest
          in: query
          schema:
            type: boolean
            default: false
          description: If true, returns only the latest version of each process definition
        - name: bpmnProcessIdIn
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by BPMN process ID
        - name: bpmnProcessDefinitionKeyIn
          in: query
          schema:
            type: array
            items:
              type: integer
              format: int64
          description: Filter by process definition key
        - name: search
          in: query
          schema:
            type: string
          description: Search by BPMN process ID or BPMN process name (partial match)
        - name: sortBy
          in: query
          schema:
            type: string
            enum: [name, bpmnProcessId, version, instanceCount, incidentCount]
          description: Sort field
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
          description: Sort direction
      responses:
        200:
          description: Process definition statistics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessDefinitionStatisticsPage"
              example:
                items:
                  - key: 4503599627370498
                    version: 3
                    bpmnProcessId: "loan-application"
                    name: "Loan Application Process"
                    bpmnResourceName: "loan-application.bpmn"
                    instanceCounts:
                      total: 1250
                      active: 45
                      completed: 1180
                      terminated: 20
                      failed: 5
                  - key: 4503599627370510
                    version: 1
                    bpmnProcessId: "order-fulfillment"
                    name: "Order Fulfillment"
                    bpmnResourceName: "order-fulfillment.bpmn"
                    instanceCounts:
                      total: 890
                      active: 120
                      completed: 750
                      terminated: 15
                      failed: 5
                page: 1
                size: 10
                count: 2
                totalCount: 2
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_REQUEST"
                message: "The request parameters are invalid"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "INTERNAL_SERVER_ERROR"
                message: "An unexpected error occurred while retrieving process definition statistics"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_GATEWAY"
                message: "Failed to redirect request to responsible node"

  /process-instances:
    post:
      operationId: createProcessInstance
      summary: Create a new process instance
      tags:
        - process-instance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                processDefinitionKey:
                  type: integer
                  format: int64
                  description: Start the process instance using bpmn process definition identified by processDefinitionKey. ( Takes priority )
                bpmnProcessId:
                  type: string
                  description: Start the process instance using latest bpmn process definition identified by bpmnProcessId.
                variables:
                  type: object
                historyTimeToLive:
                  type: string
                  description: Duration for which process instance data are kept in storage after the process instance ends. If omitted the default will be picked up from engine configuration. (1d8h, 1M5d8h)
                  example: 30d
                businessKey:
                  type: string
                  description: Business key of the process instance used mainly for correlating process instance to the business entity.
              example:
                processDefinitionKey: 4503599627370498
                variables:
                  customerId: "customer-456"
                  amount: 1000
                  applicationDate: "2025-08-22"
      responses:
        201:
          description: Process instance created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessInstance"
              example:
                key: 4503599627370501
                processDefinitionKey: 4503599627370498
                createdAt: "2025-08-22T14:30:25Z"
                state: "active"
                variables:
                  customerId: "customer-456"
                  amount: 1000
                  applicationDate: "2025-08-22"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found (e.g. process definition was not found)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      summary: Get list of running process instances
      operationId: getProcessInstances
      tags:
        - process-instance
      parameters:
        - name: processDefinitionKey
          in: query
          schema:
            type: integer
            format: int64
          description: Key of the process definition
          example: 4503599627370498
        - name: parentProcessInstanceKey
          in: query
          schema:
            type: integer
            format: int64
          description: Key of the parent process instance
          example: 1603294627315478
        - name: businessKey
          in: query
          schema:
            type: string
          description: Business key of the process instance used mainly for correlating process instance to the business entity.
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          description: Page number (1-based indexing)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 10
          description: Number of items per page
          example: 10
        - name: bpmnProcessId
          in: query
          schema:
            type: string
          description: Filter by BPMN process ID (returns instances across all versions)
        - name: sortBy
          in: query
          schema:
            type: string
            enum: [createdAt, key, state, businessKey, bpmnProcessId]
          description: Sort field (applies globally across partitions)
        - $ref: "#/components/parameters/sortOrder"
        - name: createdFrom
          in: query
          schema:
            type: string
            format: date-time
          description: Filter - created after this date
        - name: createdTo
          in: query
          schema:
            type: string
            format: date-time
          description: Filter - created before this date
        - name: state
          in: query
          schema:
            type: string
            enum: [active, completed, terminated, failed]
          description: Filter by state
        - name: activityId
          in: query
          schema:
            type: string
          description: Filter by current activity element ID
        - name: includeChildProcesses
          in: query
          schema:
            type: boolean
      responses:
        200:
          description: List of running process instances
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessInstancePage"
              example:
                partitions:
                  - partition: 1
                    count: 24
                    items:
                      - key: 4503599627370501
                        processDefinitionKey: 4503599627370498
                        bpmnProcessId: "loan-application"
                        createdAt: "2025-08-22T14:30:25Z"
                        state: "active"
                        variables:
                          customerId: "customer-456"
                          amount: 1000
                          applicationDate: "2025-08-22"
                      - key: 4503599627370505
                        processDefinitionKey: 4503599627370498
                        bpmnProcessId: "loan-application"
                        createdAt: "2025-08-22T15:10:12Z"
                        state: "active"
                        variables:
                          customerId: "customer-789"
                          amount: 5000
                          applicationDate: "2025-08-22"
                  - partition: 2
                    count: 18
                    items:
                      - key: 9007199254740992
                        processDefinitionKey: 4503599627370498
                        bpmnProcessId: "loan-application"
                        createdAt: "2025-08-22T15:45:33Z"
                        state: "active"
                        variables:
                          customerId: "customer-101"
                          amount: 7500
                          applicationDate: "2025-08-22"
                page: 1
                size: 10
                count: 3
                totalCount: 42
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to collect data from responsible nodes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /process-instances/{processInstanceKey}:
    get:
      operationId: getProcessInstance
      tags:
        - process-instance
      summary: Get state of a process instance selected by processInstanceKey
      parameters:
        - name: processInstanceKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 4503599627370501
      responses:
        200:
          description: State of a process instance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessInstance"
              example:
                key: 4503599627370501
                processDefinitionKey: 4503599627370498
                createdAt: "2025-08-22T14:30:25Z"
                state: "active"
                variables:
                  customerId: "customer-456"
                  amount: 1000
                  applicationDate: "2025-08-22"
                  taskAssignee: "john.doe"
                  currentStatus: "Application review"

        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to collect data from responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /process-instances/{processInstanceKey}/variables:
    patch:
      operationId: updateProcessInstanceVariables
      summary: Update process instance variables
      tags:
        - process-instance
      parameters:
        - name: processInstanceKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 4503599627370501
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - variables
              properties:
                variables:
                  type: object
            example:
              variables:
                orderAmount: 150.00
                approved: true
                reviewedBy: "john.doe"
                reviewComment: "Approved after verification"
      responses:
        204:
          description: Variables updated
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found (e.g process instance is not found)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict (e.g process instance is not in correct state for this operation)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /process-instances/{processInstanceKey}/variables/{variableName}:
    delete:
      operationId: deleteProcessInstanceVariable
      summary: Delete a process instance variable
      tags:
        - process-instance
      parameters:
        - name: processInstanceKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 4503599627370501
        - name: variableName
          in: path
          required: true
          schema:
            type: string
          example: "temporaryFlag"
      responses:
        204:
          description: Variable deleted
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found (e.g. process instance or variable not found)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict (e.g process instance is not in correct state for this operation)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /process-instances/{processInstanceKey}/child-processes:
    get:
      summary: Get list of running child process instances
      operationId: getChildProcessInstances
      tags:
        - process-instance
      parameters:
        - name: processInstanceKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 4503599627370501
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          description: Page number (1-based indexing)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 10
          description: Number of items per page
          example: 10
        - name: sortBy
          in: query
          schema:
            type: string
            enum: [key, state]
          description: Sort field (applies globally across partitions)
        - $ref: "#/components/parameters/sortOrder"
        - name: state
          in: query
          schema:
            type: string
            enum: [active, completed, terminated, failed]
          description: Filter by state
      responses:
        200:
          description: List of child process instances
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessInstancePage"
              example:
                partitions:
                  - partition: 1
                    items:
                      - key: 4503599627370501
                        processDefinitionKey: 4503599627370498
                        createdAt: "2025-08-22T14:30:25Z"
                        state: "active"
                        variables:
                          customerId: "customer-456"
                          amount: 1000
                          applicationDate: "2025-08-22"
                      - key: 4503599627370505
                        processDefinitionKey: 4503599627370498
                        createdAt: "2025-08-22T15:10:12Z"
                        state: "active"
                        variables:
                          customerId: "customer-789"
                          amount: 5000
                          applicationDate: "2025-08-22"
                  - partition: 2
                    items:
                      - key: 9007199254740992
                        processDefinitionKey: 4503599627370498
                        createdAt: "2025-08-22T15:45:33Z"
                        state: "active"
                        variables:
                          customerId: "customer-101"
                          amount: 7500
                          applicationDate: "2025-08-22"
                page: 1
                size: 10
                count: 3
                totalCount: 3
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to collect data from responsible nodes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /process-instances/{processInstanceKey}/cancel:
    post:
      operationId: cancelProcessInstance
      summary: Cancels a process instance
      tags:
        - process-instance
      parameters:
        - name: processInstanceKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 4503599627370501
      responses:
        204:
          description: Process instance cancelled
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found (e.g. process instance is not found)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict (e.g process instance is not in cancellable state)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /process-instances/{processInstanceKey}/jobs:
    get:
      operationId: getProcessInstanceJobs
      tags:
        - process-instance
      summary: Get list of jobs for a process instance
      parameters:
        - name: processInstanceKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 4503599627370501
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          description: Page number (1-based indexing)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
          description: Number of items per page (max 100)
          example: 10
      responses:
        200:
          description: List of jobs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobPage"
              example:
                items:
                  - key: 4503599627370510
                    elementId: "Task_CheckApplication"
                    type: "user-task"
                    processInstanceKey: 4503599627370501
                    state: "active"
                    createdAt: "2025-08-22T14:30:26Z"
                    variables:
                      formKey: "loan-application-form"
                      assignee: "john.doe"
                  - key: 4503599627370511
                    elementId: "Task_CreditCheck"
                    type: "service-task"
                    processInstanceKey: 4503599627370501
                    state: "completed"
                    createdAt: "2025-08-22T14:32:15Z"
                    variables:
                      result: "approved"
                      score: 85
                page: 1
                size: 10
                count: 2
                totalCount: 2
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to collect data from responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /process-instances/{processInstanceKey}/history:
    get:
      operationId: getHistory
      tags:
        - process-instance
      summary: Get list of visited flow elements for a process instance
      parameters:
        - name: processInstanceKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 4503599627370501
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          description: Page number (1-based indexing)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
          description: Number of items per page (max 100)
          example: 10
        - name: sortBy
          in: query
          schema:
            type: string
            enum: [createdAt]
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
          description: Sort direction
      responses:
        200:
          description: List of activities
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowElementHistoryPage"
              example:
                items:
                  - key: 4503599627370525
                    elementId: "StartEvent_1"
                    processInstanceKey: 4503599627370501
                    createdAt: "2025-08-22T14:30:26Z"
                  - key: 4503599627370526
                    elementId: "Flow_1"
                    processInstanceKey: 4503599627370501
                    createdAt: "2025-08-22T14:30:26Z"
                  - key: 4503599627370527
                    elementId: "Task_CheckApplication"
                    processInstanceKey: 4503599627370501
                    createdAt: "2025-08-22T14:30:27Z"
                page: 1
                size: 10
                count: 3
                totalCount: 3
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to collect data from responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /process-instances/{processInstanceKey}/incidents:
    get:
      operationId: getIncidents
      tags:
        - process-instance
      summary: Get list of incidents for a process instance
      parameters:
        - name: processInstanceKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 4503599627370501
        - name: state
          in: query
          schema:
            type: string
            enum: [resolved, unresolved]
          description: Filter by incident state (omit to get all incidents)
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          description: Page number (1-based indexing)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
          description: Number of items per page (max 100)
          example: 10
      responses:
        200:
          description: List of incidents
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentPage"
              example:
                items:
                  - key: 4503599627370530
                    elementInstanceKey: 4503599627370521
                    elementId: "Task_CheckApplication"
                    processInstanceKey: 4503599627370501
                    message: "Failed to assign task: User not found"
                    createdAt: "2025-08-22T14:35:10Z"
                    executionToken: 123456
                    bpmnProcessId: "loan-application"
                    state: "unresolved"
                  - key: 4503599627370531
                    elementInstanceKey: 4503599627370522
                    elementId: "Task_CreditCheck"
                    processInstanceKey: 4503599627370501
                    message: "External service unavailable"
                    createdAt: "2025-08-22T14:36:22Z"
                    resolvedAt: "2025-08-22T14:45:18Z"
                    executionToken: 123457
                    bpmnProcessId: "loan-application"
                    state: "resolved"
                page: 1
                size: 10
                count: 2
                totalCount: 2
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to collect data from responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /process-instances/{processInstanceKey}/statistics:
    get:
      operationId: getProcessInstanceElementStatistics
      summary: Get running and incident counts per BPMN element for a process instance
      tags:
        - process-instance
      parameters:
        - name: processInstanceKey
          required: true
          in: path
          schema:
            type: integer
            format: int64
          example: 4503599627370501
      responses:
        200:
          description: Element statistics as a map of elementId to counts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ElementStatisticsPartitions"
              example:
                partitions:
                  - partition: 1
                    items:
                      Task_CheckApplication:
                        activeCount: 1
                        incidentCount: 0
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_REQUEST"
                message: "The provided processInstanceKey is invalid"
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "NOT_FOUND"
                message: "No process instance found for the given key"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to collect data from responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /jobs:
    get:
      operationId: getJobs
      tags:
        - job
      summary: Get list of jobs on partitions
      parameters:
        - name: processInstanceKey
          in: query
          schema:
            type: integer
            format: int64
          description: Filter by process instance
        - name: jobType
          in: query
          required: false
          schema:
            type: string
          description: Filter by job type
          example: "service-task"
        - name: assignee
          in: query
          schema:
            type: string
          description: Filter by assignee
        - name: state
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/JobState"
          description: Filter by job state
          example: "active"
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
          description: Page number (1-based indexing)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
          description: Number of items per page (max 100)
          example: 10
        - name: sortBy
          in: query
          schema:
            type: string
            enum: [createdAt, key, type, state]
          description: Sort field
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
          description: Sort direction
      responses:
        200:
          description: List of jobs on partitions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobPartitionPage"
              example:
                partitions:
                  - partition: 1
                    items:
                      - key: 4503599627370540
                        elementId: "Task_ReviewApplication"
                        type: "user-task"
                        processInstanceKey: 4503599627370501
                        state: "active"
                        createdAt: "2025-08-22T15:10:26Z"
                        assignee: "john.doe"
                        retries: 3
                        variables:
                          formKey: "loan-review-form"
                  - partition: 2
                    items:
                      - key: 9007199254740995
                        elementId: "Task_SendNotification"
                        type: "service-task"
                        processInstanceKey: 9007199254740992
                        state: "active"
                        createdAt: "2025-08-22T15:46:33Z"
                        retries: 3
                        variables:
                          notificationType: "email"
                          recipient: "customer@example.com"
                page: 1
                size: 10
                count: 2
                totalCount: 2
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to collect data from responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /jobs/{jobKey}:
    get:
      operationId: getJob
      summary: Get job details
      tags:
        - job
      parameters:
        - name: jobKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 4503599627370540
      responses:
        200:
          description: Job details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
              example:
                key: 4503599627370540
                elementId: "Task_ReviewApplication"
                type: "io.camunda.zeebe:userTask"
                processInstanceKey: 4503599627370501
                state: "active"
                createdAt: "2025-08-22T15:10:26Z"
                assignee: "john.doe"
                retries: 3
                variables:
                  formKey: "loan-review-form"
                  applicationId: "APP-12345"
                  customerName: "Alice Johnson"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to collect data from responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /jobs/{jobKey}/assign:
    post:
      operationId: assignJob
      summary: Assign a job to a user
      tags:
        - job
      parameters:
        - name: jobKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 4503599627370540
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - assignee
              properties:
                assignee:
                  type: string
            example:
              assignee: "john.doe"
      responses:
        204:
          description: Job assigned
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Job not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /jobs/{jobKey}/complete:
    post:
      operationId: completeJob
      tags:
        - job
      summary: Complete a job
      parameters:
        - name: jobKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 4503599627370540
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                variables:
                  type: object
            example:
              variables:
                result: "success"
                transactionId: "tx-789-xyz"
                processedAt: "2025-08-22T15:15:30Z"
      responses:
        201:
          description: Job completed
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /jobs/{jobKey}/fail:
    post:
      operationId: failJob
      tags:
        - job
      summary: Fail a job
      parameters:
        - name: jobKey
          in: path
          required: true
          description: The key of the job to fail.
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                errorCode:
                  type: string
                  description: The error code against which an error catch event is matched.
                variables:
                  type: object
            example:
              errorCode: "123-456-789"
              variables:
                transactionId: "tx-789-xyz"
      responses:
        204:
          description: The job is failed.
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /messages:
    post:
      operationId: publishMessage
      tags:
        - message
      summary: Publish a message
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - correlationKey
                - messageName
              properties:
                correlationKey:
                  type: string
                messageName:
                  type: string
                variables:
                  type: object
            example:
              correlationKey: "011-235-813"
              messageName: "payment-received"
              variables:
                paymentId: "pay-123-abc"
                amount: 1000
                currency: "USD"
                receivedAt: "2025-08-22T16:25:10Z"
      responses:
        201:
          description: Message sent
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "BAD_REQUEST"
                message: "Invalid request payload"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "NOT_FOUND"
                message: "The requested resource was not found"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "TECHNICAL_ERROR"
                message: "An unexpected error occurred while processing the request"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: "CLUSTER_ERROR"
                message: "Failed to redirect request to responsible node"

  /incidents/{incidentKey}/resolve:
    post:
      operationId: resolveIncident
      tags:
        - incident
      summary: Resolve an incident
      parameters:
        - name: incidentKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 4503599627370530
      responses:
        201:
          description: Incident resolved
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /modify/start-process-instance:
    post:
      operationId: StartProcessInstanceOnElements
      summary: Start a new process instance starting at chosen elements
      tags:
        - migration
        - process-instance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - processDefinitionKey
                - startingElementIds
              properties:
                processDefinitionKey:
                  type: integer
                  format: int64
                variables:
                  type: object
                startingElementIds:
                  type: array
                  description: Allows for a start at chosen element id
                  items:
                    type: string
            example:
              processDefinitionKey: 4503599627370498
              variables:
                customerId: "customer-456"
                amount: 1000
                applicationDate: "2025-08-22"
              startingElementIds: ["flowNode-1", "flowNode-2"]
      responses:
        201:
          description: Process instance created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessInstance"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found (e.g. process definition with processDefinitionKey not found)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /modify/process-instance:
    post:
      operationId: ModifyProcessInstance
      summary: Modify process instance
      tags:
        - migration
        - process-instance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - processInstanceKey
              properties:
                processInstanceKey:
                  type: integer
                  format: int64
                variables:
                  type: object
                  description: Sets process instance variables.
                elementInstancesToStart:
                  type: array
                  items:
                    $ref: "#/components/schemas/StartElementInstanceData"
                  description: Starts execution token.
                elementInstancesToTerminate:
                  type: array
                  items:
                    $ref: "#/components/schemas/TerminateElementInstanceData"
                  description: Terminates execution token.
      responses:
        201:
          description: Process instance modified
          content:
            application/json:
              schema:
                type: object
                properties:
                  processInstance:
                    $ref: "#/components/schemas/ProcessInstance"
                  activeElementInstances:
                    type: array
                    items:
                      $ref: "#/components/schemas/ElementInstance"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Failed to redirect request to responsible node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /tests/{nodeId}/start-pprof-server:
    post:
      operationId: testStartPprofServer
      summary: start pprof server
      tags:
        - test
      parameters:
        - name: nodeId
          in: path
          required: true
          schema:
            type: string
            pattern: "^[a-zA-Z0-9-_]+$"
          description: ID of the node to start pprof server on
      responses:
        200:
          description: Pprof server started
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /tests/{nodeId}/stop-pprof-server:
    post:
      operationId: testStopPprofServer
      summary: stop pprof server
      tags:
        - test
      parameters:
        - name: nodeId
          in: path
          required: true
          schema:
            type: string
            pattern: "^[a-zA-Z0-9-_]+$"
          description: ID of the node to stop pprof server on
      responses:
        200:
          description: Pprof server stopped
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    DecisionInstancePartitionPage:
      type: object
      allOf:
        - type: object
          required:
            - partitions
          properties:
            partitions:
              type: array
              items:
                $ref: "#/components/schemas/PartitionDecisionInstances"
        - $ref: "#/components/schemas/PartitionedPageMetadata"
    PartitionDecisionInstances:
      type: object
      required:
        - partition
        - items
      properties:
        partition:
          type: integer
        count:
          type: integer
          description: Total decision instances in this partition
        items:
          type: array
          items:
            $ref: "#/components/schemas/DecisionInstanceSummary"
    DecisionInstanceSummary:
      type: object
      required:
        - key
        - dmnResourceDefinitionKey
        - evaluatedAt
      properties:
        key:
          type: integer
          format: int64
        dmnResourceDefinitionKey:
          type: integer
          format: int64
        processInstanceKey:
          type: integer
          format: int64
        flowElementInstanceKey:
          type: integer
          format: int64
          description: Key of the flow element instance that triggered this decision
        evaluatedAt:
          type: string
          format: date-time
    DecisionInstanceDetail:
      type: object
      required:
        - key
        - dmnResourceDefinitionKey
        - evaluatedAt
        - evaluatedDecisions
      properties:
        key:
          type: integer
          format: int64
        dmnResourceDefinitionKey:
          type: integer
          format: int64
        processInstanceKey:
          type: integer
          format: int64
        flowElementInstanceKey:
          type: integer
          format: int64
          description: Key of the flow element instance that triggered this decision
        evaluatedAt:
          type: string
          format: date-time
        evaluatedDecisions:
          type: array
          items:
            $ref: "#/components/schemas/EvaluatedDecision"
        decisionOutput:
          type: string
          format: json
          x-go-type: json.RawMessage
          description: Final output of the requested decision
    EvaluatedDecision:
      type: object
      properties:
        decisionId:
          type: string
        decisionName:
          type: string
        decisionType:
          type: string
          enum: [DECISION_TABLE, LITERAL_EXPRESSION]
        evaluationOrder:
          type: integer
          description: Order in which this decision was evaluated
        inputs:
          type: array
          items:
            $ref: "#/components/schemas/EvaluatedInput"
        outputs:
          type: array
          items:
            $ref: "#/components/schemas/EvaluatedOutput"
        matchedRules:
          type: array
          items:
            $ref: "#/components/schemas/MatchedRule"
          description: For DECISION_TABLE type only
    EvaluatedInput:
      type: object
      properties:
        inputId:
          type: string
        inputName:
          type: string
        inputExpression:
          type: string
        inputValue:
          description: The evaluated input value (any type)
    EvaluatedOutput:
      type: object
      properties:
        outputId:
          type: string
        outputName:
          type: string
        outputValue:
          description: The output value (any type)
    MatchedRule:
      type: object
      properties:
        ruleId:
          type: string
        ruleIndex:
          type: integer
        evaluatedOutputs:
          type: array
          items:
            $ref: "#/components/schemas/EvaluatedOutput"
    PartitionedPageMetadata:
      type: object
      required:
        - page
        - size
        - count
        - totalCount
      properties:
        page:
          type: integer
          description: Current page number (1-based indexing)
        size:
          type: integer
          description: Number of items per page
        count:
          type: integer
          description: Number of items returned in the current page
        totalCount:
          type: integer
          description: Total number of items available
    PageMetadata:
      type: object
      required:
        - page
        - size
        - count
        - totalCount
      properties:
        page:
          type: integer
          description: Current page number (1-based indexing)
        size:
          type: integer
          description: Number of items per page
        count:
          type: integer
          description: Number of items returned in the current page
        totalCount:
          type: integer
          description: Total number of items available
    PartitionProcessInstances:
      type: object
      required:
        - partition
        - items
      properties:
        partition:
          type: integer
        items:
          type: array
          items:
            $ref: "#/components/schemas/ProcessInstance"
    DmnResourceDefinitionsPage:
      type: object
      allOf:
        - type: object
          required:
            - items
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/DmnResourceDefinitionSimple"
        - $ref: "#/components/schemas/PageMetadata"
    DmnResourceDefinitionSimple:
      type: object
      required:
        - key
        - version
        - dmnResourceDefinitionId
        - dmnDefinitionName
      properties:
        key:
          type: integer
          format: int64
        version:
          type: integer
        dmnResourceDefinitionId:
          type: string
        dmnDefinitionName:
          type: string
    DmnResourceDefinitionDetail:
      type: object
      required:
        - dmnData
      allOf:
        - $ref: "#/components/schemas/DmnResourceDefinitionSimple"
        - type: object
          properties:
            dmnData:
              type: string
    EvaluatedDRDResult:
      type: object
      required:
        - decisionInstanceKey
        - evaluatedDecisions
        - decisionOutput
      properties:
        decisionInstanceKey:
          type: integer
          format: int64
        evaluatedDecisions:
          type: array
          items:
            $ref: "#/components/schemas/EvaluatedDecisionResult"
        decisionOutput: {}
    EvaluatedDecisionResult:
      type: object
      required:
        - decisionId
        - decisionName
        - decisionType
        - decisionDefinitionVersion
        - dmnResourceDefinitionKey
        - dmnResourceDefinitionId
        - matchedRules
        - decisionOutput
        - evaluatedInputs
      properties:
        decisionId:
          type: string
        decisionName:
          type: string
        decisionType:
          type: string
        decisionDefinitionVersion:
          type: integer
        dmnResourceDefinitionKey:
          type: integer
          format: int64
        dmnResourceDefinitionId:
          type: string
        matchedRules:
          type: array
          items:
            $ref: "#/components/schemas/EvaluatedDecisionRule"
        decisionOutput:
          type: object
        evaluatedInputs:
          type: array
          items:
            $ref: "#/components/schemas/EvaluatedDecisionInput"
    EvaluatedDecisionRule:
      type: object
      required:
        - ruleId
        - ruleIndex
        - evaluatedOutputs
      properties:
        ruleId:
          type: string
        ruleIndex:
          type: integer
        evaluatedOutputs:
          type: array
          items:
            $ref: "#/components/schemas/EvaluatedDecisionOutput"
    EvaluatedDecisionInput:
      type: object
      required:
        - inputId
        - inputName
        - inputExpression
        - inputValue
      properties:
        inputId:
          type: string
        inputName:
          type: string
        inputExpression:
          type: string
        inputValue: {}
    EvaluatedDecisionOutput:
      type: object
      required:
        - outputId
        - outputName
        - outputValue
      properties:
        outputId:
          type: string
        outputName:
          type: string
        outputValue:
          type: object
    ProcessDefinitionsPage:
      type: object
      allOf:
        - type: object
          required:
            - items
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/ProcessDefinitionSimple"
        - $ref: "#/components/schemas/PageMetadata"
    ProcessDefinitionSimple:
      type: object
      required:
        - key
        - version
        - bpmnProcessId
      properties:
        key:
          type: integer
          format: int64
        version:
          type: integer
        bpmnProcessId:
          type: string
        bpmnProcessName:
          type: string
          description: Process name from BPMN
    ProcessDefinitionDetail:
      type: object
      required:
        - bpmnData
      allOf:
        - $ref: "#/components/schemas/ProcessDefinitionSimple"
        - type: object
          properties:
            bpmnData:
              type: string
    ElementStatisticCounts:
      type: object
      description: Active and incident counts for a single BPMN element
      required:
        - activeCount
        - incidentCount
      properties:
        activeCount:
          type: integer
          description: Number of active element instances
        incidentCount:
          type: integer
          description: Number of incidents on this element
        completedCount:
          type: integer
          description: Number of completed element instances
        terminatedCount:
          type: integer
          description: Number of terminated (canceled) element instances
    ElementStatistic:
      type: object
      description: Map of elementId to active/incident counts
      additionalProperties:
        $ref: "#/components/schemas/ElementStatisticCounts"
    PartitionElementStatistics:
      type: object
      required:
        - partition
        - items
      properties:
        partition:
          type: integer
        items:
          $ref: "#/components/schemas/ElementStatistic"
    ElementStatisticsPartitions:
      type: object
      required:
        - partitions
      properties:
        partitions:
          type: array
          items:
            $ref: "#/components/schemas/PartitionElementStatistics"
    ProcessDefinitionStatisticsPage:
      type: object
      required:
        - partitions
        - page
        - size
        - count
        - totalCount
      properties:
        partitions:
          type: array
          items:
            $ref: "#/components/schemas/PartitionProcessDefinitionStatistics"
        page:
          type: integer
        size:
          type: integer
        count:
          type: integer
          description: Number of items in current page
        totalCount:
          type: integer
          description: Total number of items across all pages
    PartitionProcessDefinitionStatistics:
      type: object
      required:
        - partition
        - items
      properties:
        partition:
          type: integer
        items:
          type: array
          items:
            $ref: "#/components/schemas/ProcessDefinitionStatistics"
    ProcessDefinitionStatistics:
      type: object
      required:
        - key
        - version
        - bpmnProcessId
        - instanceCounts
      properties:
        key:
          type: integer
          format: int64
        version:
          type: integer
        bpmnProcessId:
          type: string
        name:
          type: string
          description: Process name from BPMN
        instanceCounts:
          $ref: "#/components/schemas/InstanceCounts"
    InstanceCounts:
      type: object
      required:
        - total
        - active
        - completed
        - terminated
        - failed
      properties:
        total:
          type: integer
          description: Total number of process instances
        active:
          type: integer
          description: Number of active instances
        completed:
          type: integer
          description: Number of completed instances
        terminated:
          type: integer
          description: Number of terminated instances
        failed:
          type: integer
          description: Number of failed instances
    ProcessInstancePage:
      type: object
      allOf:
        - type: object
          required:
            - partitions
          properties:
            partitions:
              type: array
              items:
                $ref: "#/components/schemas/PartitionProcessInstances"
        - $ref: "#/components/schemas/PartitionedPageMetadata"
    ProcessInstance:
      type: object
      required:
        - key
        - processDefinitionKey
        - createdAt
        - state
        - variables
        - activeElementInstances
        - processType
      properties:
        key:
          type: integer
          format: int64
        processDefinitionKey:
          type: integer
          format: int64
        bpmnProcessId:
          type: string
        businessKey:
          type: string
        createdAt:
          type: string
          format: date-time
        state:
          type: string
          enum:
            - active
            - completed
            - terminated
            - failed
        parentProcessInstanceKey:
          type: integer
          format: int64
        processType:
          type: string
          enum:
            - default
            - multiInstance
            - subprocess
            - callActivity
        variables:
          type: object
        activeElementInstances:
          type: array
          items:
            $ref: "#/components/schemas/ElementInstance"
    JobPage:
      type: object
      allOf:
        - type: object
          required:
            - items
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/Job"
        - $ref: "#/components/schemas/PageMetadata"
    JobPartitionPage:
      type: object
      allOf:
        - type: object
          required:
            - partitions
          properties:
            partitions:
              type: array
              items:
                $ref: "#/components/schemas/PartitionJobs"
        - $ref: "#/components/schemas/PartitionedPageMetadata"
    PartitionJobs:
      type: object
      required:
        - partition
        - items
      properties:
        partition:
          type: integer
        items:
          type: array
          items:
            $ref: "#/components/schemas/Job"
    Job:
      type: object
      required:
        - key
        - elementId
        - type
        - processInstanceKey
        - state
        - createdAt
        - variables
      properties:
        key:
          type: integer
          format: int64
        elementId:
          type: string
        type:
          type: string
        processInstanceKey:
          type: integer
          format: int64
        state:
          $ref: "#/components/schemas/JobState"
        createdAt:
          type: string
          format: date-time
        variables:
          type: object
        assignee:
          type: string
          description: Assignee (user assigned to this job)
        retries:
          type: integer
          description: Remaining retries
    JobState:
      type: string
      enum:
        - active
        - completed
        - terminated
        - failed
    ElementInstance:
      type: object
      required:
        - elementInstanceKey
        - createdAt
        - state
        - elementId
      properties:
        elementInstanceKey:
          type: integer
          format: int64
        createdAt:
          type: string
          format: date-time
        state:
          type: string
        elementId:
          type: string
    FlowElementHistoryPage:
      type: object
      allOf:
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/FlowElementHistory"
        - $ref: "#/components/schemas/PageMetadata"
    TerminateElementInstanceData:
      type: object
      required:
        - elementInstanceKey
      properties:
        elementInstanceKey:
          type: integer
          format: int64
      example:
        elementId: "flow-node-1"
    StartElementInstanceData:
      type: object
      required:
        - elementId
      properties:
        elementId:
          type: string
          description: Element instance is created at this element.
      example:
        elementId: "flow-node-1"
    FlowElementHistory:
      type: object
      required:
        - key
        - processInstanceKey
        - createdAt
        - elementId
      properties:
        key:
          type: integer
          format: int64
        processInstanceKey:
          type: integer
          format: int64
        createdAt:
          type: string
          format: date-time
        elementId:
          type: string
    IncidentPage:
      type: object
      allOf:
        - type: object
          required:
            - items
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/Incident"
        - $ref: "#/components/schemas/PageMetadata"
    Incident:
      type: object
      required:
        - key
        - elementInstanceKey
        - elementId
        - processInstanceKey
        - message
        - createdAt
        - executionToken
      properties:
        key:
          type: integer
          format: int64
        elementInstanceKey:
          type: integer
          format: int64
        elementId:
          type: string
        processInstanceKey:
          type: integer
          format: int64
        message:
          type: string
        createdAt:
          type: string
          format: date-time
        resolvedAt:
          type: string
          format: date-time
        executionToken:
          type: integer
          format: int64
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
      example:
        code: "NOT_FOUND"
        message: "Process instance with key 4503599627370501 not found"
  parameters:
    sortOrder:
      name: sortOrder
      in: query
      schema:
        type: string
        enum: [asc, desc]
      description: Sort direction