windmill/openflow.openapi.yaml

openapi: '3.0.3'

info:
  version: 1.773.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')
        on_behalf_of_email:
          type: string
          description: The flow will be run with the permissions of the user with this email.
      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
        preserve_step_tags:
          type: boolean
          description: If true and the flow runs on a custom worker tag, steps that declare their own non-empty tag run on it instead of inheriting the flow tag. Steps without their own tag still inherit the flow tag.
        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: integer
          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: integer
          description: Maximum total time in seconds that a job can be debounced
        max_total_debounces_amount:
          type: integer
          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
        delete_after_secs:
          type: integer
          description: If set, delete the flow job's args, result and logs after this many seconds following job completion
        flow_env:
          type: object
          description: "Environment variables available to all steps. Values can be strings, JSON values, or special references: '$var:path' (workspace variable) or '$res:path' (resource)."
          additionalProperties: {}
        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'
        groups:
          type: array
          description: Semantic groups of modules for organizational purposes
          items:
            $ref: '#/components/schemas/FlowGroup'
      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

    FlowGroup:
      type: object
      description: A semantic group of flow modules for organizational purposes. Does not affect execution — modules remain in their original position in the flow. Groups provide naming and collapsibility in the editor. Members are computed dynamically from all nodes on paths between start_id and end_id.
      properties:
        summary:
          type: string
          description: Display name for this group
        note:
          type: string
          description: Markdown note shown below the group header
        autocollapse:
          type: boolean
          default: false
          description: If true, this group is collapsed by default in the flow editor. UI hint only.
        start_id:
          type: string
          description: ID of the first flow module in this group (topological entry point)
        end_id:
          type: string
          description: ID of the last flow module in this group (topological exit point)
        color:
          type: string
          description: Color for the group in the flow editor
      required:
        - start_id
        - end_id

    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
          nullable: true
          description: Custom error message when stopping with an error. Mutually exclusive with skip_if_stopped. If set to a non-empty string, the flow stops with this error. If empty string, a default error message is used. If null or omitted, no error is raised.
        error_include_result:
          type: boolean
          description: "When stopping with an error (error_message set), embed the stopping step's own result inside the raised error object (as error.result) instead of discarding it. The top-level result stays { error }. Defaults to false."
      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_secs:
          type: integer
          description: If set, delete the step's args, result and logs after this many seconds following job completion
        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'
        debouncing:
          description: "Debounce configuration for this step (EE only)"
          type: object
          properties:
            debounce_delay_s:
              type: integer
              description: Delay in seconds to debounce this step's executions across flow runs
            debounce_key:
              type: string
              description: "Expression to group debounced executions. Supports $workspace and $args[name]. Default: $workspace/flow/<flow_path>-<step_id>"
            debounce_args_to_accumulate:
              type: array
              description: Array-type arguments to accumulate across debounced executions
              items:
                type: string
            max_total_debouncing_time:
              type: integer
              description: Maximum total time in seconds before forced execution
            max_total_debounces_amount:
              type: integer
              description: Maximum number of debounces before forced execution
      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 for loops, use 'flow_input.iter.value' for the current iteration value (in while loops it equals 'flow_input.iter.index')
      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

    # Provider configuration schemas
    AIProviderKind:
      type: string
      description: Supported AI provider types
      enum:
        - openai
        - azure_openai
        - azure_foundry
        - anthropic
        - mistral
        - deepseek
        - googleai
        - groq
        - openrouter
        - togetherai
        - customai
        - aws_bedrock

    ProviderConfig:
      type: object
      description: Complete AI provider configuration with resource reference and model selection
      properties:
        kind:
          $ref: '#/components/schemas/AIProviderKind'
        resource:
          type: string
          description: Resource reference in format '$res:{resource_path}' pointing to provider credentials
        model:
          type: string
          description: Model identifier (e.g., 'gpt-4', 'claude-3-opus-20240229', 'gemini-pro')
        reasoning_effort:
          type: string
          description: Provider-native reasoning effort token (e.g. 'low', 'high', 'none') for models that support extended thinking. Optional; unset leaves the provider default.
      required:
        - kind
        - resource
        - model

    StaticProviderTransform:
      type: object
      description: Static provider configuration passed directly to the AI agent
      properties:
        value:
          $ref: '#/components/schemas/ProviderConfig'
        type:
          type: string
          enum:
            - static
      required:
        - type
        - value

    ProviderTransform:
      description: Provider configuration - can be static (ProviderConfig), JavaScript expression, or AI-determined
      oneOf:
        - $ref: '#/components/schemas/StaticProviderTransform'
        - $ref: '#/components/schemas/JavascriptTransform'
        - $ref: '#/components/schemas/AiTransform'
      discriminator:
        propertyName: type
        mapping:
          static: '#/components/schemas/StaticProviderTransform'
          javascript: '#/components/schemas/JavascriptTransform'
          ai: '#/components/schemas/AiTransform'

    # Memory configuration schemas
    MemoryOff:
      type: object
      description: No conversation memory/context
      properties:
        kind:
          type: string
          enum:
            - 'off'
      required:
        - kind

    MemoryAuto:
      type: object
      description: Automatic context management
      properties:
        kind:
          type: string
          enum:
            - auto
        context_length:
          type: integer
          description: Maximum number of messages to retain in context
        memory_id:
          type: string
          description: Identifier for persistent memory across agent invocations
      required:
        - kind

    MemoryMessage:
      type: object
      description: A single message in conversation history
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
            - system
        content:
          type: string
      required:
        - role
        - content

    MemoryManual:
      type: object
      description: Explicit message history
      properties:
        kind:
          type: string
          enum:
            - manual
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MemoryMessage'
      required:
        - kind
        - messages

    MemoryConfig:
      description: Conversation memory configuration
      oneOf:
        - $ref: '#/components/schemas/MemoryOff'
        - $ref: '#/components/schemas/MemoryAuto'
        - $ref: '#/components/schemas/MemoryManual'
      discriminator:
        propertyName: kind
        mapping:
          'off': '#/components/schemas/MemoryOff'
          auto: '#/components/schemas/MemoryAuto'
          manual: '#/components/schemas/MemoryManual'

    StaticMemoryTransform:
      type: object
      description: Static memory configuration passed directly to the AI agent
      properties:
        value:
          $ref: '#/components/schemas/MemoryConfig'
        type:
          type: string
          enum:
            - static
      required:
        - type
        - value

    MemoryTransform:
      description: Memory configuration - can be static (MemoryConfig), JavaScript expression, or AI-determined
      oneOf:
        - $ref: '#/components/schemas/StaticMemoryTransform'
        - $ref: '#/components/schemas/JavascriptTransform'
        - $ref: '#/components/schemas/AiTransform'
      discriminator:
        propertyName: type
        mapping:
          static: '#/components/schemas/StaticMemoryTransform'
          javascript: '#/components/schemas/JavascriptTransform'
          ai: '#/components/schemas/AiTransform'

    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
            - bunnative
            - python3
            - go
            - bash
            - powershell
            - postgresql
            - mysql
            - bigquery
            - snowflake
            - mssql
            - oracledb
            - graphql
            - nativets
            - php
            - rust
            - ansible
            - csharp
            - nu
            - java
            - ruby
            - rlang
            - duckdb
            # for related places search: ADD_NEW_LANG
        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
                  - volume
              access_type:
                type: string
                nullable: true
                description: Access level for this asset
                enum: [r, w, rw]
              alt_access_type:
                type: string
                nullable: true
                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 until stopped. The implicit iterator is the iteration counter, so 'flow_input.iter.value' equals 'flow_input.iter.index' (0, 1, 2, ...) and never carries state. To carry state across iterations, a step reads its own previous-iteration result via 'results.<its_own_id>' with a first-iteration fallback - the loop's stop_after_if must then be on that inner step (a plain single-step body with stop_after_if on the loop module does not resolve 'results' across iterations and never terminates); plain counters can instead be derived from 'flow_input.iter.index', which works in every configuration. stop_after_if is evaluated after each iteration - on the loop module 'result' is the last iteration's result
      properties:
        modules:
          type: array
          description: Steps to execute in each iteration
          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)
        description:
          type: string
          description: Free-text description of the tool given to the AI to decide when and how to call it. Overrides the description auto-derived from the underlying script.
        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/ProviderTransform'
            output_type:
              allOf:
                - $ref: '#/components/schemas/InputTransform'
              description: |
                Output format type.
                Valid values: 'text' (default) - plain text response, 'image' - image generation
            user_message:
              allOf:
                - $ref: '#/components/schemas/InputTransform'
              description: The user's prompt/message to the AI agent. Supports variable interpolation with flow.input syntax.
            system_prompt:
              allOf:
                - $ref: '#/components/schemas/InputTransform'
              description: System instructions that guide the AI's behavior, persona, and response style. Optional.
            streaming:
              allOf:
                - $ref: '#/components/schemas/InputTransform'
              description: |
                Boolean. If true, stream the AI response incrementally.
                Streaming events include: token_delta, reasoning_token_delta, tool_call, tool_call_arguments, tool_execution, tool_result
            memory:
              $ref: '#/components/schemas/MemoryTransform'
            output_schema:
              allOf:
                - $ref: '#/components/schemas/InputTransform'
              description: |
                JSON Schema object defining structured output format. Used when you need the AI to return data in a specific shape.
                Supports standard JSON Schema properties: type, properties, required, items, enum, pattern, minLength, maxLength, minimum, maximum, etc.
                Example: { type: 'object', properties: { name: { type: 'string' }, age: { type: 'integer' } }, required: ['name'] }
            user_attachments:
              allOf:
                - $ref: '#/components/schemas/InputTransform'
              description: |
                Array of file references (images or PDFs) for the AI agent.
                Format: Array<{ bucket: string, key: string }> - S3 object references
                Example: [{ bucket: 'my-bucket', key: 'documents/report.pdf' }]
            max_completion_tokens:
              allOf:
                - $ref: '#/components/schemas/InputTransform'
              description: |
                Integer. Maximum number of tokens the AI will generate in its response.
                Range: 1 to 4,294,967,295. Typical values: 256-4096 for most use cases.
            temperature:
              allOf:
                - $ref: '#/components/schemas/InputTransform'
              description: |
                Float. Controls randomness/creativity of responses.
                Range: 0.0 to 2.0 (provider-dependent)
                - 0.0 = deterministic, focused responses
                - 0.7 = balanced (common default)
                - 1.0+ = more creative/random
            max_iterations:
              allOf:
                - $ref: '#/components/schemas/InputTransform'
              description: |
                Number. Limits how many times the agent can loop through reasoning and tool use.
                Range: 1-1000.
          # Only the flow-local inputs are always present: a step linked to an `ai_agent` resource
          # (see `agent`) keeps just those and takes provider/output_type from the resource.
          required:
            - user_message
        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
        tag:
          type: string
          description: Worker group tag for execution routing. If not set, the AI agent step runs on the flow's tag (default `flow`)
        omit_output_from_conversation:
          type: boolean
          default: false
          description: If true, this AI agent step does not persist its assistant or tool messages to the flow conversation when chat mode is enabled.
        agent:
          type: string
          description: |
            Path of a reusable `ai_agent` resource (hybrid linking). When set, the agent brain
            config (provider/model/system prompt/etc.) and tool set are resolved at runtime from
            that resource; the module's input_transforms then only carry the flow-local inputs
            (user_message/user_attachments).
        tool_inputs:
          type: object
          description: |
            Host-local wiring for an agent's tool inputs, keyed by tool id then input key. Binds the
            referenced agent's tools to this flow's context (flow_input/results) without mutating the
            shared resource; overlaid onto the tools' input_transforms at runtime — including when
            `agent` is unset, since a step forked for editing keeps these overrides until it is saved
            back or unlinked.
          additionalProperties:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/InputTransform'
        parallel:
          type: boolean
          description: If true, the agent can execute multiple tool calls in parallel
      required:
        - 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]