Workflow YAML reference

A workflow is a directed graph of typed nodes wired by edges, authored in the visual builder and serialized to YAML. The canonical shape is a single JSON Schema generated from the same zod source the web app validates against (web/src/lib/api-schemas-workflow.ts), so the document, the editor, and the runtime never disagree.

Editor validation

Every workflow exported from the builder begins with a modeline that points your editor’s yaml-language-server at the schema, giving inline validation and node-kind autocompletion:

# yaml-language-server: $schema=https://supacloud.run/schemas/workflow.json
name: nightly-triage
nodes:
  - key: classify
    kind: llm_classify
    config: {}
edges: []

Note

The schema is regenerated from zod and the committed copy is drift-checked in CI, so it always matches the running validator. Per-node config is currently an open object; per-kind sub-schemas are a follow-up.

Top-level fields

Field	Type	Notes
name	string	Workflow name.
project_id	string	The owning project.
nodes	array	The typed-node graph (the V8 builder surface).
edges	array	Connections between nodes, by source/target key.
steps	array	The v1 agent-only step view, kept for back-compat.
max_concurrent_runs	integer | null	Caps simultaneous runs; null = unbounded.

Node

Field	Type	Notes
key	string	Unique node key (referenced by edges).
kind	enum	One of the node kinds below.
config	object	Kind-specific configuration (open object today).
position	{ x, y }	Canvas coordinates for the builder.

Edge

Field	Type	Notes
source	string	Source node key.
target	string	Target node key.
source_handle	string	Which output handle the edge leaves (default out; gates use branch handles).

Node kinds

Kind	Purpose
agent	Run an AI coding agent with a prompt.
gate	Branch on a predicate to different output handles.
human	Pause for a human decision or input.
end	Terminal node.
code	Run a Bash/Python/TypeScript/Go/Rust/C# snippet (defaults to Bash). Unbound: hermetic container, no network/DB. A Python/TypeScript node may declare resource_bindings to run on the credentialed sandbox with vetted egress + a host-mediated guarded DB call (ADR 0058).
db_query	Read from a bound PostgreSQL resource.
db_execute	Write to a bound PostgreSQL resource.
http_request	Make an outbound HTTP call (SSRF-guarded, IP-pinned).
transform	Reshape data flowing between nodes.
notify_telegram	Send a Telegram message.
notify_email	Send an email.
notify_webhook	POST to a webhook.
notify_discord	Send a Discord message.
loop	Iterate over a collection.
wait_event	Pause until an external event arrives.
llm_classify	Classify input with an LLM.
imap_ack	Acknowledge an IMAP message.
app	Invoke a deployed App.
connector	Run a marketplace connector node.

Upstream node results flow to a node via SC_NODE_INPUTS; a trigger payload via SC_TRIGGER_CONTEXT. See the build-your-first-workflow tutorial to author one in the visual builder.