Canvas Flow Literal Runs
A flow:literal node holds a Flow definition. Running the node starts a run of that Flow.
Prerequisites
Canvas must be enabled for the Space, Flow runs from a Canvas must be enabled for the Space, and the caller must be a Space admin. Otherwise the run request returns NOT_FOUND. See Canvas Access.
Starting a Run
A run takes:
Parameter | Required | Description |
|---|---|---|
| Required | Canvas to read the head snapshot from |
| Required | Node to run. Must be a Flow literal ( |
| Optional | Map of handle key to |
The run returns the definition ID and the run.
The definition is always read from the Canvas head version, not from a caller-supplied version.
Definition
The pinned artifact must be a Flow definition with a name, nodes, edges, and input and output handles. Input and output handles are declared by the definition. They are not inferred, and a run cannot change them.
Server-Side Derivation
The Flow is checked and derived from its definition before it runs:
- The definition must declare exactly one
flow:triggernode. Zero or more than one returnsBAD_REQUESTwithFlow definition must declare exactly one trigger node. - Every node type must be runnable. Otherwise, the request returns
BAD_REQUESTwithFlow node type <type> is not runnable.
Inputs are resolved from artifacts in the Space. An input the Space does not own returns BAD_REQUEST with Input <key> artifact is unavailable.
Errors
Condition | Result |
|---|---|
Node missing from the head snapshot |
|
Node is not a Flow literal |
|
Pin does not resolve within the Space |
|
Wrong media type or unparseable definition |
|
Input artifact not in the Space |
|
Flow runs from a Canvas not enabled for the Space |
|
Definitions
Running the same artifact again reuses the same definition, so the same definitionId is returned.
After the literal is converted into a Flow resource, the definition is no longer tied to the Canvas. See Canvas Conversion.
Run Fields
Field | Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
| Map of handle key to artifact reference |
| Failure detail, or null |
| Timestamp |
| Timestamp or null |
| Timestamp or null |
| Timestamp or null |
Run Compatibility
Compatible runs are found by exactly one of definitionId or definitionArtifactHash. Runs are matched on that identifier alone and returned newest first, by creation time and then by ID. The latest compatible run is the first one returned, or none if no run matches.
Compatibility is identity of the hydrated definition or its artifact hash. Lineage is never compatibility.
Compatible-run lookups require Canvas access and the Space admin role, the same as the rest of Canvas.