openapi: 3.2.0
info:
  description: Workflow management API for B3OS
  title: B3OS Workflow Run API
  version: '1.0'
tags:
- name: Run
paths:
  /v1/runs/sync:
    post:
      description: 'Execute a workflow definition synchronously. Blocks until all nodes

        complete and returns the full execution state. Max 60s timeout, 20 nodes.'
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/SyncRunParams'
                summary: body
                description: Workflow definition to execute
        description: Workflow definition to execute
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncRunResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
          description: Bad Request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
          description: Payment Required
      tags:
      - Run
components:
  schemas:
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse:
      properties:
        code:
          type: integer
        details:
          items: {}
          type: array
          uniqueItems: false
        message:
          type: string
        requestId:
          type: string
      type: object
    SyncRunResponse:
      properties:
        durationMs:
          type: integer
        executionState:
          additionalProperties:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionNode'
          type: object
        runId:
          type: string
        status:
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.BlockOutputProperty:
      properties:
        description:
          type: string
        properties:
          additionalProperties:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.BlockOutputProperty'
          type: object
        type:
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.VariableLifetime:
      enum:
      - persist
      - reset
      type: string
      x-enum-varnames:
      - VariableLifetimePersist
      - VariableLifetimeReset
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.BlockExpansionMeta:
      properties:
        blockId:
          type: string
        blockVersion:
          type: integer
        entryNodeIds:
          description: Subset of ExpandedIDs that are entry points
          items:
            type: string
          type: array
          uniqueItems: false
        expandedIds:
          description: All namespaced node IDs produced by expansion
          items:
            type: string
          type: array
          uniqueItems: false
        outputSchema:
          description: Block's output schema for reference
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.BlockOutput'
          type: array
          uniqueItems: false
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.VariableType:
      enum:
      - number
      - text
      - boolean
      - list
      - object
      type: string
      x-enum-varnames:
      - VariableTypeNumber
      - VariableTypeText
      - VariableTypeBoolean
      - VariableTypeList
      - VariableTypeObject
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.BlockOutput:
      properties:
        description:
          description: Human-readable description for the variable picker
          type: string
        key:
          description: Output field name exposed to consumers
          type: string
        properties:
          additionalProperties:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.BlockOutputProperty'
          description: Nested schema for object/array outputs (shown in variable picker)
          type: object
        sourceField:
          description: Field path from the source node's result (e.g., "balance")
          type: string
        sourceNode:
          description: Node ID within the block definition
          type: string
        type:
          description: '"string", "number", "boolean", "object", "array"'
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionNode:
      properties:
        connector:
          additionalProperties: {}
          description: Safe connector metadata (e.g., wallet address)
          type: object
        context:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionContext'
        finishedAt:
          type: string
        input:
          additionalProperties: {}
          description: Input payload at time of completion/failure (may be raw or resolved)
          type: object
        iterations:
          description: 'For for-each nodes only: tracks execution state of each iteration.

            Each iteration is a mini ExecutionState graph (nodeID → ExecutionNode).'
          items:
            additionalProperties:
              $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionNode'
            type: object
          type: array
          uniqueItems: false
        result:
          additionalProperties: {}
          description: Output from execution
          type: object
        secretKeys:
          description: Input keys that contain connector secrets (for masking)
          items:
            type: string
          type: array
          uniqueItems: false
        startedAt:
          type: string
        status:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionNodeStatus'
        type:
          description: Node type (e.g., "webhook", "send-erc20-token")
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.VariableDef:
      properties:
        default: {}
        description:
          type: string
        lifetime:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.VariableLifetime'
        name:
          type: string
        type:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.VariableType'
      type: object
    SyncRunParams:
      properties:
        definition:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowDefinition'
        payload:
          additionalProperties: {}
          type: object
        propValues:
          additionalProperties: {}
          type: object
      required:
      - definition
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowDefinition:
      description: 'Definition is the inline workflow graph to analyze. Same shape as a

        saved workflow''s definition. Unlike the ephemeral-run endpoint there

        is no trigger restriction — analysis is read-only and method-agnostic.'
      properties:
        blockExpansions:
          additionalProperties:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.BlockExpansionMeta'
          description: Set on run snapshots only (not workflow DB)
          type: object
        inputSchema:
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowInput'
          type: array
          uniqueItems: false
        nodes:
          additionalProperties:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowNode'
          type: object
        sensitivePropKeys:
          description: 'Legacy: kept for old runs; no longer populated for new workflows'
          items:
            type: string
          type: array
          uniqueItems: false
        triggerNodeIds:
          description: 'TriggerNodeIDs lists the node IDs that are trigger (root) nodes. Every

            workflow declares this — single-trigger workflows ship ["root"] (the

            legacy node id), multi-trigger workflows list every trigger node id.

            Treating single-trigger as a forest-of-1 removes the two-path branching

            throughout the BE + FE; older rows without the field are backfilled by

            migration 000282 and the field-missing path stays as a read-side safety

            net (see FindTriggerNodeIDs) but is no longer exercised by saves.


            "root" is also a runtime alias for "the trigger that fired this run" —

            {{root.X}} variable references resolve to the firing trigger regardless

            of which trigger fired. Don''t repurpose the literal "root" as a trigger

            id on a multi-trigger workflow.'
          items:
            type: string
          type: array
          uniqueItems: false
        variableDefs:
          description: 'VariableDefs is a snapshot of the workflow''s declared variables at run

            creation time. The canonical source lives on the workflows row

            (Workflow.VariableDefs column). Snapshotted into the run definition

            so the worker can resolve {{$vars.x}} lookups and route variable-action

            writes to the right scope without an extra DB round trip.'
          items:
            $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.VariableDef'
          type: array
          uniqueItems: false
      required:
      - nodes
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.BlockNodeContext:
      description: 'BlockContext is set on nodes that were expanded from a block.

        It traces the node back to its source block and carries the inputMapping

        needed to resolve {{$inputs.key}} references at execution time.'
      properties:
        blockId:
          description: Block entity ID
          type: string
        blockNodeId:
          description: Original block node ID in the workflow
          type: string
        blockVersion:
          description: Pinned block version
          type: integer
        inputMapping:
          additionalProperties: {}
          description: From block node payload (consumer-authored)
          type: object
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowInput:
      properties:
        description:
          type: string
        key:
          type: string
        required:
          type: boolean
        type:
          description: '"string", "number", "boolean", "object", "array"'
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionContext:
      properties:
        chainContext:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ChainContext'
        inputs:
          additionalProperties: {}
          description: Block input values ({{$inputs.key}})
          type: object
        loopVars:
          additionalProperties: {}
          description: Loop variables (for for-each nodes)
          type: object
        props:
          additionalProperties: {}
          description: Template prop values snapshot
          type: object
        workflowId:
          description: Current workflow ID ({{$workflowId}})
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ChainContext:
      properties:
        blockchain:
          description: '"evm" or "solana"'
          type: string
        networkId:
          description: '"1", "8453", "7565164", etc.'
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ConnectorReference:
      description: nil if action doesn't need connector
      properties:
        chainId:
          type: integer
        id:
          type: string
        type:
          type: string
        walletAddress:
          description: 'WalletAddress is the wallet''s on-chain address, only meaningful for

            type:"wallet" refs. Not used by ConnectorResolver (which resolves the

            address from the wallet DB record); exists for frontend round-trip fidelity.'
          type: string
      type: object
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionNodeStatus:
      enum:
      - pending
      - running
      - success
      - partial
      - failure
      - skipped
      - waiting
      - scheduled
      - cancelled
      - auto_swapping
      type: string
      x-enum-comments:
        ExecutionNodeStatusAutoSwapping: Set when auto-swap is executing to cover a balance deficit
        ExecutionNodeStatusCancelled: Set when run is cancelled by user
        ExecutionNodeStatusFailure: Set when node execution fails
        ExecutionNodeStatusPartial: Set when a for-each node completes with mixed iteration outcomes (some succeeded, some failed)
        ExecutionNodeStatusPending: Set when run is created (all non-root nodes start as pending)
        ExecutionNodeStatusRunning: Set when node execution begins
        ExecutionNodeStatusScheduled: Set when node is scheduled for future execution
        ExecutionNodeStatusSkipped: Set when node is skipped (e.g., non-taken if branch)
        ExecutionNodeStatusSuccess: Set when node execution completes successfully
        ExecutionNodeStatusWaiting: Set when node is paused waiting for a trigger
      x-enum-varnames:
      - ExecutionNodeStatusPending
      - ExecutionNodeStatusRunning
      - ExecutionNodeStatusSuccess
      - ExecutionNodeStatusPartial
      - ExecutionNodeStatusFailure
      - ExecutionNodeStatusSkipped
      - ExecutionNodeStatusWaiting
      - ExecutionNodeStatusScheduled
      - ExecutionNodeStatusCancelled
      - ExecutionNodeStatusAutoSwapping
    github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowNode:
      properties:
        blockContext:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.BlockNodeContext'
        branch:
          description: '"then"/"else" (if parent), "resumed"/"timed_out" (wait parent)'
          type: string
        children:
          items:
            type: string
          type: array
          uniqueItems: false
        connector:
          $ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ConnectorReference'
        description:
          description: AI-generated 1-sentence description
          type: string
        loopBody:
          description: Loop body nodes (only for for-each nodes)
          items:
            type: string
          type: array
          uniqueItems: false
        payload:
          additionalProperties: {}
          type: object
        resultSchema:
          additionalProperties: {}
          description: 'ResultSchema describes the output structure of this node (populated dynamically for x402 endpoints).

            This is used by the frontend to show available output variables in the variable picker.'
          type: object
        titleOverride:
          description: AI-generated short title (2-6 words), only when more descriptive than default
          type: string
        type:
          type: string
      required:
      - payload
      - type
      type: object