Workflow definitions
The JSON shape of a workflow — nodes, uses refs, and the derived interface.
A workflow is a JSON document describing a graph of nodes. The Studio editor
produces this format when you publish; the SDK builder produces it in code; and
you can also write it by hand. Either way, the same definition can be sent
inline to POST /v1/runs or published and run by reference.
Shape
{
"version": 2,
"nodes": [
{
"id": "photo",
"uses": "input",
"outputType": "IMAGE",
"label": "Source photo"
},
{
"id": "style",
"uses": "input",
"outputType": "TEXT",
"inputs": { "default": "isometric" }
},
{
"id": "gen",
"uses": "rd-fast",
"inputs": {
"prompt": "${style.value}",
"init": "${photo.value}",
"seed": 7
}
},
{
"id": "result",
"uses": "output",
"inputs": { "value": "${gen.image}" }
}
]
}| Field | Description |
|---|---|
version | Schema version. Always 2. |
nodes | The graph. Every node is { id, uses, inputs } (plus outputType/label on interface nodes). |
There are no top-level input/output blocks: a workflow's public interface is
derived from its input and output nodes. An input node's id is the API
parameter name callers provide at run time; label is display-only; an input
without a default is required.
The uses field
uses identifies what a node runs — never where it runs:
| Form | Meaning |
|---|---|
rd-fast, llm | A platform node (curated model or operator) |
input, output | Interface nodes — declare the workflow's API |
const | A fixed inline value (outputType + inputs.value) |
acme/sprite-pack@1 | A published workflow mounted as a node (reserved — coming soon) |
The ref grammar reserves version selectors (@latest, @1, @1.2.0 — same
notation as workflow references), but node
versions don't resolve yet: today only the implicit/explicit @latest runs,
and a pinned selector fails at run time.
outputType on input/const nodes is a connector id: IMAGE, TEXT,
AUDIO, VIDEO, FLOAT, INT, BOOLEAN, EMBEDDING, FILE, or
STRUCTURED.
Value references
Node inputs accept either literal JSON values (strings, numbers, booleans,
null, objects, arrays) or ${nodeId.port} references — a ref is only
recognized as the full string value, never inside a nested structure:
| Reference | Meaning |
|---|---|
${photo.value} | The value port of the node photo (input and const nodes expose their value on value) |
${gen.image} | Output port image of node gen |
References are how edges are expressed — there is no separate edge list, and there is exactly one reference namespace: every ref points at a node's port.
Authoring options
- Studio editor — design visually, then publish a version and run it by reference from code.
- SDK builder — construct the graph programmatically with validation; see Building workflows.
- Raw JSON / YAML — write the definition directly; the CLI runs YAML files with the same shape.