{
    "openapi": "3.0.3",
    "info": {
        "version": "1.775.2",
        "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"
                }
            },
            "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"
                ]
            },
            "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"
                }
            },
            "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"
                }
            },
            "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"
                }
            },
            "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"
                }
            },
            "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": {
                    "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"
                        ]
                    },
                    "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",
                                        null
                                    ]
                                },
                                "alt_access_type": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "Alternative access level",
                                    "enum": [
                                        "r",
                                        "w",
                                        "rw",
                                        null
                                    ]
                                }
                            }
                        }
                    }
                },
                "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"
                    }
                ]
            },
            "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.\nValid values: 'text' (default) - plain text response, 'image' - image generation\n"
                            },
                            "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.\nStreaming events include: token_delta, reasoning_token_delta, tool_call, tool_call_arguments, tool_execution, tool_result\n"
                            },
                            "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.\nSupports standard JSON Schema properties: type, properties, required, items, enum, pattern, minLength, maxLength, minimum, maximum, etc.\nExample: { type: 'object', properties: { name: { type: 'string' }, age: { type: 'integer' } }, required: ['name'] }\n"
                            },
                            "user_attachments": {
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/InputTransform"
                                    }
                                ],
                                "description": "Array of file references (images or PDFs) for the AI agent.\nFormat: Array<{ bucket: string, key: string }> - S3 object references\nExample: [{ bucket: 'my-bucket', key: 'documents/report.pdf' }]\n"
                            },
                            "max_completion_tokens": {
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/InputTransform"
                                    }
                                ],
                                "description": "Integer. Maximum number of tokens the AI will generate in its response.\nRange: 1 to 4,294,967,295. Typical values: 256-4096 for most use cases.\n"
                            },
                            "temperature": {
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/InputTransform"
                                    }
                                ],
                                "description": "Float. Controls randomness/creativity of responses.\nRange: 0.0 to 2.0 (provider-dependent)\n- 0.0 = deterministic, focused responses\n- 0.7 = balanced (common default)\n- 1.0+ = more creative/random\n"
                            },
                            "max_iterations": {
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/InputTransform"
                                    }
                                ],
                                "description": "Number. Limits how many times the agent can loop through reasoning and tool use.\nRange: 1-1000.\n"
                            }
                        },
                        "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\nconfig (provider/model/system prompt/etc.) and tool set are resolved at runtime from\nthat resource; the module's input_transforms then only carry the flow-local inputs\n(user_message/user_attachments).\n"
                    },
                    "tool_inputs": {
                        "type": "object",
                        "description": "Host-local wiring for an agent's tool inputs, keyed by tool id then input key. Binds the\nreferenced agent's tools to this flow's context (flow_input/results) without mutating the\nshared resource; overlaid onto the tools' input_transforms at runtime — including when\n`agent` is unset, since a step forked for editing keeps these overrides until it is saved\nback or unlinked.\n",
                        "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"
                ]
            }
        }
    }
}