openapi.yaml

openapi: 3.0.0
info:
  title: QuantumBPM API (Public)
  version: 1.5.0
  description: Public API for the QuantumBPM application. SDKs are generated from this spec.
paths:
  /version:
    get:
      summary: Version
      operationId: GetVersion
      x-required-role: public
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    example: 1.0.0
                  buildTime:
                    type: string
                    example: '2023-10-27T10:00:00Z'
                  commit:
                    type: string
                    example: abcdef123
  /dmn/evaluate/design:
    post:
      summary: Evaluate ad-hoc DMN XML
      operationId: EvaluateDesign
      x-required-role: authenticated
      description: |
        Evaluates DMN XML supplied in the request without storing it. Useful for
        testing decisions during authoring or for one-off evaluations that do
        not need to be tracked. Use the project-scoped evaluation endpoints
        against deployed definitions instead when running production workloads.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - xml
              properties:
                xml:
                  type: string
                  description: DMN XML to evaluate.
                additionalXMLs:
                  type: array
                  description: Additional DMN XML documents whose decisions are imported and may be referenced from `xml`.
                  items:
                    type: string
                context:
                  $ref: '#/components/schemas/FeelContext'
                decisionServices:
                  type: array
                  items:
                    type: string
                  description: Names of decision services to evaluate. If empty, no decision services are evaluated.
                decisions:
                  type: array
                  items:
                    type: string
                  description: Names of decisions or decision services to evaluate. If empty, all decisions in the document are evaluated.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/EvaluationResult'
        '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'
  /dmn/evaluate/design/batch:
    post:
      summary: Batch evaluate ad-hoc DMN XML against multiple inputs
      operationId: EvaluateDesignBatch
      x-required-role: authenticated
      description: |
        Evaluates a single DMN document against many input rows in one request.
        Useful for bulk testing during decision authoring (e.g. running a
        spreadsheet of expected cases through a draft decision table).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchEvaluateDesignRequest'
      responses:
        '200':
          description: Batch evaluation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchEvaluationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /projects:
    get:
      summary: List Projects
      operationId: ListProjects
      x-required-role: authenticated
      description: Lists projects the caller has access to within their account.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create Project
      operationId: CreateProject
      x-required-role: org-admin
      description: |
        Creates a new project. Projects are workspaces that group DMN definitions
        and BPMN processes for execution and access control. The caller is
        automatically added as a project administrator.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Project quota for the caller's tier has been reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /projects/{projectID}:
    get:
      summary: Get Project
      operationId: GetProject
      x-required-role: viewer
      description: Returns the project's metadata.
      parameters:
        - name: projectID
          in: path
          required: true
          description: Identifier of the project to fetch.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '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'
    delete:
      summary: Delete Project
      operationId: DeleteProject
      x-required-role: admin
      description: |
        Permanently deletes a project and all of its data: DMN definitions and
        executions, BPMN resources and instances, jobs, user tasks, messages,
        signals, and members. Running BPMN instances are terminated. This
        action cannot be undone.
      parameters:
        - name: projectID
          in: path
          required: true
          description: Identifier of the project to delete.
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: No Content
        '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'
  /projects/{projectID}/dmn/definitions:
    get:
      summary: List DMN definitions
      operationId: ListDefinitions
      x-required-role: viewer
      description: Lists all definition versions in the project. Each call to `CreateDefinition` produces a new version.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number (1-indexed)
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Number of items per page (max 100)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDefinitionsResponse'
        '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'
    post:
      summary: Create a DMN definition
      operationId: CreateDefinition
      x-required-role: editor
      description: |
        Stores a new DMN definition. Each call creates a new version
        (auto-incremented). To replace an existing definition, post the new
        XML with the same `definitionsID`.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDefinitionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Definition'
        '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'
  /projects/{projectID}/dmn/definitions/latest:
    get:
      summary: List latest DMN definitions
      operationId: ListLatestDefinitions
      x-required-role: viewer
      description: Returns the most recent version of each unique definition. Use this for picking a definition to evaluate.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number (1-indexed)
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Number of items per page (max 100)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDefinitionsResponse'
        '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'
  /projects/{projectID}/dmn/definitions/by-definitions-id/{definitionsID}:
    get:
      summary: Get a DMN definition by its DMN definitions id
      description: |
        Looks up a definition by the `id` attribute on the `<definitions>` root
        element of the DMN XML, instead of by the platform-internal `id`.
        Returns the latest version unless a specific version is requested.
      operationId: GetDefinitionByDefinitionsID
      x-required-role: viewer
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionsID
          in: path
          required: true
          schema:
            type: string
          description: Stable identifier from the DMN XML's outer `<definitions id="…">` attribute.
        - name: version
          in: query
          required: false
          schema:
            type: integer
          description: Specific version number (defaults to latest version)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Definition'
        '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'
  /projects/{projectID}/dmn/definitions/by-definitions-id/{definitionsID}/versions:
    get:
      summary: List all versions of a DMN definition
      operationId: ListDefinitionVersions
      x-required-role: viewer
      description: Returns every stored version of a definition identified by its DMN `<definitions id>`, newest to oldest.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionsID
          in: path
          required: true
          schema:
            type: string
          description: Stable identifier from the DMN XML's outer `<definitions id="…">` attribute.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number (1-indexed)
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Number of items per page (max 100)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDefinitionsResponse'
        '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'
  /projects/{projectID}/dmn/definitions/by-definitions-id/{definitionsID}/evaluate:
    post:
      summary: Evaluate a DMN definition by its DMN definitions id
      description: |
        Evaluates a stored DMN definition addressed by its `<definitions id>`
        XML attribute. Useful when callers know definitions by their DMN-level
        identifier rather than the platform's internal `id`. Defaults to the
        latest deployed version.
      operationId: EvaluateByDefinitionsID
      x-required-role: executor
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionsID
          in: path
          required: true
          schema:
            type: string
          description: Stable identifier from the DMN XML's outer `<definitions id="…">` attribute.
        - name: version
          in: query
          required: false
          schema:
            type: integer
          description: Specific version number (defaults to latest version)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluateStoredRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/EvaluationResult'
        '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'
  /projects/{projectID}/dmn/definitions/{definitionID}:
    get:
      summary: Get a DMN definition
      operationId: GetDefinition
      x-required-role: viewer
      description: Returns a single definition version by its platform identifier.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Definition'
        '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'
    put:
      summary: Update a DMN definition's metadata
      operationId: UpdateDefinition
      x-required-role: editor
      description: Modifies metadata (name) of a stored definition. The DMN XML and version are immutable; post a new definition with the same XML `id` to publish a new version.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDefinitionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Definition'
        '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'
    delete:
      summary: Delete a DMN definition version
      operationId: DeleteDefinition
      x-required-role: editor
      description: Permanently deletes a single definition version. Past executions of this version remain in history.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: No Content
        '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'
  /projects/{projectID}/dmn/definitions/{definitionID}/evaluate:
    post:
      summary: Evaluate a stored DMN definition
      operationId: EvaluateStored
      x-required-role: executor
      description: |
        Evaluates a stored DMN definition against the supplied context.
        Each call is recorded in execution history and counts toward the
        account's evaluation quota.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluateStoredRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/EvaluationResult'
        '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'
  /projects/{projectID}/dmn/definitions/{definitionID}/executions:
    get:
      summary: List executions of a DMN definition
      operationId: ListExecutions
      x-required-role: viewer
      description: Returns paginated execution history for a single definition.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionsID
          in: query
          required: false
          schema:
            type: string
          description: Filter by DMN `<definitions id>` (XML id).
        - name: startDate
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter executions after this date (ISO 8601)
        - name: businessId
          in: query
          required: false
          schema:
            type: string
            maxLength: 255
          description: Exact-match filter on the caller-supplied correlation key.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number (1-indexed)
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Number of items per page (max 100)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedExecutionsResponse'
        '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'
  /projects/{projectID}/dmn/decisions:
    get:
      summary: List decisions
      description: |
        Returns one row per unique decision XML id in the project, with the
        latest known version and the owning definition. Useful for picking
        a target decision when wiring a BPMN BusinessRuleTask.
      operationId: ListDecisions
      x-required-role: viewer
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number (1-indexed)
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Number of items per page (max 100)
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: Optional case-insensitive substring match against decision name, decision id, or owning definition name.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDecisionsResponse'
        '500':
          $ref: '#/components/responses/InternalError'
  /projects/{projectID}/dmn/executions:
    get:
      summary: List DMN executions across the project
      operationId: ListProjectExecutions
      x-required-role: viewer
      description: Returns paginated execution history for the entire project, optionally filtered by DMN definition.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionsID
          in: query
          required: false
          schema:
            type: string
          description: Filter by DMN `<definitions id>` (XML id).
        - name: businessId
          in: query
          required: false
          schema:
            type: string
            maxLength: 255
          description: Exact-match filter on the caller-supplied correlation key.
        - name: startDate
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Only return executions at or after this instant (ISO 8601). Bounds the scan and the reported total; omit for the full unbounded history.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number (1-indexed)
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Number of items per page (max 100)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedExecutionsResponse'
        '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'
  /projects/{projectID}/dmn/executions/{executionID}:
    get:
      summary: Get a single DMN execution
      operationId: GetExecution
      x-required-role: viewer
      description: Returns the inputs, outputs, and per-decision evaluation results for a single past execution.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: executionID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
        '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'
  /projects/{projectID}/bpmn/resources:
    get:
      summary: List BPMN resources
      operationId: ListBpmnResources
      x-required-role: viewer
      description: Returns all BPMN resource versions in the project, including drafts and deployed versions.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          required: false
          schema:
            type: integer
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnResourcePaginatedResponse'
    post:
      summary: Create a BPMN resource
      operationId: CreateBpmnResource
      x-required-role: editor
      description: |
        Uploads a new BPMN XML resource as a draft. Drafts can be edited and
        tested but cannot start production instances until they are deployed.
        The XML is validated; invalid XML is rejected.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBpmnResourceRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnResourceDetail'
  /projects/{projectID}/bpmn/resources/{resourceID}:
    get:
      summary: Get a BPMN resource
      operationId: GetBpmnResource
      x-required-role: viewer
      description: Returns the XML and parsed metadata for a single resource version.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: resourceID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnResourceDetail'
    put:
      summary: Update a draft BPMN resource
      operationId: UpdateBpmnResource
      x-required-role: editor
      description: |
        Replaces the XML of an existing draft resource. Once a resource has
        been deployed it is immutable; deploy a new version instead.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: resourceID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBpmnResourceRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnResourceDetail'
        '409':
          description: Conflict - resource is already deployed
    delete:
      summary: Delete a BPMN resource version
      operationId: DeleteBpmnResource
      x-required-role: editor
      description: |
        Permanently deletes a single resource version. Past instances of this
        version remain in history. Refused with 409 Conflict while any version
        of any process inside the resource still has running instances.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: resourceID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: No Content
        '409':
          description: Conflict - resource has running instances
  /projects/{projectID}/bpmn/resources/{resourceID}/deploy:
    post:
      summary: Deploy a BPMN resource
      operationId: DeployBpmnResource
      x-required-role: editor
      description: |
        Marks all processes inside the resource as executable, making them
        available to start instances of. Deployment is one-way; to change a
        deployed resource, upload a new version and deploy that.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: resourceID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /projects/{projectID}/bpmn/resources/{resourceID}/test:
    post:
      summary: Start a test instance from a draft resource
      operationId: StartBpmnTestInstance
      x-required-role: editor
      description: |
        Starts a process instance against a draft (non-deployed) resource.
        Useful for trying out an in-progress design before deploying.
        Test instances run with the same engine as production but are flagged
        so they can be filtered out of dashboards.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: resourceID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartBpmnTestInstanceRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  workflowID:
                    type: string
                    description: Stable execution identifier of the new test instance.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /projects/{projectID}/bpmn/resources/latest:
    get:
      summary: List the latest version of each BPMN resource
      operationId: ListLatestBpmnResources
      x-required-role: viewer
      description: Returns one entry per unique BPMN definitions id, with the most recent version's metadata.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnResourceSummaryPaginatedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /projects/{projectID}/bpmn/resources/by-definitions-id/{definitionsID}:
    get:
      summary: List all versions of a BPMN resource
      operationId: ListBpmnResourcesByDefinitionsID
      x-required-role: viewer
      description: Returns every stored version of a resource identified by the BPMN XML's outer `definitions` id, oldest to newest.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionsID
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnResourcePaginatedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /projects/{projectID}/bpmn/validate:
    post:
      summary: Validate BPMN XML without saving
      operationId: ValidateBpmnXml
      x-required-role: editor
      description: |
        Parses BPMN XML and reports any structural errors or warnings.
        Useful for showing inline validation in design tools without
        committing the resource. The same checks are run server-side
        before storing or deploying a resource.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateBpmnResourceRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnValidateResponse'
  /projects/{projectID}/bpmn/instances:
    get:
      summary: List BPMN instances
      operationId: ListBpmnInstances
      x-required-role: viewer
      description: Returns paginated process instances in the project, optionally filtered by definition or status.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionID
          in: query
          required: false
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - RUNNING
              - COMPLETED
              - FAILED
              - CANCELED
        - name: hasIncident
          in: query
          required: false
          description: |
            Filter by whether the instance has at least one unresolved incident.
            Omit to return all instances regardless of incident status; pass
            `true` to show only instances that need operator attention; pass
            `false` to exclude blocked instances.
          schema:
            type: boolean
        - name: suspended
          in: query
          required: false
          description: |
            Filter by effective suspension - either scope counts. `true` → only
            instances paused at instance scope (`suspendedAt` set) or whose
            definition is paused (`definitionSuspended`); `false` → only
            instances paused at neither scope. Omit for no filter. Read those
            two row fields to tell the scopes apart; resume acts on one scope
            at a time.
          schema:
            type: boolean
        - name: createdAfter
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: |
            Only return instances created at or after this timestamp. Strongly
            recommended for monitoring views - terminal-state instance rows
            accumulate indefinitely, and unfiltered queries grow linearly with
            that history.
        - name: businessId
          in: query
          required: false
          schema:
            type: string
            maxLength: 255
          description: Exact-match filter on the caller-supplied correlation key set at start time.
        - name: page
          in: query
          required: false
          schema:
            type: integer
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnInstancePaginatedResponse'
    post:
      summary: Start a BPMN process instance
      operationId: StartBpmnInstance
      x-required-role: executor
      description: |
        Starts a new instance of a deployed BPMN process. The returned
        `workflowID` is the stable execution identifier - use it to fetch
        state, send signals/messages, complete user tasks, etc.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartBpmnInstanceRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  workflowID:
                    type: string
                    description: Stable execution identifier of the new instance.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /projects/{projectID}/bpmn/instances/{workflowID}:
    get:
      summary: Get BPMN instance state
      operationId: GetBpmnInstance
      x-required-role: viewer
      description: |
        Returns the full runtime state of a process instance - current variables,
        activity history, active scopes, and any unresolved incidents. Use this
        to render dashboards or to drive operational decisions on a single
        instance.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnInstanceState'
    delete:
      summary: Cancel a BPMN instance
      operationId: CancelBpmnInstance
      x-required-role: editor
      description: |
        Cancels a running instance and all of its active activities, jobs, and
        child instances. Cancellation is best-effort - handlers in flight may
        still complete before the cancel propagates. Cancelled instances move
        to status `CANCELED` and stop consuming further work.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
  /projects/{projectID}/bpmn/instances/{workflowID}/children:
    get:
      summary: List child instances of a BPMN instance
      operationId: GetBpmnInstanceChildren
      x-required-role: viewer
      description: |
        Returns instances that this instance spawned via CallActivity elements.
        Useful for navigating into a multi-level process hierarchy (parents
        can be discovered via `parentWorkflowID` on the child).
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnInstanceChildrenResponse'
  /projects/{projectID}/bpmn/instances/{workflowID}/variables:
    get:
      summary: Get BPMN instance variables
      operationId: GetBpmnInstanceVariables
      x-required-role: viewer
      description: Returns the current variables in the root scope of a running or completed instance.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  variables:
                    type: object
                    additionalProperties: true
                    x-go-type: VariableMap
    put:
      summary: Update BPMN instance variables
      operationId: UpdateBpmnInstanceVariables
      x-required-role: editor
      description: |
        Sets or replaces variables in the root scope of a running instance.
        The new values become visible to subsequent activities and FEEL
        expressions immediately. Existing variable keys not present in the
        payload are kept; pass `null` to clear a key.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                variables:
                  type: object
                  additionalProperties: true
                  x-go-type: VariableMap
              required:
                - variables
      responses:
        '200':
          description: OK
  /projects/{projectID}/bpmn/instances/{workflowID}/incidents/{incidentID}/resolve:
    post:
      summary: Resolve an incident and retry the failed activity
      operationId: ResolveBpmnIncident
      x-required-role: editor
      description: |
        Marks an incident as resolved and re-runs the activity that produced it.
        Optional `variables` are merged into the activity's scope before retry -
        use this to fix the input that caused the failure (e.g. correct a value
        that triggered a FEEL evaluation error).
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: path
          required: true
          schema:
            type: string
        - name: incidentID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                variables:
                  type: object
                  additionalProperties: true
                  x-go-type: VariableMap
      responses:
        '200':
          description: OK
  /projects/{projectID}/bpmn/incidents:
    get:
      summary: List BPMN incidents
      operationId: ListBpmnIncidents
      x-required-role: viewer
      description: |
        Cross-instance audit listing of incidents in the project. By default
        returns open incidents first (unresolved), ordered by recency.
        Filterable by definition, error type, status, and time window.

        Each row carries the parent process metadata (processID, processName)
        so a single page render needs no follow-up queries against the
        instances endpoint. Click-through to a specific instance still uses
        the workflow-scoped detail endpoint.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionID
          in: query
          required: false
          description: Restrict to incidents on instances of a single process definition.
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: query
          required: false
          description: Restrict to incidents on a single instance - useful for an instance-detail "all incidents ever raised here" view that includes resolved rows.
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: |
            Filter by lifecycle status. `open` returns unresolved incidents;
            `resolved` returns only resolved ones. Omit to return both.
          schema:
            type: string
            enum:
              - open
              - resolved
        - name: errorType
          in: query
          required: false
          description: Restrict to a single error category (matches `BpmnIncidentRecord.errorType`).
          schema:
            type: string
            enum:
              - BpmnError
              - EscalationError
              - CompensationError
              - FeelError
              - NoHandler
              - GatewayNoMatch
              - TimerResolution
              - LinkNotFound
              - MigrationError
              - SubscriptionError
              - RotationLimitError
              - SnapshotSizeExceeded
              - CallActivityCanceled
              - ExternalRowRefreshError
              - Unknown
        - name: since
          in: query
          required: false
          description: Earliest `raisedAt` to include (inclusive).
          schema:
            type: string
            format: date-time
        - name: until
          in: query
          required: false
          description: Latest `raisedAt` to include (exclusive).
          schema:
            type: string
            format: date-time
        - name: page
          in: query
          required: false
          schema:
            type: integer
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnIncidentRecordPaginatedResponse'
  /projects/{projectID}/bpmn/instances/{workflowID}/migrate:
    post:
      summary: Migrate a running instance to a newer process version
      operationId: MigrateBpmnInstance
      x-required-role: editor
      description: |
        Moves a running instance from its current process version to a newer
        one. Element mappings tell the engine how to translate active tokens
        between versions; unmapped element ids must match by id between source
        and target. Validate the migration plan first via `MigrateValidate`.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MigrateBpmnInstanceRequest'
      responses:
        '200':
          description: OK
  /projects/{projectID}/bpmn/instances/{workflowID}/migrate/validate:
    post:
      summary: Validate a migration plan without executing it
      operationId: ValidateBpmnInstanceMigration
      x-required-role: editor
      description: |
        Returns the issues a migration plan would hit if executed: missing
        mappings, incompatible element types, active boundary events that
        would be orphaned, etc. Run this before `Migrate` to surface problems
        to the user.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MigrateBpmnInstanceRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MigrationValidationResult'
  /projects/{projectID}/bpmn/instances/{workflowID}/modify:
    post:
      summary: Modify a running instance with ad-hoc token operations
      operationId: ModifyBpmnInstance
      x-required-role: admin
      description: |
        Operational recovery tool: applies a sequence of token-level
        instructions (start before a node, cancel a token in a scope) to a
        running instance. Useful for unblocking instances that have ended up
        in unintended states. Restricted to project administrators.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyBpmnInstanceRequest'
      responses:
        '200':
          description: OK
  /projects/{projectID}/bpmn/instances/{workflowID}/adhoc/{adHocNodeID}/trigger:
    post:
      summary: Activate an activity inside a running ad-hoc subprocess
      operationId: TriggerBpmnAdHocNode
      x-required-role: executor
      description: |
        Manually starts one of the activities inside an active ad-hoc
        subprocess. Each call activates a fresh execution; the same activity
        can be triggered repeatedly until the ad-hoc subprocess completes.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: path
          required: true
          schema:
            type: string
        - name: adHocNodeID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - nodeID
              properties:
                nodeID:
                  type: string
      responses:
        '200':
          description: OK
  /projects/{projectID}/bpmn/instances/{workflowID}/adhoc/{adHocNodeID}/variables:
    post:
      summary: Update variables inside a running ad-hoc subprocess
      operationId: SetBpmnAdHocVariables
      x-required-role: executor
      description: |
        Sets variables in the ad-hoc subprocess scope. Active activities and
        the subprocess's completion condition are re-evaluated against the new
        values, which may cause the subprocess to complete or branch.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: path
          required: true
          schema:
            type: string
        - name: adHocNodeID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                variables:
                  type: object
                  additionalProperties: true
                  x-go-type: VariableMap
      responses:
        '200':
          description: OK
  /projects/{projectID}/bpmn/instances/{workflowID}/suspend:
    post:
      summary: Suspend a BPMN instance
      operationId: SuspendBpmnInstance
      x-required-role: admin
      description: |
        Pauses forward token dispatch on a single running instance. The
        instance's lifecycle status stays RUNNING; an orthogonal `suspendedAt`
        flag layers on top. Idempotent - a second call against an already-
        suspended instance is a no-op.

        While suspended: cancel / terminate / migrate / force-rotate / resolve-
        incident / variable update / modify all still work. Parked tokens
        released by signal demuxes or timer fires queue internally and dispatch
        on resume.

        The audit (operator, reason, timestamp) is also recorded in the
        workflow's Temporal history as a `SuspendInstanceEvent` so the timeline
        view on the instance detail page can render the cycle.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuspendBpmnInstanceRequest'
      responses:
        '204':
          description: No Content
  /projects/{projectID}/bpmn/instances/{workflowID}/resume:
    post:
      summary: Resume a suspended BPMN instance
      operationId: ResumeBpmnInstance
      x-required-role: admin
      description: |
        Clears the instance-scope suspension. If the parent definition is also
        suspended the instance remains effectively paused until the definition
        is resumed as well. Idempotent.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
  /projects/{projectID}/bpmn/definitions/{definitionID}/suspend:
    post:
      summary: Suspend every running instance of a BPMN definition
      operationId: SuspendBpmnDefinition
      x-required-role: admin
      description: |
        Pauses every running instance of one deployed process definition AND
        rejects new instance starts on that definition until it is resumed.

        The handler acquires a row-level lock on the definition before flipping
        the flag so a `StartBpmnInstance` racing the suspend can't slip through.
        It then iterates over every running instance (`status='RUNNING'`) and
        sends each one a definition-scope suspend signal via the engine API.
        Instances that were also explicitly instance-suspended stay paused
        after a definition-scope resume - the operator must clear that scope
        too.

        Idempotent. The reason cascades to every affected instance's history
        audit (`SuspendDefinitionEvent`) so the UI can render where the pause
        came from.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionID
          in: path
          required: true
          description: Platform identifier of the process definition version (same UUID `BpmnProcessVersion.id` exposes).
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuspendBpmnDefinitionRequest'
      responses:
        '204':
          description: No Content
        '404':
          description: Definition not found
  /projects/{projectID}/bpmn/definitions/{definitionID}/resume:
    post:
      summary: Resume a suspended BPMN definition
      operationId: ResumeBpmnDefinition
      x-required-role: admin
      description: |
        Clears the definition-scope suspension and fans out a resume signal to
        every running instance of the definition. Instances that were also
        instance-suspended stay paused until their own scope is cleared. New
        instance starts are accepted again once the definition flag clears.
        Idempotent.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: definitionID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: No Content
        '404':
          description: Definition not found
  /projects/{projectID}/bpmn/external-jobs:
    get:
      summary: List external jobs
      operationId: ListBpmnExternalJobs
      x-required-role: viewer
      description: |
        Returns paginated external jobs in the project, with optional filters
        by `taskType`, `status`, and originating instance. Use this to drive
        a dashboard or to inspect a specific job's history. For pulling
        pending work as a job worker, use `Poll` instead.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: taskType
          in: query
          required: false
          schema:
            type: string
          description: Filter jobs by task type
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - PENDING
              - COMPLETED
              - FAILED
              - CANCELED
          description: Filter jobs by status
        - name: workflowID
          in: query
          required: false
          schema:
            type: string
          description: Filter jobs by workflow ID
        - name: businessId
          in: query
          required: false
          schema:
            type: string
            maxLength: 255
          description: Exact-match filter on the caller-supplied correlation key.
        - name: createdAfter
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: |
            Only return jobs created at or after this timestamp. Strongly
            recommended for monitoring views - completed-job records accumulate
            indefinitely, and unfiltered queries grow linearly with that history.
        - name: page
          in: query
          required: false
          schema:
            type: integer
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnExternalJobPaginatedResponse'
  /projects/{projectID}/bpmn/external-jobs/queue-depth:
    get:
      summary: PENDING job counts grouped by taskType
      description: |
        Returns one entry per `taskType` with at least one PENDING job. Useful for
        monitoring queue backlogs and capacity-planning external job workers.
      operationId: GetBpmnExternalJobsQueueDepth
      x-required-role: viewer
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: createdAfter
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Only count jobs created at or after this timestamp. Should match the time-range selector used by the list endpoint so totals stay consistent.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalJobQueueDepthResponse'
  /projects/{projectID}/bpmn/external-jobs/poll:
    post:
      summary: Poll for external jobs (long-poll)
      operationId: PollBpmnExternalJobs
      x-required-role: executor
      description: |
        Long-polls for PENDING jobs of a given `taskType`. Returns a batch of
        jobs (up to `maxJobs`) as soon as any are available, or `204 No Content`
        when the timeout elapses with no work. Each returned job is exclusively
        leased to the caller for `lockDuration` - call `Heartbeat` to extend
        the lock, then `Complete` or `ThrowError` to finalize.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PollBpmnJobRequest'
      responses:
        '200':
          description: One or more jobs acquired
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExternalJob'
        '204':
          description: No jobs available within timeout
  /projects/{projectID}/bpmn/external-jobs/{executionKey}/heartbeat:
    post:
      summary: Extend the lock on an acquired job
      operationId: HeartbeatBpmnExternalJob
      x-required-role: executor
      description: |
        Refreshes the exclusive lock on a job that the caller previously
        acquired via `Poll`. Call this periodically when handling a job that
        takes longer than the original `lockDuration`. Other workers cannot
        claim the job until the lock expires or the job is completed.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: executionKey
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - clientID
              properties:
                clientID:
                  type: string
                lockDuration:
                  type: string
                  description: Duration string e.g. '30s', '2m'. Defaults to 30s.
      responses:
        '200':
          description: Lock extended
        '404':
          description: Job not found, not owned by this client, or already terminated
  /projects/{projectID}/bpmn/external-jobs/{executionKey}/complete:
    post:
      summary: Complete an external job
      operationId: CompleteBpmnExternalJob
      x-required-role: executor
      description: |
        Finalizes an acquired external job successfully. The supplied
        `variables` are merged into the originating instance's scope and the
        process resumes after the service task. Idempotent on the executionKey:
        a second call with the same key after success is a no-op.
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: executionKey
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - workflowID
              properties:
                workflowID:
                  type: string
                  description: Workflow ID returned by the poll response.
                clientID:
                  type: string
                  description: |
                    Optional worker identity (the same `clientID` used to poll).
                    When supplied, the completion is applied only if this worker
                    still holds the job's lock; a stale worker whose lease lapsed
                    and whose job a peer re-acquired is rejected as a no-op.
                    Omit for the legacy unchecked behavior.
                variables:
                  type: object
                  additionalProperties: true
                  x-go-type: VariableMap
      responses:
        '200':
          description: OK
  /projects/{projectID}/bpmn/external-jobs/{executionKey}/error:
    post:
      summary: Fail an external job with a BPMN error code
      operationId: ThrowBpmnExternalJobError
      x-required-role: executor
      description: |
        Reports that the worker could not handle the job.

        The `retryable` flag decides how the failure is treated:

        * `retryable: true` (the default) - a **technical/transient** failure.
          If the job has remaining retries it is requeued for another attempt
          and the retry budget is decremented; the process is NOT notified. Only
          once retries are exhausted is the `errorCode` raised as a BPMN error,
          triggering any matching boundary error event on the originating service
          task (or an incident if none matches).
        * `retryable: false` - a **business** BPMN error. The `errorCode` is
          raised on the process immediately, bypassing the retry budget entirely,
          so a matching boundary error event fires (or an incident is raised)
          without wasting retries. Use this for domain outcomes a retry could
          never fix (e.g. `PAYMENT_DECLINED`). SDK workers send this automatically
          when a handler throws a typed `BpmnError`.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: executionKey
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - errorCode
              properties:
                errorCode:
                  type: string
                clientID:
                  type: string
                  description: |
                    Optional worker identity (the same `clientID` used to poll).
                    When supplied, the error is applied only if this worker still
                    holds the job's lock, so a stale report can't requeue or fail
                    a job a peer is actively holding. Omit for the legacy
                    unchecked behavior.
                retryable:
                  type: boolean
                  default: true
                  description: |
                    Whether this failure should consume the retry budget before
                    reaching the process. `true` (default) treats it as a
                    technical failure: requeue while retries remain, raise the
                    BPMN error only at exhaustion. `false` treats `errorCode` as a
                    business BPMN error and raises it immediately, bypassing
                    retries so a boundary error event fires (or an incident is
                    raised) at once. SDK workers set `false` for a handler-thrown
                    `BpmnError` and `true` for any other exception.
                variables:
                  type: object
                  additionalProperties: true
                  x-go-type: VariableMap
      responses:
        '200':
          description: OK
  /projects/{projectID}/bpmn/external-jobs/batch/complete:
    post:
      summary: Complete External Jobs in Batch
      operationId: CompleteBpmnExternalJobsBatch
      x-required-role: executor
      description: |
        Completes a batch of external jobs in one request. Each item is
        delivered to its instance in parallel and per-item status is returned
        so a partial failure does not sink the whole batch.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              properties:
                clientID:
                  type: string
                  description: |
                    Optional worker identity (the same `clientID` used to poll)
                    applied to every item in the batch - a batch is one worker's
                    report. When supplied, an item is completed only if this
                    worker still holds its lock; items re-acquired by a peer drop
                    out silently. Omit for the legacy unchecked behavior.
                items:
                  type: array
                  minItems: 1
                  maxItems: 200
                  items:
                    type: object
                    required:
                      - executionKey
                      - workflowID
                    properties:
                      executionKey:
                        type: string
                      workflowID:
                        type: string
                      variables:
                        type: object
                        additionalProperties: true
                        x-go-type: VariableMap
      responses:
        '200':
          description: Per-item batch result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalJobBatchResponse'
  /projects/{projectID}/bpmn/external-jobs/batch/error:
    post:
      summary: Fail external jobs in batch
      operationId: ThrowBpmnExternalJobErrorsBatch
      x-required-role: executor
      description: |
        Reports a batch of worker failures in one request. With `retryable: true`
        (the default) each item's remaining retry budget decides whether it
        requeues for another attempt or surfaces its `errorCode` as a BPMN
        error/incident on the originating instance. With `retryable: false` every
        item is treated as a business BPMN error and raised immediately, bypassing
        the retry budget (see the single-job error endpoint for the full
        semantics). Per-item status is returned so a partial failure does not sink
        the whole batch.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              properties:
                clientID:
                  type: string
                  description: |
                    Optional worker identity (the same `clientID` used to poll)
                    applied to every item in the batch - a batch is one worker's
                    report. When supplied, an item is requeued/failed only if this
                    worker still holds its lock; items held by a peer are reported
                    as an error and left untouched. Omit for the legacy unchecked
                    behavior.
                retryable:
                  type: boolean
                  default: true
                  description: |
                    Applies to every item in the batch. `true` (default) consumes
                    each item's retry budget before raising its BPMN error; `false`
                    raises every item's `errorCode` as a business BPMN error
                    immediately, bypassing retries. See the single-job error
                    endpoint for the full semantics.
                items:
                  type: array
                  minItems: 1
                  maxItems: 200
                  items:
                    type: object
                    required:
                      - executionKey
                      - workflowID
                      - errorCode
                    properties:
                      executionKey:
                        type: string
                      workflowID:
                        type: string
                      errorCode:
                        type: string
                      variables:
                        type: object
                        additionalProperties: true
                        x-go-type: VariableMap
      responses:
        '200':
          description: Per-item batch result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalJobBatchResponse'
  /projects/{projectID}/bpmn/user-tasks:
    get:
      summary: List User Tasks
      operationId: ListBpmnUserTasks
      x-required-role: executor
      description: |
        Paginated list of user tasks for the project, optionally filtered by
        workflow, status, assignee, candidate user or candidate group.
        Requires Executor role on the project.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: workflowID
          in: query
          required: false
          schema:
            type: string
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - CREATED
              - COMPLETED
              - CANCELED
              - FAILED
        - name: assignee
          in: query
          required: false
          schema:
            type: string
        - name: candidateUser
          in: query
          required: false
          schema:
            type: string
        - name: candidateGroup
          in: query
          required: false
          schema:
            type: string
        - name: businessId
          in: query
          required: false
          schema:
            type: string
            maxLength: 255
          description: Exact-match filter on the caller-supplied correlation key.
        - name: page
          in: query
          required: false
          schema:
            type: integer
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnUserTaskPaginatedResponse'
  /projects/{projectID}/bpmn/user-tasks/me:
    get:
      summary: List User Tasks for the Caller
      operationId: ListBpmnUserTasksForCaller
      x-required-role: viewer
      description: |
        Returns CREATED user tasks the caller can act on: directly assigned,
        listed in `candidateUsers`, or whose `candidateGroups` overlap any of
        the caller's identity-provider groups. Requires Viewer role on the project.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          required: false
          schema:
            type: integer
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnUserTaskPaginatedResponse'
  /projects/{projectID}/bpmn/user-tasks/{executionKey}:
    get:
      summary: Get User Task
      operationId: GetBpmnUserTask
      x-required-role: viewer
      description: |
        Fetch a single user task by execution key. Allowed for callers with
        Executor (or higher) role on the project, OR for callers who are the
        task's assignee, listed in candidateUsers, or whose identity groups
        overlap candidateGroups - same access semantics as Complete and Error.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: executionKey
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserTask'
        '403':
          description: Forbidden - caller is not Executor and not assigned to the task
        '404':
          description: Not Found
    patch:
      summary: Update User Task Assignment
      operationId: UpdateBpmnUserTaskAssignment
      x-required-role: executor
      description: |
        Reassign / change candidates on a CREATED user task. Returns 404 if the
        task does not exist or is no longer in CREATED state. Requires Executor
        role on the project.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: executionKey
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserTaskAssignmentRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserTask'
        '404':
          description: Not Found
  /projects/{projectID}/bpmn/user-tasks/{executionKey}/complete:
    post:
      summary: Complete User Task
      operationId: CompleteBpmnUserTask
      x-required-role: viewer
      description: |
        Complete a user task with the given variables. Allowed for callers with
        Executor (or higher) role on the project, OR for callers who are the
        task's assignee, listed in candidateUsers, or whose identity groups
        overlap candidateGroups.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: executionKey
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                variables:
                  type: object
                  additionalProperties: true
                  x-go-type: VariableMap
      responses:
        '200':
          description: OK
        '403':
          description: Forbidden - caller is not Executor and not assigned to the task
        '404':
          description: User task not found
  /projects/{projectID}/bpmn/user-tasks/{executionKey}/error:
    post:
      summary: Fail a user task with a BPMN error code
      operationId: ThrowBpmnUserTaskError
      x-required-role: viewer
      description: |
        Reports that the assignee could not complete the task. The `errorCode`
        is raised from the user-task node so any matching boundary error event
        can take over the failure path. Same access semantics as Complete.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: executionKey
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - errorCode
              properties:
                errorCode:
                  type: string
                variables:
                  type: object
                  additionalProperties: true
                  x-go-type: VariableMap
      responses:
        '200':
          description: OK
        '403':
          description: Forbidden - caller is not Executor and not assigned to the task
        '404':
          description: User task not found
  /projects/{projectID}/bpmn/messages:
    post:
      summary: Publish a BPMN message
      operationId: PublishBpmnMessage
      x-required-role: executor
      description: |
        Publishes a message into the project. Each message is delivered to at
        most one waiting catch event whose subscription matches `messageName`
        and whose correlation keys are a subset of `correlationKeys`. If no
        subscriber is currently waiting the message is buffered up to its TTL
        and delivered to the first matching subscriber that registers.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - messageName
              properties:
                messageName:
                  type: string
                  description: Name of the message, matched against catch-event subscriptions.
                correlationKeys:
                  $ref: '#/components/schemas/CorrelationKeys'
                variables:
                  type: object
                  description: Variables to pass into the receiving instance when the message is delivered.
                  additionalProperties: true
                  x-go-type: VariableMap
                ttl:
                  type: string
                  description: |
                    Optional time-to-live for the buffered message. Accepted
                    forms: ISO 8601 duration (`PT1H`, `P1DT12H`), Go duration
                    (`1h30m`), or RFC 3339 absolute timestamp
                    (`2026-12-31T23:59:59Z`). Omitted/empty applies the
                    server's 1-hour default.
      responses:
        '200':
          description: OK
  /projects/{projectID}/bpmn/signals:
    post:
      summary: Publish a BPMN signal
      operationId: PublishBpmnSignal
      x-required-role: executor
      description: |
        Publishes a signal into the project. Unlike messages, signals are
        broadcast: every catch event whose subscription matches `signalName`
        receives the signal. Published signals are buffered for 24 hours, so
        subscribers that register within that window also receive the signal
        (after that the buffered copy is purged).
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - signalName
              properties:
                signalName:
                  type: string
                  description: Name of the signal, matched against catch-event subscriptions.
                variables:
                  type: object
                  description: Variables to pass into each receiving instance.
                  additionalProperties: true
                  x-go-type: VariableMap
                ttl:
                  type: string
                  description: |
                    How long the published signal stays buffered for late
                    subscribers. Accepted forms: ISO 8601 duration (`PT1H`,
                    `P1DT12H`), Go duration (`1h30m`), or RFC 3339 absolute
                    timestamp (`2026-12-31T23:59:59Z`). Omitted/empty applies
                    the server's 24-hour default.
      responses:
        '200':
          description: OK
  /projects/{projectID}/bpmn/processes:
    get:
      summary: List BPMN processes
      operationId: ListBpmnProcesses
      x-required-role: viewer
      description: |
        Returns one entry per unique process ID with aggregated counts of
        running and completed instances across all deployed versions. Use
        `ListBpmnProcessVersions` to drill into specific versions.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: Optional case-insensitive substring match against process id or process name.
        - name: createdAfter
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: |
            Bounds the totalCount aggregate to instances created at or after this
            timestamp. Strongly recommended for monitoring views - instance
            history accumulates indefinitely and unfiltered totals scan the full
            table per definition. runningCount ignores this filter (it is always
            point-in-time).
        - name: suspended
          in: query
          required: false
          schema:
            type: boolean
          description: |
            Filter by paused versions. `true` → only processes with at least one
            paused version; `false` → only processes with none. Omit for no
            filter. This is the cross-process answer to "which definitions are
            paused?"; `suspendedVersionCount` on each row says how many.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnProcessSummaryPaginatedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /projects/{projectID}/bpmn/processes/{processID}/versions:
    get:
      summary: List deployed versions of a BPMN process
      operationId: ListBpmnProcessVersions
      x-required-role: viewer
      description: |
        Returns each deployed version of a single process with its instance
        counts. Useful for picking the source/target version when migrating
        running instances.
      tags:
        - bpmn
      parameters:
        - name: projectID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: processID
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
        - name: createdAfter
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: |
            Bounds the totalCount aggregate to instances created at or after this
            timestamp. See ListBpmnProcesses for rationale. runningCount ignores
            this filter.
        - name: suspended
          in: query
          required: false
          schema:
            type: boolean
          description: |
            Filter by definition-scope suspension. `true` → only paused versions;
            `false` → only active ones. Omit for no filter.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BpmnProcessVersionPaginatedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    FeelNumber:
      type: number
      description: FEEL number. Maps to a decimal value at runtime. Exact decimal semantics end-to-end - the Go types use json.Number so values are never narrowed through float64.
      x-go-type: json.Number
    FeelString:
      type: string
      description: FEEL string. Date, time, and duration values are also represented as strings using the FEEL textual forms (e.g. `"2026-01-31"`, `"PT1H"`).
    FeelBoolean:
      type: boolean
      description: FEEL boolean.
    FeelValue:
      description: A FEEL-typed value as it appears in DMN inputs and outputs. May be a number, string, boolean, list, or nested context.
      oneOf:
        - $ref: '#/components/schemas/FeelNumber'
        - $ref: '#/components/schemas/FeelString'
        - $ref: '#/components/schemas/FeelBoolean'
        - $ref: '#/components/schemas/FeelList'
        - $ref: '#/components/schemas/FeelContext'
      nullable: true
    FeelList:
      type: array
      description: FEEL list. Lists may contain mixed types.
      items:
        $ref: '#/components/schemas/FeelValue'
    FeelContext:
      type: object
      description: FEEL context (a name → value map). The DMN equivalent of an object.
      additionalProperties:
        $ref: '#/components/schemas/FeelValue'
    HitRule:
      type: object
      description: A single rule that matched during decision-table evaluation.
      properties:
        ruleID:
          type: string
          description: ID of the matched rule from the DMN XML.
        outputs:
          $ref: '#/components/schemas/FeelValue'
    EvaluationResult:
      type: object
      description: Result of evaluating a single decision (or decision service / BKM / input data) within a DMN evaluation.
      properties:
        decisionID:
          type: string
          description: ID of the decision element from the DMN XML.
        name:
          type: string
          description: Human-readable name of the decision.
        error:
          type: string
          description: Error message if the decision failed to evaluate. Null on success.
          nullable: true
        type:
          type: string
          description: |
            Kind of DMN element that produced this result:
              * `DECISION` - a decision node, the typical case.
              * `DECISION_SERVICE` - a decision service that aggregates multiple decisions.
              * `BKM` - a business knowledge model (reusable invocable logic).
              * `INPUT_DATA` - an input variable, included for context, not evaluated.
          enum:
            - DECISION
            - DECISION_SERVICE
            - BKM
            - INPUT_DATA
        value:
          $ref: '#/components/schemas/FeelValue'
        hitRules:
          type: array
          description: For decision tables, the rules that matched. Empty for other decision logic.
          items:
            $ref: '#/components/schemas/HitRule'
        dependencies:
          type: array
          description: Results of upstream decisions this decision required. Useful for tracing evaluation paths.
          items:
            $ref: '#/components/schemas/EvaluationResult'
    Error:
      type: object
      description: A standard error response. The HTTP status code carries the broad category; `code` is the machine-readable identifier within that category.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: |
            Machine-readable error category. Values:
              * `BAD_REQUEST` - request is malformed or fails validation.
              * `UNAUTHORIZED` - request lacks or has an invalid authentication token.
              * `FORBIDDEN` - caller is authenticated but lacks permission, or has hit a quota.
              * `NOT_FOUND` - the addressed resource does not exist.
              * `INTERNAL_ERROR` - unexpected server-side failure.
          enum:
            - BAD_REQUEST
            - UNAUTHORIZED
            - FORBIDDEN
            - NOT_FOUND
            - INTERNAL_ERROR
        message:
          type: string
          description: Human-readable description of the failure.
        details:
          type: object
          description: Optional structured context (e.g. the field that failed validation, the limit that was exceeded). Shape is per-error and not generally guaranteed.
          additionalProperties: true
    BatchEvaluateDesignRequest:
      type: object
      description: Payload for batch evaluating ad-hoc DMN XML against multiple input rows.
      properties:
        xml:
          type: string
          description: DMN XML to evaluate.
        inputs:
          type: array
          description: One input context per row to evaluate. At most 500 rows per request.
          maxItems: 500
          items:
            $ref: '#/components/schemas/FeelContext'
    BatchEvaluationResponse:
      type: object
      description: Per-row results from a batch evaluation.
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              executionID:
                type: string
                description: Identifier assigned to this row's evaluation, useful for correlating with logs.
              inputs:
                type: object
                description: The input row that produced these results, echoed for convenience.
                additionalProperties: true
              results:
                type: object
                description: Evaluation results keyed by decision name.
                additionalProperties:
                  $ref: '#/components/schemas/EvaluationResult'
    Project:
      type: object
      description: A workspace that groups DMN definitions and BPMN processes together for access control and execution.
      required:
        - id
        - name
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique project identifier.
        name:
          type: string
          description: Human-readable project name.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the project was created.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of the last modification.
    CreateProjectRequest:
      type: object
      description: Payload for creating a new project. The owning account is inferred from the caller's authentication context.
      required:
        - name
      properties:
        name:
          type: string
          description: Human-readable project name.
    Definition:
      type: object
      description: A stored DMN definition. Each call to CreateDefinition produces a new version of a `definitionsID`.
      required:
        - id
        - name
        - definitionsID
        - xml
        - version
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Platform identifier for this specific definition version.
        name:
          type: string
          description: Human-readable name displayed in the UI.
        definitionsID:
          type: string
          description: Stable identifier from the DMN XML's outer `<definitions id="…">` attribute. Shared across versions.
        xml:
          type: string
          description: The DMN XML body.
        version:
          type: integer
          description: Auto-incremented version number, starting at 1 for the first upload of a `definitionsID`.
        createdBy:
          type: string
          description: User who uploaded this version.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this version was uploaded.
        versionCount:
          type: integer
          description: Total number of stored versions under this `definitionsID`. Populated by the latest-listing endpoint; absent on single-version reads.
    PaginationMetadata:
      type: object
      description: Pagination metadata accompanying paginated list responses.
      required:
        - page
        - pageSize
        - total
        - totalPages
      properties:
        page:
          type: integer
          description: Current page number (1-indexed).
        pageSize:
          type: integer
          description: Number of items per page.
        total:
          type: integer
          description: Total number of items across all pages.
        totalPages:
          type: integer
          description: Total number of pages.
    PaginatedDefinitionsResponse:
      type: object
      description: Page of DMN definition versions.
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Definition'
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
    CreateDefinitionRequest:
      type: object
      description: Payload for creating a new DMN definition version.
      required:
        - name
        - xml
      properties:
        name:
          type: string
          description: Display name.
        xml:
          type: string
          description: DMN XML body.
        version:
          type: integer
          description: Optional explicit version number. If omitted, the server assigns one.
    EvaluateStoredRequest:
      type: object
      description: Payload for evaluating a stored DMN definition.
      required:
        - context
      properties:
        version:
          type: integer
          description: Specific definition version to evaluate. Defaults to the latest version.
        context:
          $ref: '#/components/schemas/FeelContext'
        decisionServices:
          type: array
          items:
            type: string
          description: Names of decision services to evaluate. If empty, no decision services are evaluated.
        decisions:
          type: array
          items:
            type: string
          description: Names of decisions or decision services to evaluate. If empty, all decisions are evaluated.
        businessId:
          type: string
          maxLength: 255
          description: Optional caller-supplied correlation key persisted with the resulting execution row for cross-system tracing.
    UpdateDefinitionRequest:
      type: object
      description: Payload for updating metadata on an existing definition version.
      properties:
        xml:
          type: string
          description: Replacement XML. The `definitionsID` and `version` from the original are preserved.
        version:
          type: integer
          description: Optional explicit version override. Generally not used during update.
        name:
          type: string
          description: New display name.
    Execution:
      type: object
      description: A single recorded DMN evaluation against a stored definition.
      required:
        - id
        - definitionID
        - executedAt
        - inputs
        - outputs
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of this execution.
        definitionID:
          type: string
          format: uuid
          description: Platform identifier of the definition version that was evaluated.
        executedAt:
          type: string
          format: date-time
          description: Timestamp when the evaluation ran.
        executedBy:
          type: string
          description: User or service account that issued the evaluation.
        inputs:
          $ref: '#/components/schemas/FeelContext'
        outputs:
          $ref: '#/components/schemas/FeelValue'
        definitionsID:
          type: string
          description: The DMN XML's `<definitions id="…">` value, useful for grouping executions across versions.
        businessId:
          type: string
          description: Caller-supplied correlation key passed at evaluation time (REST) or inherited from the parent BPMN process (business rule task).
    PaginatedExecutionsResponse:
      type: object
      description: Page of recorded DMN executions.
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Execution'
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
    DecisionInputField:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Variable name the decision expects as input
        typeRef:
          type: string
          description: DMN typeRef (e.g. string, number, boolean) when declared
    DecisionSummary:
      type: object
      description: A unique decision in the project, surfaced for picking from BPMN BusinessRuleTask elements.
      required:
        - decisionID
        - decisionName
        - definitionsID
        - definitionName
        - latestVersion
        - inputFields
      properties:
        decisionID:
          type: string
          description: ID of the decision node from the DMN XML (unique per project).
        decisionName:
          type: string
          description: Human-readable name of the decision.
        definitionsID:
          type: string
          description: Stable identifier from the DMN XML's outer `<definitions id="…">` attribute.
        definitionName:
          type: string
          description: Human-readable name of the parent DMN definition.
        latestVersion:
          type: integer
          description: Highest deployed version that contains this decision.
        inputFields:
          type: array
          description: Declared input variables of the decision (from DMN `InformationRequirement` → `InputData`). Useful for prepopulating BPMN BusinessRuleTask input mappings. Empty when the decision declares no typed inputs.
          items:
            $ref: '#/components/schemas/DecisionInputField'
    PaginatedDecisionsResponse:
      type: object
      description: Page of decisions.
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DecisionSummary'
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
    BpmnResource:
      type: object
      description: A version of a BPMN resource (XML file containing one or more processes).
      required:
        - id
        - name
        - xml
        - definitionsID
        - isDeployed
        - createdBy
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Platform identifier for this specific resource version.
        name:
          type: string
          description: Display name.
        xml:
          type: string
          description: BPMN XML body.
        definitionsID:
          type: string
          description: Stable identifier from the BPMN XML's outer `<definitions id="…">` attribute. Shared across versions.
        isDeployed:
          type: boolean
          description: True once the resource has been deployed and its processes are available to start instances.
        deployedAt:
          type: string
          format: date-time
          description: Timestamp when the resource was deployed. Empty for drafts.
        createdBy:
          type: string
          description: User who uploaded this version.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this version was uploaded.
        hasSuspendedDefinition:
          type: boolean
          description: |
            True when at least one process definition inside this resource version
            is paused. Populated on list endpoints; absent on single-resource
            reads, where the per-process `suspendedAt` is the precise answer.
    BpmnResourcePaginatedResponse:
      type: object
      description: Page of BPMN resource versions.
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BpmnResource'
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
    CreateBpmnResourceRequest:
      type: object
      description: Payload for uploading a BPMN resource version.
      required:
        - name
        - xml
      properties:
        name:
          type: string
          description: Display name.
        xml:
          type: string
          description: BPMN XML body.
    BpmnProcessDefinition:
      type: object
      description: A single deployable process parsed out of a BPMN resource.
      required:
        - id
        - resourceID
        - processID
        - version
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Platform identifier of this process definition. Used as `processDefinitionID` when starting instances.
        resourceID:
          type: string
          format: uuid
          description: Platform identifier of the owning BPMN resource.
        processID:
          type: string
          description: BPMN `id` attribute on the `<process>` element.
        processName:
          type: string
          description: Human-readable name from the BPMN XML.
        version:
          type: integer
          description: Process version. Auto-incremented per `processID` on deploy.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this version became available.
        suspendedAt:
          type: string
          format: date-time
          description: Timestamp at which this process definition was paused. Empty when active.
        suspendReason:
          type: string
          description: Free-text reason captured at suspend time.
    BpmnResourceDetail:
      description: A BPMN resource together with the parsed processes it contains.
      allOf:
        - $ref: '#/components/schemas/BpmnResource'
        - type: object
          properties:
            processes:
              type: array
              description: Parsed processes inside the resource. Empty for resources whose XML has not been deployed yet.
              items:
                $ref: '#/components/schemas/BpmnProcessDefinition'
    StartBpmnTestInstanceRequest:
      type: object
      description: Payload for starting a non-deployed BPMN process instance against a draft resource for testing.
      properties:
        processID:
          type: string
          description: BPMN process ID (the `id` attribute on `<bpmn:process>`) to start. Defaults to the first executable process in the resource.
        variables:
          type: object
          description: Initial process variables.
          additionalProperties: true
          x-go-type: VariableMap
        businessId:
          type: string
          maxLength: 255
          description: Optional caller-supplied correlation key.
    BpmnResourceSummary:
      type: object
      description: One entry per BPMN definitionsID showing the latest version's metadata.
      required:
        - definitionsID
        - latestResourceID
        - name
        - versionCount
        - isDeployed
        - createdAt
      properties:
        definitionsID:
          type: string
          description: Stable BPMN definitions identifier.
        latestResourceID:
          type: string
          format: uuid
          description: Platform identifier of the latest resource version under this `definitionsID`.
        name:
          type: string
          description: Display name from the latest version.
        versionCount:
          type: integer
          description: Total number of stored versions for this `definitionsID`.
        isDeployed:
          type: boolean
          description: Whether the latest version is deployed.
        hasSuspendedDefinition:
          type: boolean
          description: |
            True when any version under this `definitionsID` contains a paused
            process definition - including older versions, since a pause on a
            superseded version is exactly what's hard to find otherwise.
        createdAt:
          type: string
          format: date-time
          description: Upload timestamp of the latest version.
    BpmnResourceSummaryPaginatedResponse:
      type: object
      description: Page of BPMN resource summaries.
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BpmnResourceSummary'
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
    ValidateBpmnResourceRequest:
      type: object
      description: Payload for the BPMN XML validator.
      required:
        - xml
      properties:
        xml:
          type: string
          description: BPMN XML to validate.
    BpmnValidationIssue:
      type: object
      description: A single validation finding produced while parsing BPMN XML.
      required:
        - severity
        - message
      properties:
        severity:
          type: string
          description: Severity of the issue. `error` blocks deploy; `warning` is informational.
          enum:
            - error
            - warning
        elementID:
          type: string
          description: ID of the BPMN element the issue is about. Empty for issues that aren't tied to a specific element.
        message:
          type: string
          description: Human-readable description of the issue.
    BpmnValidateResponse:
      type: object
      description: Result of validating BPMN XML, separated into blocking errors and informational warnings.
      required:
        - errors
        - warnings
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/BpmnValidationIssue'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/BpmnValidationIssue'
    BpmnInstance:
      type: object
      description: A running or completed execution of a BPMN process.
      required:
        - definitionID
        - workflowID
        - status
        - createdAt
      properties:
        definitionID:
          type: string
          format: uuid
          description: ID of the deployed BPMN process definition this instance is running.
        workflowID:
          type: string
          description: Stable execution identifier for this instance. Use this to address the instance in all API calls - fetch state, send signals/messages, complete user tasks, list children, cancel, etc.
        parentWorkflowID:
          type: string
          description: Execution identifier of the parent instance that started this one via a CallActivity. Empty for top-level instances.
        status:
          type: string
          description: Current lifecycle status of the instance.
          enum:
            - RUNNING
            - COMPLETED
            - FAILED
            - CANCELED
            - TERMINATED
            - TIMED_OUT
        startedBy:
          type: string
          description: User or service account that initiated the instance.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the instance was started.
        completedAt:
          type: string
          format: date-time
          description: Timestamp when the instance reached a terminal status. Empty while running.
        hasIncident:
          type: boolean
          description: True when at least one unresolved incident is currently attached to this instance. Computed at query time against the open-incidents index - useful for rendering a "needs attention" indicator in instance lists without paying for a per-row state fetch from the engine.
        suspendedAt:
          type: string
          format: date-time
          description: |
            Timestamp at which this instance was paused at INSTANCE scope. Empty
            when not instance-suspended. The instance may still be effectively
            suspended via its definition - see `definitionSuspended`.
        suspendedBy:
          type: string
          description: Operator who suspended this instance (instance scope). Empty when not instance-suspended.
        suspendReason:
          type: string
          description: Free-text reason captured at suspend time.
        definitionSuspended:
          type: boolean
          description: |
            True when the process definition this instance runs is paused. Token
            dispatch stops while either scope is set, so an instance is
            effectively paused if this is true or `suspendedAt` is present. The
            two stay separate because resume acts on one scope at a time.
        businessId:
          type: string
          description: Caller-supplied correlation key set when the instance was started. Inherited unchanged on child instances spawned via CallActivity.
    BpmnInstancePaginatedResponse:
      type: object
      description: Page of BPMN process instances.
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BpmnInstance'
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
    StartBpmnInstanceRequest:
      type: object
      description: Payload for starting a new BPMN process instance.
      required:
        - processDefinitionID
      properties:
        processDefinitionID:
          type: string
          format: uuid
          description: ID of a deployed `BpmnProcessDefinition` to start.
        variables:
          type: object
          description: Initial process variables. Available to FEEL expressions and service tasks from the first activity onward.
          additionalProperties: true
          x-go-type: VariableMap
        businessId:
          type: string
          maxLength: 255
          description: Optional caller-supplied correlation key (order number, ticket ID, etc.) indexed for filtering and stamped on every child instance, external job, user task, and DMN execution emitted by this process.
    BpmnIncident:
      type: object
      description: An error that halted execution of a BPMN node and requires manual resolution.
      properties:
        incidentID:
          type: string
          description: Unique identifier of this incident.
        nodeID:
          type: string
          description: ID of the BPMN node where the error occurred.
        scopeID:
          type: string
          description: ID of the scope in which the error occurred.
        executionKey:
          type: string
          description: Execution key of the activity that failed.
        parentScopeID:
          type: string
          description: ID of the scope containing `scopeID`, empty for the root scope. Scope IDs are opaque, so this is how a client walks a failure back up the process tree.
        miIndex:
          type: integer
          description: Zero-based multi-instance body index when the failure happened inside one iteration of a multi-instance activity. Absent otherwise.
        errorMessage:
          type: string
          description: Human-readable description of the error.
        errorCode:
          type: string
          description: BPMN error code from the process definition; empty for non-BPMN errors.
        errorType:
          type: string
          description: |
            Category of the error. Values:
              * `BpmnError` - A `bpmn:error` thrown by the process or an external job worker.
              * `EscalationError` - A `bpmn:escalation` raised by the process.
              * `CompensationError` - Failure during compensation handler execution.
              * `FeelError` - A FEEL expression failed to evaluate.
              * `NoHandler` - A thrown error/escalation has no matching catch event.
              * `GatewayNoMatch` - An exclusive gateway evaluated all conditions to false with no default flow.
              * `TimerResolution` - A timer expression could not be parsed or resolved.
              * `LinkNotFound` - A link throw event has no matching link catch.
              * `MigrationError` - A process instance migration could not be applied.
              * `SubscriptionError` - A message/signal listener's registry row could not be written; the listener is dead until resolved.
              * `RotationLimitError` - The instance reached its ContinueAsNew rotation cap.
              * `SnapshotSizeExceeded` - A ContinueAsNew snapshot exceeded the configured size cap.
              * `CallActivityCanceled` - A call-activity child terminated as Canceled out-of-band.
              * `ExternalRowRefreshError` - A migration could not rewrite a parked wait's external row (job, user task or subscription) against the target definition. Resolving re-runs the refresh.
              * `Unknown` - Internal error not classified above.
          enum:
            - BpmnError
            - EscalationError
            - CompensationError
            - FeelError
            - NoHandler
            - GatewayNoMatch
            - TimerResolution
            - LinkNotFound
            - MigrationError
            - SubscriptionError
            - RotationLimitError
            - SnapshotSizeExceeded
            - CallActivityCanceled
            - ExternalRowRefreshError
            - Unknown
        variables:
          type: object
          description: Variables in scope at the time of the error.
          additionalProperties: true
          x-go-type: VariableMap
        timestamp:
          type: integer
          format: int64
          description: Unix epoch milliseconds when the incident was recorded.
    ActiveScope:
      type: object
      description: A scope (sub-process, multi-instance body, or root process) that currently holds at least one live execution token.
      properties:
        scopeID:
          type: string
          description: Unique identifier of this scope instance.
        parentScopeID:
          type: string
          description: ID of the parent scope, empty for the root scope.
        nodeID:
          type: string
          description: ID of the BPMN element that created this scope (e.g. a sub-process node). Empty for the root scope.
        activeNodes:
          type: object
          description: 'Live token count per flow node in this scope, keyed by node ID. A node can hold more than one token at a time (a parallel fork whose branches re-converge without a join, a non-interrupting boundary handler, a loop edge re-entering a node a prior token has not left yet), so the count matters: a presence-only list cannot tell one token from five. Absent keys mean no live token.'
          additionalProperties:
            type: integer
        processVersion:
          type: integer
          description: Version of the process definition active in this scope.
        variables:
          type: object
          description: Variables scoped to this instance, excluding inherited parent-scope variables.
          additionalProperties: true
          x-go-type: VariableMap
    SuspensionEntry:
      type: object
      description: |
        Audit-shaped record of an active suspension at one scope (instance or
        definition). Returned inline on `BpmnInstanceState` - `null` when not
        suspended at that scope. An instance is "effectively suspended" if either
        scope's entry is present; the dispatcher pauses forward token dispatch
        while either flag is set.
      required:
        - suspendedAt
      properties:
        suspendedAt:
          type: integer
          format: int64
          description: Unix epoch nanoseconds at which the suspension was applied.
        suspendedBy:
          type: string
          description: Identifier of the operator (or service account) that initiated the suspension.
        reason:
          type: string
          description: Free-text reason captured at suspend time; surfaces in the operator UI alongside the action.
    BpmnInstanceState:
      type: object
      description: Full runtime state of a BPMN process instance.
      required:
        - resourceID
      properties:
        resourceID:
          type: string
          format: uuid
          description: ID of the BPMN resource (definition file) that produced this instance.
        workflowID:
          type: string
          description: Execution identifier for this instance.
        parentWorkflowID:
          type: string
          description: Execution identifier of the parent instance that started this one via a CallActivity. Empty for top-level instances.
        processId:
          type: string
          description: BPMN process definition ID this instance was started from.
        processVersion:
          type: integer
          description: Version of the BPMN process definition this instance is currently running. Updated by migration operations.
        status:
          type: string
          description: Current lifecycle status of the instance (e.g. RUNNING, COMPLETED, FAILED, TERMINATED).
        variables:
          type: object
          description: All variables currently in scope for the root process.
          additionalProperties: true
          x-go-type: VariableMap
        error:
          type: boolean
          description: True when the instance has an unresolved incident.
        incidents:
          type: array
          description: Active incidents that require resolution before the process can continue.
          items:
            $ref: '#/components/schemas/BpmnIncident'
        activeScopes:
          type: array
          description: Scopes that currently hold at least one live token.
          items:
            $ref: '#/components/schemas/ActiveScope'
        failureReason:
          type: string
          description: Error message from the workflow when status is FAILED.
        instanceSuspension:
          $ref: '#/components/schemas/SuspensionEntry'
          description: |
            Present when this instance has been explicitly suspended by an
            operator. Persisted across CaN rotations. Clear via the resume
            instance endpoint. Composes with `definitionSuspension` - both must
            be null for the instance to dispatch tokens.
        definitionSuspension:
          $ref: '#/components/schemas/SuspensionEntry'
          description: |
            Present when the instance's process definition has been suspended.
            Clear via the resume definition endpoint (the backend fans out to
            every running instance of the definition).
        businessId:
          type: string
          description: Caller-supplied correlation key set when the instance was started.
    BpmnInstanceChildrenResponse:
      type: object
      description: Child instances spawned by a parent instance via CallActivity elements.
      required:
        - children
      properties:
        children:
          type: array
          items:
            $ref: '#/components/schemas/BpmnInstance'
    BpmnIncidentRecord:
      type: object
      description: |
        A persisted incident - the cross-instance audit row that backs the
        "Incidents" view. The same incident is also available in
        `BpmnInstanceState.incidents` while it is still open in the engine; the
        persisted row additionally carries `raisedAt` / `resolvedAt` /
        `resolvedBy` and the parent process metadata so it can be listed and
        filtered without joining back to the instance.
      required:
        - id
        - incidentID
        - workflowID
        - nodeID
        - errorType
        - errorMessage
        - raisedAt
      properties:
        id:
          type: string
          format: uuid
          description: Surrogate row identifier; stable across resolves.
        incidentID:
          type: string
          description: Engine-assigned incident identifier, unique within the workflow.
        workflowID:
          type: string
          description: Identifier of the instance that produced the incident.
        definitionID:
          type: string
          format: uuid
          description: ID of the process definition the instance is running. May be absent when the source definition was deleted.
        processID:
          type: string
          description: BPMN process ID of the parent definition. Convenience field; absent when definitionID is unresolved.
        processName:
          type: string
          description: Human-readable name of the parent process definition.
        nodeID:
          type: string
          description: ID of the BPMN node where the error occurred.
        scopeID:
          type: string
          description: ID of the scope in which the error occurred.
        executionKey:
          type: string
          description: Execution key of the activity that failed.
        parentScopeID:
          type: string
          description: ID of the scope containing `scopeID`, empty for the root scope. Scope IDs are opaque, so this is how a client walks a failure back up the process tree.
        miIndex:
          type: integer
          description: Zero-based multi-instance body index when the failure happened inside one iteration of a multi-instance activity. Absent otherwise.
        errorType:
          type: string
          description: Category of the error - same enum as `BpmnIncident.errorType`.
          enum:
            - BpmnError
            - EscalationError
            - CompensationError
            - FeelError
            - NoHandler
            - GatewayNoMatch
            - TimerResolution
            - LinkNotFound
            - MigrationError
            - SubscriptionError
            - RotationLimitError
            - SnapshotSizeExceeded
            - CallActivityCanceled
            - ExternalRowRefreshError
            - Unknown
        errorCode:
          type: string
          description: BPMN error code from the process definition; empty for non-BPMN errors.
        errorMessage:
          type: string
          description: Human-readable description of the error.
        raisedAt:
          type: string
          format: date-time
          description: Timestamp when the engine recorded the incident.
        resolvedAt:
          type: string
          format: date-time
          description: Timestamp when the incident was resolved. Empty while open.
        resolvedBy:
          type: string
          description: Identifier of the user who resolved the incident, or "system:reconcile" when corrected by drift reconciliation. Empty for engine-internal resolves (boundary catches, modification cancel) and for open incidents.
    BpmnIncidentRecordPaginatedResponse:
      type: object
      description: Page of persisted incidents.
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BpmnIncidentRecord'
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
    ElementMapping:
      type: object
      description: Maps a BPMN flow node from the source process version to the corresponding node in the target version during migration.
      required:
        - sourceElementID
        - targetElementID
      properties:
        sourceElementID:
          type: string
          description: BPMN element id in the running instance's current process version.
        targetElementID:
          type: string
          description: BPMN element id in the target process version.
    MigrateBpmnInstanceRequest:
      type: object
      description: Payload for migrating a running instance to a different version of its process.
      required:
        - targetVersion
      properties:
        targetVersion:
          type: integer
          description: Version of the same process to migrate to.
        elementMappings:
          type: array
          description: Mappings for elements that have been renamed between versions. Elements with the same id in source and target are matched implicitly.
          items:
            $ref: '#/components/schemas/ElementMapping'
        variables:
          type: object
          description: Variables to merge into the instance scope as part of the migration. Useful for filling in inputs introduced in the target version.
          additionalProperties: true
          x-go-type: VariableMap
    MigrationValidationResult:
      type: object
      description: Outcome of validating a migration plan without executing it.
      properties:
        valid:
          type: boolean
          description: True when the plan can be applied as-is.
        issues:
          type: array
          description: Human-readable descriptions of problems that would prevent migration.
          items:
            type: string
    ModificationInstruction:
      type: object
      description: A single token-level operation applied to a running instance during a modification.
      required:
        - type
        - nodeID
      properties:
        type:
          type: string
          description: |
            Kind of operation:
              * `START_BEFORE_NODE` - activate `nodeID` in the given scope, optionally seeding `variables` first.
              * `CANCEL_TOKEN` - cancel the active token at `nodeID` in the given scope.
          enum:
            - START_BEFORE_NODE
            - CANCEL_TOKEN
        nodeID:
          type: string
          description: BPMN flow node id the instruction targets.
        scopeID:
          type: string
          description: Scope to apply the instruction in. Empty applies to the root process scope.
        variables:
          type: object
          description: Variables to inject into the scope for `START_BEFORE_NODE`.
          additionalProperties: true
          x-go-type: VariableMap
    ModifyBpmnInstanceRequest:
      type: object
      description: Payload for an ad-hoc modification of a running instance. Instructions are applied in order.
      required:
        - instructions
      properties:
        instructions:
          type: array
          items:
            $ref: '#/components/schemas/ModificationInstruction'
    SuspendBpmnInstanceRequest:
      type: object
      description: Optional metadata captured with an instance-scope suspension.
      properties:
        reason:
          type: string
          description: Free-text rationale. Surfaces in the operator UI and the workflow's history audit.
    SuspendBpmnDefinitionRequest:
      type: object
      description: Optional metadata captured with a definition-scope suspension. The same reason cascades to each running instance.
      properties:
        reason:
          type: string
    ExternalJob:
      type: object
      description: A unit of work emitted by a BPMN service task that an external worker is expected to handle.
      required:
        - id
        - executionKey
        - workflowID
        - nodeID
        - taskType
        - status
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of this job record.
        executionKey:
          type: string
          description: Stable key for the activity execution that produced the job. Used as the path parameter when completing or failing the job.
        workflowID:
          type: string
          description: Identifier of the instance that produced the job. Required when calling Complete / ThrowError.
        nodeID:
          type: string
          description: ID of the BPMN service-task node.
        taskType:
          type: string
          description: Worker selector. Workers poll for jobs by `taskType`.
        variables:
          type: object
          description: Input variables resolved by the service task at activity entry.
          additionalProperties: true
          x-go-type: VariableMap
        parentWorkflowID:
          type: string
          description: Identifier of the parent instance (set when the producing instance was started by a CallActivity).
        status:
          type: string
          description: Lifecycle status of the job.
          enum:
            - PENDING
            - COMPLETED
            - CANCELED
            - FAILED
        retries:
          type: integer
          description: Remaining retry budget. Decremented each time the worker reports a failure that the BPMN model maps to a retry.
        headers:
          type: object
          description: Static metadata attached at design time on the service task. Available to workers but not merged back into the instance.
          additionalProperties:
            type: string
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the job was created.
        completedAt:
          type: string
          format: date-time
          description: Timestamp when the job reached a terminal status.
        lockedBy:
          type: string
          description: Worker `clientID` that currently holds the exclusive lock on the job.
        lockExpiresAt:
          type: string
          format: date-time
          description: Time at which the lock will be released if not extended via Heartbeat.
        cancelReason:
          type: string
          description: Best-effort label describing why a CANCELED job was interrupted (e.g. instance cancelled, instance terminated).
        businessId:
          type: string
          description: Caller-supplied correlation key inherited from the parent BPMN process. Workers can use it for log correlation or downstream tracing.
        traceContext:
          type: object
          additionalProperties:
            type: string
          description: W3C trace-propagation carrier (e.g. `traceparent`/`tracestate`) captured from the originating process instance. Present only when distributed tracing is enabled on the server. SDK workers pass this map to their OpenTelemetry propagator's extract so the worker span joins the instance's trace; plain workers can ignore it.
    BpmnExternalJobPaginatedResponse:
      type: object
      description: Page of external jobs.
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ExternalJob'
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
    ExternalJobQueueDepthItem:
      type: object
      description: PENDING job count for a single task type.
      required:
        - taskType
        - pendingCount
      properties:
        taskType:
          type: string
        pendingCount:
          type: integer
          format: int64
    ExternalJobQueueDepthResponse:
      type: object
      description: Per-task-type breakdown of pending external jobs.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ExternalJobQueueDepthItem'
    PollBpmnJobRequest:
      type: object
      description: Long-poll request for external jobs.
      required:
        - taskType
        - clientID
      properties:
        taskType:
          type: string
          description: Selector for the kind of work the worker handles.
        clientID:
          type: string
          description: Stable identifier for this worker. Used to attribute job locks and to count active workers.
        lockDuration:
          type: string
          description: Exclusive lock duration on each acquired job. Accepts Go duration strings (e.g. `5s`, `2m`). Defaults to `30s`.
        timeout:
          type: string
          description: How long to wait for a job before returning 204. Accepts Go duration strings. Defaults to `30s`.
        maxJobs:
          type: integer
          description: Maximum number of jobs to acquire in one call. Defaults to 1, capped at 100.
    ExternalJobBatchResponse:
      type: object
      description: Per-item result of a batch complete or batch error call.
      required:
        - results
      properties:
        results:
          type: array
          items:
            type: object
            required:
              - executionKey
              - status
            properties:
              executionKey:
                type: string
                description: The execution key of the item from the request.
              status:
                type: string
                description: |
                  Outcome for this item:
                    * `completed` - the job was completed successfully.
                    * `failed` - the job exhausted its retries and surfaced as an incident.
                    * `requeued` - a retry budget remained, the job is back in PENDING.
                    * `error` - the per-item operation itself failed; the job's state is unchanged.
                enum:
                  - completed
                  - failed
                  - requeued
                  - error
              error:
                type: string
                description: When `status` is `error`, a human-readable description of the failure.
    UserTask:
      type: object
      description: A human-handled work item produced by a BPMN user task or manual task.
      required:
        - id
        - executionKey
        - workflowID
        - nodeID
        - status
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of this user task record.
        executionKey:
          type: string
          description: Stable key for the activity execution. Used as the path parameter when completing or failing the task.
        workflowID:
          type: string
          description: Identifier of the instance that produced the task.
        parentWorkflowID:
          type: string
          description: Identifier of the parent instance (set when the producing instance was started by a CallActivity).
        nodeID:
          type: string
          description: ID of the BPMN node that emitted the task.
        taskType:
          type: string
          description: BPMN element type - typically `UserTask` or `ManualTask`.
        assignee:
          type: string
          description: User the task is currently assigned to. Empty when the task is in a candidate pool but not yet claimed.
        candidateUsers:
          type: array
          description: Users who may claim or complete this task even when no `assignee` is set.
          items:
            type: string
        candidateGroups:
          type: array
          description: Identity-provider groups whose members may claim or complete this task.
          items:
            type: string
        formKey:
          type: string
          description: Static form reference declared on the task (BPMN `formKey`). Resolved by the consumer to display the right UI.
        formID:
          type: string
          description: Resolved internal form identifier when `formKey` matches a stored form definition.
        variables:
          type: object
          description: Input variables resolved at activity entry. Available for rendering form defaults.
          additionalProperties: true
          x-go-type: VariableMap
        headers:
          type: object
          description: Static metadata attached at design time on the user task.
          additionalProperties:
            type: string
        status:
          type: string
          description: Lifecycle status of the task.
          enum:
            - CREATED
            - COMPLETED
            - CANCELED
            - FAILED
        cancelReason:
          type: string
          description: Best-effort label describing why a CANCELED task was interrupted (e.g. instance cancelled, boundary event interrupted).
        errorCode:
          type: string
          description: BPMN error code captured when the task was failed via ThrowError. Set only for FAILED tasks.
        completionVariables:
          type: object
          description: Variables submitted alongside the completion or error call. Set for COMPLETED and FAILED tasks.
          additionalProperties: true
          x-go-type: VariableMap
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the task was created.
        completedAt:
          type: string
          format: date-time
          description: Timestamp when the task reached a terminal status.
        businessId:
          type: string
          description: Caller-supplied correlation key inherited from the parent BPMN process.
    BpmnUserTaskPaginatedResponse:
      type: object
      description: Page of user tasks.
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/UserTask'
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
    UpdateUserTaskAssignmentRequest:
      type: object
      description: |
        Reassign a CREATED user task. All fields are optional but at least one
        must be present. Fields are REPLACED atomically - pass the full set of
        candidateUsers / candidateGroups you want stored, not a delta.
      properties:
        assignee:
          type: string
          nullable: true
          description: New assignee. Pass null to clear.
        candidateUsers:
          type: array
          items:
            type: string
        candidateGroups:
          type: array
          items:
            type: string
    CorrelationKeyString:
      type: string
      description: A scalar string correlation value.
    CorrelationKeyNumber:
      type: number
      description: A scalar numeric correlation value.
    CorrelationKeyBoolean:
      type: boolean
      description: A scalar boolean correlation value.
    CorrelationKeyMap:
      type: object
      description: A multi-key correlation value, used when the subscription's correlation expression resolves to a context.
      additionalProperties: true
    CorrelationKeys:
      description: |
        Selects which subscription(s) receive a published message.

        The provided value - primitive (string, number, boolean) or object -
        is matched against the subscription's resolved correlation value.
        Matching is type-sensitive (the number `123` does not match the
        string `"123"`); for objects, the publisher's keys must be a
        recursive subset of the subscription's stored keys.

        Empty / omitted broadcasts to subscriptions with no correlation
        requirement.
      oneOf:
        - $ref: '#/components/schemas/CorrelationKeyString'
        - $ref: '#/components/schemas/CorrelationKeyNumber'
        - $ref: '#/components/schemas/CorrelationKeyBoolean'
        - $ref: '#/components/schemas/CorrelationKeyMap'
    BpmnProcessSummary:
      type: object
      description: Aggregated counts for a process across all of its deployed versions.
      required:
        - processID
        - processName
        - versionCount
        - runningCount
        - totalCount
      properties:
        processID:
          type: string
          description: BPMN process id.
        processName:
          type: string
          description: Human-readable process name.
        versionCount:
          type: integer
          description: Number of deployed versions of this process.
        suspendedVersionCount:
          type: integer
          description: |
            How many versions of this process are paused. Zero means the process
            starts and dispatches normally; anything higher means at least one
            version rejects new instances. Filter the list with `suspended=true`
            to see only these.
        runningCount:
          type: integer
          description: Instances with status RUNNING across all versions.
        totalCount:
          type: integer
          description: All instances across all versions.
    BpmnProcessSummaryPaginatedResponse:
      type: object
      description: Page of process summaries.
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BpmnProcessSummary'
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
    BpmnProcessVersion:
      type: object
      description: One deployed version of a process, with instance counts.
      required:
        - id
        - resourceID
        - resourceName
        - processID
        - processName
        - version
        - createdAt
        - runningCount
        - totalCount
      properties:
        id:
          type: string
          format: uuid
          description: Platform identifier of this process definition version. Use it to filter instances or as the source/target of a migration.
        resourceID:
          type: string
          format: uuid
          description: Owning BPMN resource version.
        resourceName:
          type: string
          description: Display name of the owning resource.
        processID:
          type: string
          description: BPMN process id.
        processName:
          type: string
          description: Human-readable process name.
        version:
          type: integer
          description: Version number, starting at 1 for the first deploy.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this version was deployed.
        runningCount:
          type: integer
          description: Instances of this version with status RUNNING.
        totalCount:
          type: integer
          description: All instances of this version across statuses.
        suspendedAt:
          type: string
          format: date-time
          description: |
            Timestamp at which this definition was paused. While set, the start
            endpoint rejects new instances of this definition with 409, and every
            already-running instance was sent a definition-scope suspend signal.
            Empty when active.
        suspendedBy:
          type: string
          description: Operator who suspended this definition. Empty when active.
        suspendReason:
          type: string
          description: Free-text reason captured at suspend time.
    BpmnProcessVersionPaginatedResponse:
      type: object
      description: Page of process version entries.
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BpmnProcessVersion'
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'