openapi: '3.0.3' info: version: 1.600.1 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-' (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.' 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' discriminator: propertyName: type mapping: static: '#/components/schemas/StaticTransform' javascript: '#/components/schemas/JavascriptTransform' 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 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]