openapi: 3.0.0

info:
  title: ZenBPM OpenAPI
  description: REST API for ZenBPM
  version: 1.6.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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"
        413:
          $ref: "#/components/responses/PayloadTooLarge"
        415:
          $ref: "#/components/responses/UnsupportedMediaType"

    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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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
                  nullable: true
            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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"
        413:
          $ref: "#/components/responses/PayloadTooLarge"
        415:
          $ref: "#/components/responses/UnsupportedMediaType"

  /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
                    totalCount: 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
                    totalCount: 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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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, size limited by httpServer.maxRequestBodyBytes, 10 MiB by default)
            encoding:
              resource:
                contentType: application/octet-stream, application/xml
      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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"
        413:
          $ref: "#/components/responses/PayloadTooLarge"
        415:
          $ref: "#/components/responses/UnsupportedMediaType"
    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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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:
                partitions:
                  - partition: 1
                    totalCount: 2
                    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
                          withIncident: 0
                      - 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
                          withIncident: 2
                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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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
                  nullable: true
                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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"
        413:
          $ref: "#/components/responses/PayloadTooLarge"
        415:
          $ref: "#/components/responses/UnsupportedMediaType"
    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
            maximum: 100
            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
                    totalCount: 24
                    items:
                      - key: 4503599627370501
                        processDefinitionKey: 4503599627370498
                        bpmnProcessId: "loan-application"
                        createdAt: "2025-08-22T14:30:25Z"
                        state: "active"
                        incidentCount: 1
                        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"
                        incidentCount: 0
                        variables:
                          customerId: "customer-789"
                          amount: 5000
                          applicationDate: "2025-08-22"
                  - partition: 2
                    totalCount: 18
                    items:
                      - key: 9007199254740992
                        processDefinitionKey: 4503599627370498
                        bpmnProcessId: "loan-application"
                        createdAt: "2025-08-22T15:45:33Z"
                        state: "active"
                        incidentCount: 2
                        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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"
        413:
          $ref: "#/components/responses/PayloadTooLarge"
        415:
          $ref: "#/components/responses/UnsupportedMediaType"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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
            maximum: 100
            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
                    totalCount: 2
                    items:
                      - key: 4503599627370501
                        processDefinitionKey: 4503599627370498
                        createdAt: "2025-08-22T14:30:25Z"
                        state: "active"
                        incidentCount: 1
                        variables:
                          customerId: "customer-456"
                          amount: 1000
                          applicationDate: "2025-08-22"
                      - key: 4503599627370505
                        processDefinitionKey: 4503599627370498
                        createdAt: "2025-08-22T15:10:12Z"
                        state: "active"
                        incidentCount: 0
                        variables:
                          customerId: "customer-789"
                          amount: 5000
                          applicationDate: "2025-08-22"
                  - partition: 2
                    totalCount: 1
                    items:
                      - key: 9007199254740992
                        processDefinitionKey: 4503599627370498
                        createdAt: "2025-08-22T15:45:33Z"
                        state: "active"
                        incidentCount: 2
                        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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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: 4503599627370500
                    elementInstanceKey: 4503599627370900
                    state: "active"
                    createdAt: "2025-08-22T14:30:26Z"
                    inputVariables:
                      formKey: "loan-application-form"
                      assignee: "john.doe"
                  - key: 4503599627370511
                    elementId: "Task_CreditCheck"
                    type: "service-task"
                    processInstanceKey: 4503599627370501
                    elementInstanceKey: 4503599627370901
                    state: "completed"
                    createdAt: "2025-08-22T14:32:15Z"
                    inputVariables:
                      applicantId: "APP-12345"
                      creditScoreThreshold: 80
                    outputVariables:
                      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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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: 1000
            default: 10
          description: Number of items per page (max 1000)
          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"
                    elementType: "START_EVENT"
                    processInstanceKey: 4503599627370501
                    createdAt: "2025-08-22T14:30:26Z"
                  - key: 4503599627370526
                    elementId: "Flow_1"
                    elementType: "SEQUENCE_FLOW"
                    processInstanceKey: 4503599627370501
                    createdAt: "2025-08-22T14:30:26Z"
                  - key: 4503599627370527
                    elementId: "Task_CheckApplication"
                    elementType: "SERVICE_TASK"
                    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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /process-instances/{processInstanceKey}/event-subscriptions/messages:
    get:
      operationId: getProcessInstanceMessageSubscriptions
      tags:
        - process-instance
      summary: Get message event subscriptions for a process instance
      parameters:
        - name: processInstanceKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
        - name: state
          in: query
          schema:
            $ref: "#/components/schemas/EventSubscriptionState"
      responses:
        200:
          description: List of message subscriptions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageSubscriptionPage"
        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: Cluster error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /process-instances/{processInstanceKey}/event-subscriptions/timers:
    get:
      operationId: getProcessInstanceTimerSubscriptions
      tags:
        - process-instance
      summary: Get timer event subscriptions for a process instance
      parameters:
        - name: processInstanceKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
        - name: state
          in: query
          schema:
            $ref: "#/components/schemas/EventSubscriptionState"
      responses:
        200:
          description: List of timer subscriptions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TimerSubscriptionPage"
        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: Cluster error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /process-instances/{processInstanceKey}/event-subscriptions/errors:
    get:
      operationId: getProcessInstanceErrorSubscriptions
      tags:
        - process-instance
      summary: Get error event subscriptions for a process instance
      parameters:
        - name: processInstanceKey
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
        - name: state
          in: query
          schema:
            $ref: "#/components/schemas/EventSubscriptionState"
      responses:
        200:
          description: List of error subscriptions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorSubscriptionPage"
        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: Cluster error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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
                    totalCount: 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
                        inputVariables:
                          formKey: "loan-review-form"
                  - partition: 2
                    totalCount: 1
                    items:
                      - key: 9007199254740995
                        elementId: "Task_SendNotification"
                        type: "service-task"
                        processInstanceKey: 9007199254740992
                        state: "active"
                        createdAt: "2025-08-22T15:46:33Z"
                        retries: 3
                        inputVariables:
                          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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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: "zenbpm:userTask"
                processInstanceKey: 4503599627370501
                state: "active"
                createdAt: "2025-08-22T15:10:26Z"
                assignee: "john.doe"
                retries: 3
                inputVariables:
                  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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"
        413:
          $ref: "#/components/responses/PayloadTooLarge"
        415:
          $ref: "#/components/responses/UnsupportedMediaType"

  /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
                  nullable: true
            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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"
        413:
          $ref: "#/components/responses/PayloadTooLarge"
        415:
          $ref: "#/components/responses/UnsupportedMediaType"

  /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
                  nullable: true
            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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"
        413:
          $ref: "#/components/responses/PayloadTooLarge"
        415:
          $ref: "#/components/responses/UnsupportedMediaType"

  /messages:
    post:
      operationId: publishMessage
      tags:
        - message
      summary: Publish a message
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - messageName
              properties:
                correlationKey:
                  type: string
                messageName:
                  type: string
                variables:
                  type: object
                  nullable: true
            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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"
        413:
          $ref: "#/components/responses/PayloadTooLarge"
        415:
          $ref: "#/components/responses/UnsupportedMediaType"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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
                  nullable: true
                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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"
        413:
          $ref: "#/components/responses/PayloadTooLarge"
        415:
          $ref: "#/components/responses/UnsupportedMediaType"

  /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
                  nullable: true
                  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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"
        413:
          $ref: "#/components/responses/PayloadTooLarge"
        415:
          $ref: "#/components/responses/UnsupportedMediaType"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

  /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"
        405:
          $ref: "#/components/responses/MethodNotAllowed"

components:
  responses:
    MethodNotAllowed:
      description: The HTTP method is not allowed for the requested path.
      headers:
        Allow:
          description: Allowed HTTP methods for the requested path.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            code: "METHOD_NOT_ALLOWED"
            message: "method not allowed"
    PayloadTooLarge:
      description: The request body exceeds the configured size limit (httpServer.maxRequestBodyBytes, 10 MiB by default).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            code: "PAYLOAD_TOO_LARGE"
            message: "http: request body too large"
    UnsupportedMediaType:
      description: The request body content type is not supported by the operation.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            code: "UNSUPPORTED_MEDIA_TYPE"
            message: "unsupported content type"
  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
        - totalCount
      properties:
        partition:
          type: integer
        totalCount:
          type: integer
          description: Total number of items available 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
        - totalCount
      properties:
        partition:
          type: integer
        totalCount:
          type: integer
          description: Total number of items available in this partition
        items:
          type: array
          items:
            $ref: "#/components/schemas/ProcessInstancesSimple"
    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
        - totalCount
      properties:
        partition:
          type: integer
        totalCount:
          type: integer
          description: Total number of items available in this partition
        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
        - withIncident
      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
        withIncident:
          type: integer
          description: >
            Number of process instances that currently have at least one
            directly associated unresolved incident. Each process instance is
            counted once, regardless of how many incidents it has, and
            regardless of its state (i.e. active, completed, terminated or
            failed). Incidents associated with nested subprocess or
            multi-instance scopes are not rolled up to their parent instance.
    ProcessInstancePage:
      type: object
      allOf:
        - type: object
          required:
            - partitions
          properties:
            partitions:
              type: array
              items:
                $ref: "#/components/schemas/PartitionProcessInstances"
        - $ref: "#/components/schemas/PartitionedPageMetadata"
    ProcessInstance:
      allOf:
        - $ref: "#/components/schemas/ProcessInstancesSimple"
        - type: object
          required:
            - activeElementInstances
          properties:
            activeElementInstances:
              type: array
              items:
                $ref: "#/components/schemas/ElementInstance"
    ProcessInstancesSimple:
      type: object
      required:
        - key
        - processDefinitionKey
        - createdAt
        - state
        - variables
        - 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:
          $ref: "#/components/schemas/ProcessInstanceState"
        parentProcessInstanceKey:
          type: integer
          format: int64
        processType:
          $ref: "#/components/schemas/ProcessInstanceProcessType"
        variables:
          type: object
        incidentCount:
          type: integer
          description: >
            Number of currently unresolved incidents directly associated with
            this process instance. Present on process-instance list responses
            and omitted from responses where the count is not calculated.
            Zero when the listed instance has no open incidents.
    ProcessInstanceProcessType:
      type: string
      enum:
        - default
        - multiInstance
        - subprocess
        - callActivity
    ProcessInstanceState:
      type: string
      enum:
        - active
        - completed
        - terminated
        - failed
    EventSubscriptionState:
      type: string
      enum:
        - active
        - compensated
        - compensating
        - completed
        - completing
        - failed
        - failing
        - ready
        - terminated
        - terminating
        - withdrawn
    MessageSubscription:
      type: object
      required:
        - key
        - elementId
        - processDefinitionKey
        - processInstanceKey
        - messageName
        - state
        - createdAt
      properties:
        key:
          type: integer
          format: int64
        elementInstanceKey:
          type: integer
          format: int64
          nullable: true
        elementId:
          type: string
        processDefinitionKey:
          type: integer
          format: int64
        processInstanceKey:
          type: integer
          format: int64
        messageName:
          type: string
        correlationKey:
          type: string
          nullable: true
        state:
          $ref: "#/components/schemas/EventSubscriptionState"
        createdAt:
          type: string
          format: date-time
    TimerSubscription:
      type: object
      required:
        - key
        - elementId
        - processDefinitionKey
        - processInstanceKey
        - state
        - createdAt
      properties:
        key:
          type: integer
          format: int64
        elementInstanceKey:
          type: integer
          format: int64
          nullable: true
        elementId:
          type: string
        processDefinitionKey:
          type: integer
          format: int64
        processInstanceKey:
          type: integer
          format: int64
        state:
          $ref: "#/components/schemas/EventSubscriptionState"
        createdAt:
          type: string
          format: date-time
        dueDate:
          type: string
          format: date-time
    ErrorSubscription:
      type: object
      required:
        - key
        - elementInstanceKey
        - elementId
        - processDefinitionKey
        - processInstanceKey
        - state
        - createdAt
      properties:
        key:
          type: integer
          format: int64
        elementInstanceKey:
          type: integer
          format: int64
        elementId:
          type: string
        processDefinitionKey:
          type: integer
          format: int64
        processInstanceKey:
          type: integer
          format: int64
        errorCode:
          type: string
          nullable: true
        state:
          $ref: "#/components/schemas/EventSubscriptionState"
        createdAt:
          type: string
          format: date-time
    MessageSubscriptionPage:
      type: object
      allOf:
        - type: object
          required:
            - items
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/MessageSubscription"
        - $ref: "#/components/schemas/PageMetadata"
    TimerSubscriptionPage:
      type: object
      allOf:
        - type: object
          required:
            - items
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/TimerSubscription"
        - $ref: "#/components/schemas/PageMetadata"
    ErrorSubscriptionPage:
      type: object
      allOf:
        - type: object
          required:
            - items
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/ErrorSubscription"
        - $ref: "#/components/schemas/PageMetadata"
    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
        - totalCount
      properties:
        partition:
          type: integer
        totalCount:
          type: integer
          description: Total number of items available in this partition
        items:
          type: array
          items:
            $ref: "#/components/schemas/Job"
    Job:
      type: object
      required:
        - key
        - elementId
        - type
        - elementType
        - processInstanceKey
        - elementInstanceKey
        - state
        - createdAt
        - inputVariables
      properties:
        key:
          type: integer
          format: int64
        elementId:
          type: string
        type:
          type: string
          description: Configurable worker-routing type
        elementType:
          type: string
          description: BPMN element type that created the job
        processInstanceKey:
          type: integer
          format: int64
        elementInstanceKey:
          type: integer
          format: int64
        state:
          $ref: "#/components/schemas/JobState"
        createdAt:
          type: string
          format: date-time
        inputVariables:
          type: object
          description: Variables provided to the job at creation/activation time (from BPMN input mappings)
        outputVariables:
          type: object
          description: Output variables set on job completion or failure (full output before mapping)
        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
        - elementType
        - inputVariables
      properties:
        key:
          type: integer
          format: int64
        processInstanceKey:
          type: integer
          format: int64
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        elementId:
          type: string
        elementType:
          type: string
        inputVariables:
          type: object
          description: Variables provided to the flow element at creation time (from BPMN input mappings)
        outputVariables:
          type: object
          description: Output variables produced by the flow element on completion (after BPMN output mapping)
    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