openflow.openapi.yaml

openapi: '3.0.3'

info:
  version: 1.624.0
  title: OpenFlow Spec
  contact:
    name: Ruben Fiszel
    email: ruben@windmill.dev
    url: https://windmill.dev

  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

paths: {}

externalDocs:
  description: documentation portal
  url: https://windmill.dev

components:
  schemas:
    OpenFlow:
      type: object
      description: Top-level flow definition containing metadata, configuration, and the flow structure
      properties:
        summary:
          type: string
          description: Short description of what this flow does
        description:
          type: string
          description: Detailed documentation for this flow
        value:
          $ref: '#/components/schemas/FlowValue'
        schema:
          type: object
          description: JSON Schema for flow inputs. Use this to define input parameters, their types, defaults, and validation. For resource inputs, set type to 'object' and format to 'resource-<type>' (e.g., 'resource-stripe')
      required:
        - summary
        - value

    FlowValue:
      type: object
      description: The flow structure containing modules and optional preprocessor/failure handlers
      properties:
        modules:
          type: array
          description: Array of steps that execute in sequence. Each step can be a script, subflow, loop, or branch
          items:
            $ref: '#/components/schemas/FlowModule'
        failure_module:
          description: Special module that executes when the flow fails. Receives error object with message, name, stack, and step_id. Must have id 'failure'. Only supports script/rawscript types
          $ref: '#/components/schemas/FlowModule'
        preprocessor_module:
          description: Special module that runs before the first step on external triggers. Must have id 'preprocessor'. Only supports script/rawscript types. Cannot reference other step results
          $ref: '#/components/schemas/FlowModule'
        same_worker:
          type: boolean
          description: If true, all steps run on the same worker for better performance
        concurrent_limit:
          type: number
          description: Maximum number of concurrent executions of this flow
        concurrency_key:
          type: string
          description: Expression to group concurrent executions (e.g., by user ID)
        concurrency_time_window_s:
          type: number
          description: Time window in seconds for concurrent_limit
        debounce_delay_s:
          type: number
          description: Delay in seconds to debounce flow executions
        debounce_key:
          type: string
          description: Expression to group debounced executions
        debounce_args_to_accumulate:
          type: array
          description: Arguments to accumulate across debounced executions
          items:
            type: string
        max_total_debouncing_time:
          type: number
          description: Maximum total time in seconds that a job can be debounced
        max_total_debounces_amount:
          type: number
          description: Maximum number of times a job can be debounced
        skip_expr:
          type: string
          description: JavaScript expression to conditionally skip the entire flow
        cache_ttl:
          type: number
          description: Cache duration in seconds for flow results
        cache_ignore_s3_path:
          type: boolean
        flow_env:
          type: object
          description: Environment variables available to all steps
          additionalProperties:
            type: string
        priority:
          type: number
          description: Execution priority (higher numbers run first)
        early_return:
          type: string
          description: JavaScript expression to return early from the flow
        chat_input_enabled:
          type: boolean
          description: Whether this flow accepts chat-style input
        notes:
          type: array
          description: Sticky notes attached to the flow
          items:
            $ref: '#/components/schemas/FlowNote'
      required:
        - modules

    Retry:
      type: object
      description: Retry configuration for failed module executions
      properties:
        constant:
          type: object
          description: Retry with constant delay between attempts
          properties:
            attempts:
              type: integer
              description: Number of retry attempts
            seconds:
              type: integer
              description: Seconds to wait between retries
        exponential:
          type: object
          description: Retry with exponential backoff (delay doubles each time)
          properties:
            attempts:
              type: integer
              description: Number of retry attempts
            multiplier:
              type: integer
              description: Multiplier for exponential backoff
            seconds:
              type: integer
              minimum: 1
              description: Initial delay in seconds
            random_factor:
              type: integer
              minimum: 0
              maximum: 100
              description: Random jitter percentage (0-100) to avoid thundering herd
        retry_if:
          $ref: '#/components/schemas/RetryIf'

    FlowNote:
      type: object
      description: A sticky note attached to a flow for documentation and annotation
      properties:
        id:
          type: string
          description: Unique identifier for the note
        text:
          type: string
          description: Content of the note
        position:
          type: object
          description: Position of the note in the flow editor
          properties:
            x:
              type: number
              description: X coordinate
            y:
              type: number
              description: Y coordinate
          required:
            - x
            - y
        size:
          type: object
          description: Size of the note in the flow editor
          properties:
            width:
              type: number
              description: Width in pixels
            height:
              type: number
              description: Height in pixels
          required:
            - width
            - height
        color:
          type: string
          description: Color of the note (e.g., "yellow", "#ffff00")
        type:
          type: string
          enum: [free, group]
          description: Type of note - 'free' for standalone notes, 'group' for notes that group other nodes
        locked:
          type: boolean
          default: false
          description: Whether the note is locked and cannot be edited or moved
        contained_node_ids:
          type: array
          items:
            type: string
          description: For group notes, the IDs of nodes contained within this group
      required:
        - id
        - text
        - color
        - type

    RetryIf:
      type: object
      description: Conditional retry based on error or result
      properties:
        expr:
          type: string
          description: JavaScript expression that returns true to retry. Has access to 'result' and 'error' variables
      required:
        - expr

    StopAfterIf:
      type: object
      description: Early termination condition for a module
      properties:
        skip_if_stopped:
          type: boolean
          description: If true, following steps are skipped when this condition triggers
        expr:
          type: string
          description: JavaScript expression evaluated after the module runs. Can use 'result' (step's result) or 'flow_input'. Return true to stop
        error_message:
          type: string
          description: Custom error message shown when stopping
      required:
        - expr

    FlowModule:
      type: object
      description: A single step in a flow. Can be a script, subflow, loop, or branch
      properties:
        id:
          type: string
          description: Unique identifier for this step. Used to reference results via 'results.step_id'. Must be a valid identifier (alphanumeric, underscore, hyphen)
        value:
          $ref: '#/components/schemas/FlowModuleValue'
        stop_after_if:
          description: Early termination condition evaluated after this step completes
          $ref: '#/components/schemas/StopAfterIf'
        stop_after_all_iters_if:
          description: For loops only - early termination condition evaluated after all iterations complete
          $ref: '#/components/schemas/StopAfterIf'
        skip_if:
          type: object
          description: Conditionally skip this step based on previous results or flow inputs
          properties:
            expr:
              type: string
              description: JavaScript expression that returns true to skip. Can use 'flow_input' or 'results.<step_id>'
          required:
            - expr
        sleep:
          description: Delay before executing this step (in seconds or as expression)
          $ref: '#/components/schemas/InputTransform'
        cache_ttl:
          type: number
          description: Cache duration in seconds for this step's results
        cache_ignore_s3_path:
          type: boolean
        timeout:
          description: Maximum execution time in seconds (static value or expression)
          $ref: '#/components/schemas/InputTransform'
        delete_after_use:
          type: boolean
          description: If true, this step's result is deleted after use to save memory
        summary:
          type: string
          description: Short description of what this step does
        mock:
          type: object
          description: Mock configuration for testing without executing the actual step
          properties:
            enabled:
              type: boolean
              description: If true, return mock value instead of executing
            return_value:
              description: Value to return when mocked
        suspend:
          type: object
          description: Configuration for approval/resume steps that wait for user input
          properties:
            required_events:
              type: integer
              description: Number of approvals required before continuing
            timeout:
              type: integer
              description: Timeout in seconds before auto-continuing or canceling
            resume_form:
              type: object
              description: Form schema for collecting input when resuming
              properties:
                schema:
                  type: object
                  description: JSON Schema for the resume form
            user_auth_required:
              type: boolean
              description: If true, only authenticated users can approve
            user_groups_required:
              description: Expression or list of groups that can approve
              $ref: '#/components/schemas/InputTransform'
            self_approval_disabled:
              type: boolean
              description: If true, the user who started the flow cannot approve
            hide_cancel:
              type: boolean
              description: If true, hide the cancel button on the approval form
            continue_on_disapprove_timeout:
              type: boolean
              description: If true, continue flow on timeout instead of canceling
        priority:
          type: number
          description: Execution priority for this step (higher numbers run first)
        continue_on_error:
          type: boolean
          description: If true, flow continues even if this step fails
        retry:
          description: Retry configuration if this step fails
          $ref: '#/components/schemas/Retry'
      required:
        - value
        - id

    InputTransform:
      description: Maps input parameters for a step. Can be a static value or a JavaScript expression that references previous results or flow inputs
      oneOf:
        - $ref: '#/components/schemas/StaticTransform'
        - $ref: '#/components/schemas/JavascriptTransform'
        - $ref: '#/components/schemas/AiTransform'
      discriminator:
        propertyName: type
        mapping:
          static: '#/components/schemas/StaticTransform'
          javascript: '#/components/schemas/JavascriptTransform'
          ai: '#/components/schemas/AiTransform'

    StaticTransform:
      type: object
      description: Static value passed directly to the step. Use for hardcoded values or resource references like '$res:path/to/resource'
      properties:
        value:
          description: The static value. For resources, use format '$res:path/to/resource'
        type:
          type: string
          enum:
            - static
      required:
        - type

    JavascriptTransform:
      type: object
      description: JavaScript expression evaluated at runtime. Can reference previous step results via 'results.step_id' or flow inputs via 'flow_input.property'. Inside loops, use 'flow_input.iter.value' for the current iteration value
      properties:
        expr:
          type: string
          description: JavaScript expression returning the value. Available variables - results (object with all previous step results), flow_input (flow inputs), flow_input.iter (in loops)
        type:
          type: string
          enum:
            - javascript
      required:
        - expr
        - type

    AiTransform:
      type: object
      description: Value resolved by the AI runtime for this input. The AI engine decides how to satisfy the parameter.
      properties:
        type:
          type: string
          enum:
            - ai
      required:
        - type

    FlowModuleValue:
      description: The actual implementation of a flow step. Can be a script (inline or referenced), subflow, loop, branch, or special module type
      oneOf:
        - $ref: '#/components/schemas/RawScript'
        - $ref: '#/components/schemas/PathScript'
        - $ref: '#/components/schemas/PathFlow'
        - $ref: '#/components/schemas/ForloopFlow'
        - $ref: '#/components/schemas/WhileloopFlow'
        - $ref: '#/components/schemas/BranchOne'
        - $ref: '#/components/schemas/BranchAll'
        - $ref: '#/components/schemas/Identity'
        - $ref: '#/components/schemas/AiAgent'
      discriminator:
        propertyName: type
        mapping:
          rawscript: '#/components/schemas/RawScript'
          script: '#/components/schemas/PathScript'
          flow: '#/components/schemas/PathFlow'
          forloopflow: '#/components/schemas/ForloopFlow'
          whileloopflow: '#/components/schemas/WhileloopFlow'
          branchone: '#/components/schemas/BranchOne'
          branchall: '#/components/schemas/BranchAll'
          identity: '#/components/schemas/Identity'
          aiagent: '#/components/schemas/AiAgent'

    RawScript:
      type: object
      description: Inline script with code defined directly in the flow. Use 'bun' as default language if unspecified. The script receives arguments from input_transforms
      properties:
        # to be made required once migration is over
        input_transforms:
          type: object
          description: Map of parameter names to their values (static or JavaScript expressions). These become the script's input arguments
          additionalProperties:
            $ref: '#/components/schemas/InputTransform'
        content:
          type: string
          description: The script source code. Should export a 'main' function
        language:
          type: string
          description: Programming language for this script
          enum:
            - deno
            - bun
            - python3
            - go
            - bash
            - powershell
            - postgresql
            - mysql
            - bigquery
            - snowflake
            - mssql
            - oracledb
            - graphql
            - nativets
            - php
            # TODO: Add missing languages
        path:
          type: string
          description: Optional path for saving this script
        lock:
          type: string
          description: Lock file content for dependencies
        type:
          type: string
          enum:
            - rawscript
        tag:
          type: string
          description: Worker group tag for execution routing
        concurrent_limit:
          type: number
          description: Maximum concurrent executions of this script
        concurrency_time_window_s:
          type: number
          description: Time window for concurrent_limit
        custom_concurrency_key:
          type: string
          description: Custom key for grouping concurrent executions
        is_trigger:
          type: boolean
          description: If true, this script is a trigger that can start the flow
        assets:
          type: array
          description: External resources this script accesses (S3 objects, resources, etc.)
          items:
            type: object
            required:
              - path
              - kind
            properties:
              path:
                type: string
                description: Path to the asset
              kind:
                type: string
                description: Type of asset
                enum:
                  - s3object
                  - resource
                  - ducklake
                  - datatable
              access_type:
                type: string
                description: Access level for this asset
                enum: [r, w, rw]
              alt_access_type:
                type: string
                description: Alternative access level
                enum: [r, w, rw]
      required:
        - type
        - content
        - language
        - input_transforms

    PathScript:
      type: object
      description: Reference to an existing script by path. Use this when calling a previously saved script instead of writing inline code
      properties:
        input_transforms:
          type: object
          description: Map of parameter names to their values (static or JavaScript expressions). These become the script's input arguments
          additionalProperties:
            $ref: '#/components/schemas/InputTransform'
        path:
          type: string
          description: Path to the script in the workspace (e.g., 'f/scripts/send_email')
        hash:
          type: string
          description: Optional specific version hash of the script to use
        type:
          type: string
          enum:
            - script
        tag_override:
          type: string
          description: Override the script's default worker group tag
        is_trigger:
          type: boolean
          description: If true, this script is a trigger that can start the flow
      required:
        - type
        - path
        - input_transforms

    PathFlow:
      type: object
      description: Reference to an existing flow by path. Use this to call another flow as a subflow
      properties:
        input_transforms:
          type: object
          description: Map of parameter names to their values (static or JavaScript expressions). These become the subflow's input arguments
          additionalProperties:
            $ref: '#/components/schemas/InputTransform'
        path:
          type: string
          description: Path to the flow in the workspace (e.g., 'f/flows/process_user')
        type:
          type: string
          enum:
            - flow
      required:
        - type
        - path
        - input_transforms

    ForloopFlow:
      type: object
      description: Executes nested modules in a loop over an iterator. Inside the loop, use 'flow_input.iter.value' to access the current iteration value, and 'flow_input.iter.index' for the index. Supports parallel execution for better performance on I/O-bound operations
      properties:
        modules:
          type: array
          description: Steps to execute for each iteration. These can reference the iteration value via 'flow_input.iter.value'
          items:
            $ref: '#/components/schemas/FlowModule'
        iterator:
          description: JavaScript expression that returns an array to iterate over. Can reference 'results.step_id' or 'flow_input'
          $ref: '#/components/schemas/InputTransform'
        skip_failures:
          type: boolean
          description: If true, iteration failures don't stop the loop. Failed iterations return null
        type:
          type: string
          enum:
            - forloopflow
        parallel:
          type: boolean
          description: If true, iterations run concurrently (faster for I/O-bound operations). Use with parallelism to control concurrency
        parallelism:
          description: Maximum number of concurrent iterations when parallel=true. Limits resource usage. Can be static number or expression
          $ref: '#/components/schemas/InputTransform'
        squash:
          type: boolean
      required:
        - modules
        - iterator
        - skip_failures
        - type

    WhileloopFlow:
      type: object
      description: Executes nested modules repeatedly while a condition is true. The loop checks the condition after each iteration. Use stop_after_if on modules to control loop termination
      properties:
        modules:
          type: array
          description: Steps to execute in each iteration. Use stop_after_if to control when the loop ends
          items:
            $ref: '#/components/schemas/FlowModule'
        skip_failures:
          type: boolean
          description: If true, iteration failures don't stop the loop. Failed iterations return null
        type:
          type: string
          enum:
            - whileloopflow
        parallel:
          type: boolean
          description: If true, iterations run concurrently (use with caution in while loops)
        parallelism:
          description: Maximum number of concurrent iterations when parallel=true
          $ref: '#/components/schemas/InputTransform'
        squash:
          type: boolean
      required:
        - modules
        - skip_failures
        - type

    BranchOne:
      type: object
      description: Conditional branching where only the first matching branch executes. Branches are evaluated in order, and the first one with a true expression runs. If no branches match, the default branch executes
      properties:
        branches:
          type: array
          description: Array of branches to evaluate in order. The first branch with expr evaluating to true executes
          items:
            type: object
            properties:
              summary:
                type: string
                description: Short description of this branch condition
              expr:
                type: string
                description: JavaScript expression that returns boolean. Can use 'results.step_id' or 'flow_input'. First true expr wins
              modules:
                type: array
                description: Steps to execute if this branch's expr is true
                items:
                  $ref: '#/components/schemas/FlowModule'
            required:
              - modules
              - expr
        default:
          type: array
          description: Steps to execute if no branch expressions match
          items:
            $ref: '#/components/schemas/FlowModule'
        type:
          type: string
          enum:
            - branchone
      required:
        - branches
        - default
        - type

    BranchAll:
      type: object
      description: Parallel branching where all branches execute simultaneously. Unlike BranchOne, all branches run regardless of conditions. Useful for executing independent tasks concurrently
      properties:
        branches:
          type: array
          description: Array of branches that all execute (either in parallel or sequentially)
          items:
            type: object
            properties:
              summary:
                type: string
                description: Short description of this branch's purpose
              skip_failure:
                type: boolean
                description: If true, failure in this branch doesn't fail the entire flow
              modules:
                type: array
                description: Steps to execute in this branch
                items:
                  $ref: '#/components/schemas/FlowModule'
            required:
              - modules
        type:
          type: string
          enum:
            - branchall
        parallel:
          type: boolean
          description: If true, all branches execute concurrently. If false, they execute sequentially
      required:
        - branches
        - type

    AgentTool:
      type: object
      description: A tool available to an AI agent. Can be a flow module or an external MCP (Model Context Protocol) tool
      properties:
        id:
          type: string
          description: Unique identifier for this tool. Cannot contain spaces - use underscores instead (e.g., 'get_user_data' not 'get user data')
        summary:
          type: string
          description: Short description of what this tool does (shown to the AI)
        value:
          $ref: '#/components/schemas/ToolValue'
      required:
        - id
        - value

    ToolValue:
      description: The implementation of a tool. Can be a flow module (script/flow) or an MCP tool reference
      oneOf:
        - $ref: '#/components/schemas/FlowModuleTool'
        - $ref: '#/components/schemas/McpToolValue'
        - $ref: '#/components/schemas/WebsearchToolValue'
      discriminator:
        propertyName: tool_type
        mapping:
          flowmodule: '#/components/schemas/FlowModuleTool'
          mcp: '#/components/schemas/McpToolValue'
          websearch: '#/components/schemas/WebsearchToolValue'

    FlowModuleTool:
      description: A tool implemented as a flow module (script, flow, etc.). The AI can call this like any other flow module
      allOf:
        - type: object
          properties:
            tool_type:
              type: string
              enum:
                - flowmodule
          required:
            - tool_type
        - $ref: '#/components/schemas/FlowModuleValue'

    WebsearchToolValue:
      type: object
      description: A tool implemented as a websearch tool. The AI can call this like any other websearch tool
      properties:
        tool_type:
          type: string
          enum:
            - websearch
      required:
        - tool_type

    McpToolValue:
      type: object
      description: Reference to an external MCP (Model Context Protocol) tool. The AI can call tools from MCP servers
      properties:
        tool_type:
          type: string
          enum:
            - mcp
        resource_path:
          type: string
          description: Path to the MCP resource/server configuration
        include_tools:
          type: array
          description: Whitelist of specific tools to include from this MCP server
          items:
            type: string
        exclude_tools:
          type: array
          description: Blacklist of tools to exclude from this MCP server
          items:
            type: string
      required:
        - tool_type
        - resource_path

    AiAgent:
      type: object
      description: AI agent step that can use tools to accomplish tasks. The agent receives inputs and can call any of its configured tools to complete the task
      properties:
        input_transforms:
          type: object
          description: Input parameters for the AI agent mapped to their values
          properties:
            provider:
              $ref: '#/components/schemas/InputTransform'
            output_type:
              $ref: '#/components/schemas/InputTransform'
            user_message:
              $ref: '#/components/schemas/InputTransform'
            system_prompt:
              $ref: '#/components/schemas/InputTransform'
            streaming:
              $ref: '#/components/schemas/InputTransform'
            memory:
              $ref: '#/components/schemas/InputTransform'
            output_schema:
              $ref: '#/components/schemas/InputTransform'
            user_images:
              $ref: '#/components/schemas/InputTransform'
            max_completion_tokens:
              $ref: '#/components/schemas/InputTransform'
            temperature:
              $ref: '#/components/schemas/InputTransform'
          required:
            - provider
            - user_message
            - output_type
        tools:
          type: array
          description: Array of tools the agent can use. The agent decides which tools to call based on the task
          items:
            $ref: '#/components/schemas/AgentTool'
        type:
          type: string
          enum:
            - aiagent
        parallel:
          type: boolean
          description: If true, the agent can execute multiple tool calls in parallel
      required:
        - tools
        - type
        - input_transforms

    Identity:
      type: object
      description: Pass-through module that returns its input unchanged. Useful for flow structure or as a placeholder
      properties:
        type:
          type: string
          enum:
            - identity
        flow:
          type: boolean
          description: If true, marks this as a flow identity (special handling)

      required:
        - type

    FlowStatus:
      type: object
      properties:
        step:
          type: integer
        modules:
          type: array
          items:
            $ref: '#/components/schemas/FlowStatusModule'
        user_states:
          additionalProperties: true
        preprocessor_module:
          allOf:
            - $ref: '#/components/schemas/FlowStatusModule'
        failure_module:
          allOf:
            - $ref: '#/components/schemas/FlowStatusModule'
            - type: object
              properties:
                parent_module:
                  type: string
        retry:
          type: object
          properties:
            fail_count:
              type: integer
            failed_jobs:
              type: array
              items:
                type: string
                format: uuid
      required:
        - step
        - modules
        - failure_module

    FlowStatusModule:
      type: object
      properties:
        type:
          type: string
          enum:
            - WaitingForPriorSteps
            - WaitingForEvents
            - WaitingForExecutor
            - InProgress
            - Success
            - Failure
        id:
          type: string
        job:
          type: string
          format: uuid
        count:
          type: integer
        progress:
          type: integer
        iterator:
          type: object
          properties:
            index:
              type: integer
            itered:
              type: array
              items: {}
            itered_len:
              type: integer
            args: {}
        flow_jobs:
          type: array
          items:
            type: string
        flow_jobs_success:
          type: array
          items:
            type: boolean
        flow_jobs_duration:
          type: object
          properties:
            started_at:
              type: array
              items:
                type: string
            duration_ms:
              type: array
              items:
                type: integer
        branch_chosen:
          type: object
          properties:
            type:
              type: string
              enum: [branch, default]
            branch:
              type: integer
          required:
            - type
        branchall:
          type: object
          properties:
            branch:
              type: integer
            len:
              type: integer
          required:
            - branch
            - len
        approvers:
          type: array
          items:
            type: object
            properties:
              resume_id:
                type: integer
              approver:
                type: string
            required:
              - resume_id
              - approver
        failed_retries:
          type: array
          items:
            type: string
            format: uuid
        skipped:
          type: boolean
        agent_actions:
          type: array
          items:
            type: object
            oneOf:
              - type: object
                properties:
                  job_id:
                    type: string
                    format: uuid
                  function_name:
                    type: string
                  type:
                    type: string
                    enum: [tool_call]
                  module_id:
                    type: string
                required:
                  - job_id
                  - function_name
                  - type
                  - module_id
              - type: object
                properties:
                  call_id:
                    type: string
                    format: uuid
                  function_name:
                    type: string
                  resource_path:
                    type: string
                  type:
                    type: string
                    enum: [mcp_tool_call]
                  arguments:
                    type: object
                required:
                  - call_id
                  - function_name
                  - resource_path
                  - type
              - type: object
                properties:
                  type:
                    type: string
                    enum: [web_search]
                required:
                  - type
              - type: object
                properties:
                  type:
                    type: string
                    enum: [message]
                required:
                  - content
                  - type
        agent_actions_success:
          type: array
          items:
            type: boolean
      required: [type]