openapi: 3.0.3
info:
  title: ArtificialFlow HTTP API
  version: 1.2.0
  description: |
    Supported versioned HTTP contract for ArtificialFlow command, query, worker,
    and user-task integrations. The gateway `/api/v1` URL is the
    recommended public base. Unversioned `/api` compatibility routes preserve
    their existing 1.x response and plain-text error contracts.
    Query operations under `/query` are eventually consistent.
    Authorization uses four roles from the access token:
    `artificialflowadmin` (everything), `artificialflowbusiness` (workflow and
    decision modeling), `artificialflowclient` (SDK/API runtime operations and
    user tasks) and `artificialflowanalytics` (reserved, no API access yet).
    Client applications authenticate their own end users and pass them as
    task filters or as `assignee`; ArtificialFlow does not validate end-user
    tokens.
    Authentication follows the deployment's boolean `IAM_DEPLOYMENT_MODE`:
    with `true` every operation except health and `/identity/login` needs a
    Bearer token from the external OIDC provider; with `false` (no IAM
    provider) no token is needed and every call runs as `artificialflowadmin`.
  license:
    name: MIT
    url: https://opensource.org/license/mit
  contact:
    name: ArtificialFlow
    url: https://github.com/artificialflow/artificialflow
servers:
  - url: http://localhost:9100/api/v1
    description: Local versioned gateway (recommended)
  - url: https://app.example.com/api/v1
    description: Production versioned gateway example
tags:
  - name: Identity
    description: Principal inspection and deployment IAM metadata
  - name: Workflows
    description: BPMN process-definition deployment and management
  - name: Decisions
    description: JSON decision-table deployment and evaluation
  - name: Instances
    description: Authoritative workflow-instance commands and reads
  - name: Events
    description: BPMN message, signal, and escalation publication
  - name: Jobs
    description: External worker activation, locking, completion, and failure
  - name: Tasks
    description: User-task search, claim and completion on behalf of a client application's end users
  - name: Query
    description: Eventually consistent projected search operations
  - name: Operations
    description: Health, incidents, retries, and engine counters
security:
  - bearerAuth: []
paths:
  /health:
    get:
      tags: [Operations]
      summary: Check command service health
      operationId: commandHealth
      security: []
      responses:
        "200":
          description: Healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
  /identity/me:
    get:
      tags: [Identity]
      summary: Inspect the authenticated principal
      operationId: getIdentity
      responses:
        "200":
          description: Authentication state and principal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /identity/config:
    get:
      tags: [Identity]
      summary: Read non-secret IAM deployment configuration
      operationId: getIdentityConfig
      responses:
        "200":
          description: IAM mode, issuers, claim paths, and standard roles
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  deployment_mode:
                    type: boolean
                    description: >-
                      IAM_DEPLOYMENT_MODE. true: an external OIDC provider
                      authenticates console users and SDK clients. false: no
                      IAM provider; local console sign-in and no API token.
        "401":
          $ref: "#/components/responses/Unauthorized"
  /identity/login:
    post:
      tags: [Identity]
      summary: Console sign-in when no IAM provider is used
      description: >-
        Checks the console admin credentials (CONSOLE_ADMIN_USERNAME /
        CONSOLE_ADMIN_PASSWORD, default admin/admin) when
        IAM_DEPLOYMENT_MODE=false. No token is issued: in that mode the API
        is unauthenticated. With IAM_DEPLOYMENT_MODE=true the endpoint is
        unavailable: the token check rejects the call (401), or 404 if a valid
        token is sent.
      operationId: consoleLogin
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [username, password]
              properties:
                username: {type: string}
                password: {type: string}
      responses:
        "200":
          description: Credentials accepted
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "400":
          description: Malformed request body
        "401":
          description: Invalid username or password, or IAM is external and no token was sent
        "404":
          description: IAM is external; sign in through the OIDC provider
  /workflows:
    get:
      tags: [Workflows]
      summary: List authoritative workflow definitions
      operationId: listWorkflows
      responses:
        "200":
          description: Workflow definitions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WorkflowDefinition"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      tags: [Workflows]
      summary: Deploy a BPMN 2.0 workflow
      operationId: deployWorkflow
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: string
              format: binary
          text/xml:
            schema:
              type: string
              format: binary
      responses:
        "200":
          description: Deployed definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowDefinition"
        "400":
          $ref: "#/components/responses/BadRequest"
        "413":
          description: BPMN exceeds the 20 MiB request limit
  /workflows/{id}:
    parameters:
      - $ref: "#/components/parameters/WorkflowId"
    get:
      tags: [Workflows]
      summary: Get a workflow definition by key or BPMN process id
      operationId: getWorkflow
      responses:
        "200":
          description: Workflow definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowDefinition"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      tags: [Workflows]
      summary: Delete a workflow definition
      operationId: deleteWorkflow
      responses:
        "204":
          description: Deleted
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /decisions:
    get:
      tags: [Decisions]
      summary: List deployed decisions
      operationId: listDecisions
      responses:
        "200":
          description: Decisions
          content:
            application/json:
              schema:
                type: object
                properties:
                  decisions:
                    type: array
                    items:
                      $ref: "#/components/schemas/Decision"
    post:
      tags: [Decisions]
      summary: Deploy a JSON decision table
      operationId: deployDecision
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeployDecisionRequest"
      responses:
        "200":
          description: Deployed decision
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Decision"
        "400":
          $ref: "#/components/responses/BadRequest"
  /decisions/{id}/evaluate:
    post:
      tags: [Decisions]
      summary: Evaluate the latest version of a decision
      operationId: evaluateDecision
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [inputs]
              properties:
                inputs:
                  type: object
                  additionalProperties: true
      responses:
        "200":
          description: Decision outputs
          content:
            application/json:
              schema:
                type: object
                properties:
                  outputs:
                    type: object
                    additionalProperties: true
        "404":
          $ref: "#/components/responses/NotFound"
  /instances:
    get:
      tags: [Instances]
      summary: List active instances from the command store
      operationId: listInstances
      responses:
        "200":
          description: Active instances
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WorkflowInstance"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      tags: [Instances]
      summary: Start a workflow instance
      operationId: startInstance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartInstanceRequest"
      responses:
        "200":
          description: Started instance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowInstance"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
  /instances/history/completed:
    get:
      tags: [Instances]
      summary: List completed instance history
      operationId: listCompletedInstances
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Completed instances
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WorkflowInstance"
  /instances/{id}:
    parameters:
      - $ref: "#/components/parameters/InstanceId"
    get:
      tags: [Instances]
      summary: Get authoritative instance details
      operationId: getInstance
      responses:
        "200":
          description: Instance, executions, and task metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowInstance"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      tags: [Instances]
      summary: Cancel and delete an instance
      operationId: deleteInstance
      responses:
        "204":
          description: Deleted
        "403":
          $ref: "#/components/responses/Forbidden"
  /instances/{id}/variables:
    post:
      tags: [Instances]
      summary: Merge variables into an instance
      operationId: updateInstanceVariables
      parameters:
        - $ref: "#/components/parameters/InstanceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [variables]
              properties:
                variables:
                  type: object
                  additionalProperties: true
      responses:
        "200":
          description: Updated instance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowInstance"
  /instances/{id}/migration/dry-run:
    post:
      tags: [Instances]
      summary: Validate a bounded process-instance migration
      operationId: dryRunInstanceMigration
      parameters:
        - $ref: "#/components/parameters/InstanceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InstanceMigrationRequest"
      responses:
        "200":
          description: Migration is supported and mapping is complete
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InstanceMigrationResult"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          description: Migration rejected with a stable reason code
  /instances/{id}/migration:
    post:
      tags: [Instances]
      summary: Atomically apply a validated bounded process-instance migration
      operationId: migrateInstance
      parameters:
        - $ref: "#/components/parameters/InstanceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InstanceMigrationRequest"
      responses:
        "200":
          description: Migration applied
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InstanceMigrationResult"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          description: Migration rejected with a stable reason code
  /instances/{id}/complete:
    post:
      tags: [Instances]
      summary: Complete an instance step by BPMN step id
      operationId: completeInstanceStep
      parameters:
        - $ref: "#/components/parameters/InstanceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [step_id]
              properties:
                step_id:
                  type: string
      responses:
        "200":
          description: Step completed
        "400":
          $ref: "#/components/responses/BadRequest"
  /instances/{id}/tasks:
    get:
      tags: [Tasks]
      summary: List user tasks for an instance
      operationId: listInstanceTasks
      parameters:
        - $ref: "#/components/parameters/InstanceId"
        - $ref: "#/components/parameters/IncludeCompleted"
      responses:
        "200":
          description: User tasks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserTaskList"
  /instances/{id}/tasks/{executionId}/claim:
    post:
      tags: [Tasks]
      summary: Claim a user task for an end user
      description: |
        Clients must name the end user in `assignee`. Admins default to their
        own identity and may reassign a task claimed by someone else.
      operationId: claimUserTask
      parameters:
        - $ref: "#/components/parameters/InstanceId"
        - $ref: "#/components/parameters/ExecutionId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserTaskAction"
      responses:
        "200":
          description: Claimed task
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserTask"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /instances/{id}/tasks/{executionId}/complete:
    post:
      tags: [Tasks]
      summary: Complete a user task for the end user who claimed it
      description: |
        `assignee` must match the claim owner. Admins may complete any task.
      operationId: completeUserTask
      parameters:
        - $ref: "#/components/parameters/InstanceId"
        - $ref: "#/components/parameters/ExecutionId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserTaskAction"
      responses:
        "200":
          description: Task completed
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /tasks:
    get:
      tags: [Tasks]
      summary: Search user tasks
      description: |
        Returns user tasks for a client application's end user. `assignee`,
        `candidateUser` and `candidateGroup` are OR-combined; with none of
        them every task in the selected state is returned.
      operationId: searchTasks
      parameters:
        - name: assignee
          in: query
          description: Tasks assigned to or claimed by this user
          schema:
            type: string
        - name: candidateUser
          in: query
          description: Tasks this user may act on (assignee, claim owner or candidate user)
          schema:
            type: string
        - name: candidateGroup
          in: query
          description: Tasks offered to any of these groups. Repeat or comma-separate.
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: includeUnassigned
          in: query
          description: Also return open tasks without assignee, candidates or claim
          schema:
            type: boolean
            default: false
        - name: processInstanceKey
          in: query
          schema:
            type: string
        - name: state
          in: query
          schema:
            type: string
            enum: [active, completed, all]
            default: active
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
      responses:
        "200":
          description: Matching user tasks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserTaskList"
        "400":
          $ref: "#/components/responses/BadRequest"
  /instances/{id}/jobs:
    get:
      tags: [Jobs]
      summary: List jobs belonging to an instance
      operationId: listInstanceJobs
      parameters:
        - $ref: "#/components/parameters/InstanceId"
      responses:
        "200":
          description: Jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Job"
  /signals:
    post:
      tags: [Events]
      summary: Publish a BPMN signal
      operationId: publishSignal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignalRequest"
      responses:
        "200":
          description: Published
  /messages:
    post:
      tags: [Events]
      summary: Correlate and publish a BPMN message
      operationId: publishMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MessageRequest"
      responses:
        "200":
          description: Published
  /escalations:
    post:
      tags: [Events]
      summary: Publish a BPMN escalation
      operationId: publishEscalation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EscalationRequest"
      responses:
        "200":
          description: Published
  /jobs/capabilities:
    get:
      tags: [Jobs]
      summary: Read worker protocol capabilities
      operationId: getJobCapabilities
      parameters:
        - $ref: "#/components/parameters/WorkerProtocol"
      responses:
        "200":
          description: Supported protocol and operations
          headers:
            X-Workflow-Engine-Protocol-Version:
              schema:
                type: string
                example: v1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobCapabilities"
  /jobs/activate:
    post:
      tags: [Jobs]
      summary: Activate and lock available jobs
      operationId: activateJobs
      parameters:
        - $ref: "#/components/parameters/WorkerProtocol"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActivateJobsRequest"
      responses:
        "200":
          description: Activated jobs
          content:
            application/json:
              schema:
                type: object
                required: [jobs]
                properties:
                  jobs:
                    type: array
                    items:
                      $ref: "#/components/schemas/Job"
  /jobs/{key}/complete:
    post:
      tags: [Jobs]
      summary: Complete an activated job
      operationId: completeJob
      parameters:
        - $ref: "#/components/parameters/JobKey"
        - $ref: "#/components/parameters/WorkerProtocol"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CompleteJobRequest"
      responses:
        "200":
          description: Completed or safely replayed
        "409":
          $ref: "#/components/responses/Conflict"
  /jobs/{key}/fail:
    post:
      tags: [Jobs]
      summary: Fail an activated job
      operationId: failJob
      parameters:
        - $ref: "#/components/parameters/JobKey"
        - $ref: "#/components/parameters/WorkerProtocol"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FailJobRequest"
      responses:
        "200":
          description: Failed or safely replayed
  /jobs/{key}/extend-lock:
    post:
      tags: [Jobs]
      summary: Extend an activated job lock
      operationId: extendJobLock
      parameters:
        - $ref: "#/components/parameters/JobKey"
        - $ref: "#/components/parameters/WorkerProtocol"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExtendJobLockRequest"
      responses:
        "200":
          description: Lock extended or safely replayed
  /jobs/{key}/retry:
    post:
      tags: [Jobs]
      summary: Administratively retry a failed job
      operationId: retryJob
      parameters:
        - $ref: "#/components/parameters/JobKey"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                retries:
                  type: integer
                  minimum: 0
      responses:
        "200":
          description: Job scheduled for retry
  /incidents:
    get:
      tags: [Operations]
      summary: List incidents
      operationId: listIncidents
      parameters:
        - name: processInstanceKey
          in: query
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Incidents
          content:
            application/json:
              schema:
                type: object
                required: [incidents]
                properties:
                  incidents:
                    type: array
                    items:
                      $ref: "#/components/schemas/Incident"
  /incidents/{key}/resolve:
    post:
      tags: [Operations]
      summary: Resolve an incident
      operationId: resolveIncident
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
            pattern: '^[0-9]+$'
      responses:
        "200":
          description: Resolved incident
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /internal/metrics:
    get:
      tags: [Operations]
      summary: Read engine operational counters
      description: >-
        Admin only. Private service-to-service endpoint: the public gateway
        answers 404, so call the command service directly from inside the
        cluster or Compose network.
      operationId: getEngineMetrics
      responses:
        "200":
          description: Outbox and idempotency metrics
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /query/health:
    get:
      tags: [Query]
      summary: Check query service health
      operationId: queryHealth
      security: []
      responses:
        "200":
          description: Healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
  /query/identity/me:
    get:
      tags: [Query, Identity]
      summary: Inspect the query-service principal
      operationId: getQueryIdentity
      responses:
        "200":
          description: Authentication state and principal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityResponse"
  /query/instances:
    get:
      tags: [Query]
      summary: Search projected workflow instances
      description: Results are eventually consistent with command writes.
      operationId: searchInstances
      parameters:
        - name: workflowId
          in: query
          schema:
            type: string
          description: Numeric process-definition key
        - name: state
          in: query
          schema:
            type: string
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          description: Projected instances
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectedInstancePage"
  /query/instances/{id}:
    get:
      tags: [Query]
      summary: Get a projected instance
      operationId: getProjectedInstance
      parameters:
        - $ref: "#/components/parameters/InstanceId"
      responses:
        "200":
          description: Projected instance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowInstance"
        "404":
          $ref: "#/components/responses/NotFound"
  /query/workflows:
    get:
      tags: [Query]
      summary: Search projected workflow definitions
      operationId: searchWorkflows
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          description: Projected workflows
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectedWorkflowPage"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token from the external OIDC provider (IAM_DEPLOYMENT_MODE=true).
        Not required and ignored when IAM_DEPLOYMENT_MODE=false.
  parameters:
    WorkflowId:
      name: id
      in: path
      required: true
      description: Numeric definition key or BPMN process id
      schema:
        type: string
    InstanceId:
      name: id
      in: path
      required: true
      schema:
        type: string
    ExecutionId:
      name: executionId
      in: path
      required: true
      schema:
        type: string
    JobKey:
      name: key
      in: path
      required: true
      schema:
        type: string
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: string
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 100
        minimum: 1
    Page:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1
    PageSize:
      name: pageSize
      in: query
      schema:
        type: integer
        default: 20
        minimum: 1
    IncludeCompleted:
      name: includeCompleted
      in: query
      schema:
        type: boolean
        default: false
    WorkerProtocol:
      name: X-Workflow-Worker-Protocol-Version
      in: header
      required: true
      schema:
        type: string
        enum: [v1]
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        maxLength: 128
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Unauthorized:
      description: Missing, invalid, or expired access token
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Forbidden:
      description: Principal does not have the required role
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    NotFound:
      description: Resource not found
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Conflict:
      description: Resource state or ownership conflict
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
  schemas:
    Problem:
      type: object
      required: [type, title, status, correlationId]
      properties:
        type:
          type: string
          format: uri-reference
          example: about:blank
        title:
          type: string
        status:
          type: integer
          minimum: 400
          maximum: 599
        detail:
          type: string
        instance:
          type: string
          format: uri-reference
        correlationId:
          type: string
    Health:
      type: object
      required: [status]
      properties:
        status:
          type: string
          example: ok
    Principal:
      type: object
      properties:
        subject:
          type: string
        roles:
          type: array
          items:
            type: string
        email:
          type: string
          format: email
        name:
          type: string
    IdentityResponse:
      type: object
      required: [authenticated]
      properties:
        authenticated:
          type: boolean
        principal:
          $ref: "#/components/schemas/Principal"
    WorkflowDefinition:
      type: object
      properties:
        id:
          type: string
        process_definition_id:
          type: string
        name:
          type: string
        version:
          type: integer
        resource_name:
          type: string
        deployment_id:
          type: string
        tenant_id:
          type: string
        resource_checksum:
          type: string
        bpmn_xml:
          type: string
        created_at:
          type: string
          format: date-time
        steps:
          type: array
          items:
            type: object
            additionalProperties: true
    WorkflowInstance:
      type: object
      properties:
        id:
          type: string
        workflow_id:
          type: string
        status:
          type: string
        context:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        executions:
          type: array
          items:
            type: object
            additionalProperties: true
    StartInstanceRequest:
      type: object
      required: [workflow_id]
      properties:
        workflow_id:
          type: string
          description: Numeric definition key or BPMN process id
        version:
          type: integer
          minimum: 1
        context:
          type: object
          additionalProperties: true
    InstanceMigrationRequest:
      type: object
      required: [sourceDefinitionKey, targetDefinitionKey, elementMapping]
      properties:
        sourceDefinitionKey:
          type: string
        targetDefinitionKey:
          type: string
        elementMapping:
          type: object
          additionalProperties:
            type: string
        operationId:
          type: string
    InstanceMigrationResult:
      type: object
      required: [operationId, instanceKey, dryRun, status]
      properties:
        operationId:
          type: string
        instanceKey:
          type: string
        dryRun:
          type: boolean
        status:
          type: string
          enum: [VALIDATED, APPLIED, REJECTED]
        reasonCode:
          type: string
        message:
          type: string
        sourceVersion:
          type: integer
        targetVersion:
          type: integer
    Decision:
      type: object
      properties:
        key:
          type: string
        decision_id:
          type: string
        name:
          type: string
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DeployDecisionRequest:
      type: object
      required: [decision_id, resource]
      properties:
        decision_id:
          type: string
        name:
          type: string
        resource:
          type: string
          description: JSON decision table encoded as a string
    SignalRequest:
      type: object
      required: [signal_name]
      properties:
        signal_name:
          type: string
        payload:
          type: object
          additionalProperties: true
    MessageRequest:
      type: object
      required: [message_name]
      properties:
        message_name:
          type: string
        correlation_key:
          type: string
        payload:
          type: object
          additionalProperties: true
    EscalationRequest:
      type: object
      required: [escalation_code]
      properties:
        escalation_code:
          type: string
        payload:
          type: object
          additionalProperties: true
    JobCapabilities:
      type: object
      required: [protocolVersion, capabilities]
      properties:
        protocolVersion:
          type: string
          example: v1
        capabilities:
          type: array
          items:
            type: string
          example: [activate, complete, fail, extend-lock]
    ActivateJobsRequest:
      type: object
      required: [type, worker]
      properties:
        type:
          type: string
        worker:
          type: string
        maxJobs:
          type: integer
          minimum: 1
        timeoutMs:
          type: integer
          minimum: 0
        lockDurationMs:
          type: integer
          minimum: 1
    Job:
      type: object
      properties:
        key:
          type: string
        type:
          type: string
        processInstanceKey:
          type: string
        elementInstanceKey:
          type: string
        processDefinitionKey:
          type: string
        elementId:
          type: string
        worker:
          type: string
        retries:
          type: integer
        state:
          type: string
        lockExpirationTime:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CompleteJobRequest:
      type: object
      required: [worker]
      properties:
        worker:
          type: string
        variables:
          type: object
          additionalProperties: true
    FailJobRequest:
      type: object
      required: [worker, errorMessage]
      properties:
        worker:
          type: string
        errorMessage:
          type: string
        retries:
          type: integer
          minimum: 0
    ExtendJobLockRequest:
      type: object
      required: [worker, lockDurationMs]
      properties:
        worker:
          type: string
        lockDurationMs:
          type: integer
          minimum: 1
    UserTask:
      type: object
      properties:
        key:
          type: string
        processInstanceKey:
          type: string
        processDefinitionKey:
          type: string
        elementId:
          type: string
        executionId:
          type: string
        state:
          type: string
        assignee:
          type: string
        candidateUsers:
          type: array
          items:
            type: string
        candidateGroups:
          type: array
          items:
            type: string
        claimedBy:
          type: string
        canClaim:
          type: boolean
          description: Task is open and unclaimed
        canComplete:
          type: boolean
          description: Task is open and claimed
        dueDate:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    UserTaskAction:
      type: object
      additionalProperties: false
      properties:
        assignee:
          type: string
          description: End user acting on the task. Required for client tokens.
    UserTaskList:
      type: object
      required: [tasks]
      properties:
        tasks:
          type: array
          items:
            $ref: "#/components/schemas/UserTask"
    Incident:
      type: object
      properties:
        key:
          type: string
        id:
          type: string
        processInstanceKey:
          type: string
        elementInstanceKey:
          type: string
        jobKey:
          type: string
        errorType:
          type: string
        errorMessage:
          type: string
        state:
          type: string
        createdAt:
          type: string
          format: date-time
        resolvedAt:
          type: string
          format: date-time
          nullable: true
    ProjectedInstancePage:
      type: object
      required: [instances, total]
      properties:
        instances:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowInstance"
        total:
          type: integer
          format: int64
    ProjectedWorkflowPage:
      type: object
      required: [workflows, total]
      properties:
        workflows:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowDefinition"
        total:
          type: integer
          format: int64
