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
`canvasId`	Required	Canvas to read the head snapshot from
`nodeId`	Required	Node to run. Must be a Flow literal (`flow:literal`)
`inputs`	Optional	Map of handle key to `{ artifactId, contentHash }`. Defaults 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:trigger node. Zero or more than one returns BAD_REQUEST with Flow definition must declare exactly one trigger node.
Every node type must be runnable. Otherwise, the request returns BAD_REQUEST with Flow 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	`NOT_FOUND` — `Canvas node not found`
Node is not a Flow literal	`BAD_REQUEST` — `Canvas node is not a Flow literal`
Pin does not resolve within the Space	`BAD_REQUEST` — `Definition artifact pin is invalid`
Wrong media type or unparseable definition	`BAD_REQUEST` — `Invalid Flow definition artifact`
Input artifact not in the Space	`BAD_REQUEST` — `Input <key> artifact is unavailable`
Flow runs from a Canvas not enabled for the Space	`NOT_FOUND`

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
`runId`	`string`
`spaceId`	`string`
`definitionId`	`string`
`artifactHash`	`string`
`status`	`created` \| `running` \| `succeeded` \| `failed` \| `cancelled`
`inputs`	Map of handle key to artifact reference
`failure`	Failure detail, or null
`createdAt`	Timestamp
`startedAt`	Timestamp or null
`finishedAt`	Timestamp or null
`cancelledAt`	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.

How to Check Whether Canvas Is Available in a Space

This guide shows you how to tell whether Canvas is available in a Space, and what to do when it is not.