Flow YAML Reference

This page documents every attribute available in a Flow document — the envelope the Flow Builder posts, whether you edit on the canvas or in the YAML view.

Top-Level Structure

flow:                  # Flow metadata (required)
  name: string
  runtime:              # (Optional) flow-level runtime defaults
nodes:                 # List of node definitions (required)
  - id: string
    type: string
    label: string
    config: {}
    runtime: {}          # (Optional) per-node runtime override
connections:           # List of directed edges between nodes (optional)
  - from: string
    to: string
    from_port: string
    to_port: string

A minimal flow needs a flow.name, at least a start node, and at least one response or output node:

flow:
  name: "Minimal Flow"
nodes:
  - id: trigger
    type: start
    config: {}
  - id: finish
    type: response
    config: {}
connections:
  - from: trigger
    to: finish

`flow`

Attribute	Type	Description
`name`	string	Flow display name (required)
`runtime`	object	(Optional) Default runtime override applied to every node that doesn’t set its own

`nodes`

The list of steps that make up the flow. Every node’s config is validated against its type’s schema on deploy/run — an unknown type or an invalid config fails validation with a structured, per-node issue.

Attribute	Type	Default	Description
`id`	string	—	Unique identifier for the node within the flow (required)
`type`	string	—	Node type — see the Node Reference for all 9 types (required)
`label`	string	`null`	(Optional) Display name shown on the canvas
`config`	object	`{}`	Type-specific configuration
`runtime`	object	`null`	(Optional) Runtime override for this node only

`runtime`

An optional block — settable at the flow level (as a default) or per-node (as an override) — controlling how a node’s compiled code executes:

Attribute	Type	Default	Description
`mode`	string	`auto`	One of `auto`, `subprocess`, `pod`
`engine`	string	`null`	(Optional) Execution engine override
`timeout_sec`	int	`null`	(Optional) Timeout in seconds, overriding the node type’s own default
`memory_mb`	int	`null`	(Optional) Memory limit in MB
`max_input_rows`	int	`null`	(Optional) Cap on input row count
`max_input_bytes`	int	`null`	(Optional) Cap on input payload size in bytes

- id: heavy_call
  type: rest_call
  config:
    url: "https://api.example.com/report"
  runtime:
    timeout_sec: 120
    memory_mb: 512

`connections`

Directed edges between nodes. Each entry wires one node’s output port to another node’s input port.

Attribute	Type	Default	Description
`from`	string	—	Id of the upstream node (required)
`to`	string	—	Id of the downstream node (required)
`from_port`	string	node’s first output	(Optional) Which output port of `from` this connection leaves from
`to_port`	string	node’s first input	(Optional) Which input port of `to` this connection arrives at

connections:
  - from: fetch_weather
    to: process
    from_port: response
    to_port: in

Branching connections

Outgoing connections from a branching node (currently only if) must explicitly set from_port to one of that node’s declared output ports (true/false) — an omitted or invalid from_port fails validation:

connections:
  - from: check_status
    to: send_email
    from_port: "true"
  - from: check_status
    to: log_rejection
    from_port: "false"

Required inputs

Some node types declare required_inputs — input ports that must have an incoming connection for the flow to be valid. response and output both require their in port to be connected.

Node types at a glance

Full attribute tables for every type live in the Node Reference. Quick summary:

Type	Category	Inputs	Outputs	Notes
`start`	trigger	—	`out`	Entry point; no config
`if`	control	`in`	`true`, `false`	Branching — `from_port` required on outgoing connections
`for_each`	control	`in`	`out`	Container — owns a nested `body` `FlowDocument`
`llm_call`	ai	`in`	`out`	Needs credentials; calls a Model Account
`rest_call`	integration	`in`	`response`	Calls an external HTTP endpoint
`action_call`	integration	`in`	`out`	Needs credentials; calls a project Action
`python`	transform	`in`	`out`	Runs a `handler(inputs, parameters)` function
`response`	terminal	`in` (required)	—	At most one per flow (exactly one inside a `for_each` body)
`output`	sink	`in` (required)	—	Writes to a dataset, webhook, or file

`for_each.config.body`

The one node type whose config embeds a full nested document, following the exact same top-level structure as a flow:

- id: process_orders
  type: for_each
  config:
    items: "inputs['in']['orders']"
    item_as: order
    save_as: results
    body:
      flow:
        name: process_orders_body
      nodes:
        - id: body_start
          type: start
          config: {}
        - id: format_order
          type: python
          config:
            code: |
              def handler(inputs, parameters):
                  return {"total": parameters["order"]["amount"] * 1.1}
        - id: body_response
          type: response
          config: {}
      connections:
        - from: body_start
          to: format_order
        - from: format_order
          to: body_response

The body may itself contain a nested for_each (up to a maximum depth of 5).
The body must contain exactly one response node — its output becomes that iteration’s result.

Full example

The “London Weather Demo” starter template — fetches current weather, transforms it, and returns a structured summary:

flow:
  name: "London Weather Demo"

nodes:
  - id: trigger
    type: start
    label: Start
    config: {}

  - id: fetch_weather
    type: rest_call
    label: Fetch London weather
    config:
      url: "https://api.open-meteo.com/v1/forecast"
      method: GET
      query:
        latitude: "51.5074"
        longitude: "-0.1278"
        current_weather: "true"
      timeout_sec: 30
      save_as: weather

  - id: process
    type: python
    label: Convert temperature
    config:
      code: |
        def handler(inputs, parameters):
            # inputs     – dict of upstream node outputs, keyed by port name
            # parameters – dict of flow run parameters
            payload = inputs.get("in") or {}
            weather = payload.get("weather", {})
            current = weather.get("current_weather", {})
            celsius = current.get("temperature")
            if celsius is None:
                raise ValueError("No temperature in weather response")

            fahrenheit = round(celsius * 9 / 5 + 32, 1)
            wind = current.get("windspeed", 0)

            return {
                "city": parameters.get("city", "London"),
                "celsius": celsius,
                "fahrenheit": fahrenheit,
                "windspeed_kmh": wind,
                "wind_category": "calm" if wind < 10 else "breezy" if wind < 25 else "windy",
                "weather_code": current.get("weathercode"),
            }

  - id: answer
    type: response
    label: Return to caller
    config: {}

connections:
  - from: trigger
    to: fetch_weather
    to_port: in
  - from: fetch_weather
    to: process
    to_port: in
  - from: process
    to: answer
    to_port: in

Next steps

Overview - flow structure and core concepts
Node Reference - every node type, its config, and its ports
Triggers & Runs - starting a flow and reading run status
Templating & Expressions - how nodes reference upstream data and parameters

Get Started

Reference

Deployment

Tutorial

YAML Reference

Flow YAML Reference

Top-Level Structure

`flow`

`nodes`

`runtime`

`connections`

Branching connections

Required inputs

Node types at a glance

`for_each.config.body`

Full example

Next steps

​Flow YAML Reference

​Top-Level Structure

​flow

​nodes

​runtime

​connections

​Branching connections

​Required inputs

​Node types at a glance

​for_each.config.body

​Full example

​Next steps

Flow YAML Reference

Top-Level Structure

`flow`

`nodes`

`runtime`

`connections`

Branching connections

Required inputs

Node types at a glance

`for_each.config.body`

Full example

Next steps