The Flow API allows you to test flows without saving them to a project and monitor the status of running flows.
Test a flow
This endpoint executes the flow immediately. Make sure your flow definition is valid before testing.
Request body
The flow definition object
Timeout duration for the flow (e.g., “5m”)
Array of store configurations for data storage
Default data well configuration
Array of data well configurations for edges
Array of node objects defining the flow structure
Unique identifier for the node
Node definition reference (format: “publisher/name”)
Array of input edge connections
Array of output edge connections
Array of flag configurations for the node
Array of node definition objects
Container image to use for execution
Array of input edge definitions
Array of output edge definitions
Array of flag definitions
Command definition for the node
Resource tier for execution
Maximum retry attempts on failure
Response
Unique identifier for the flow run
Current status of the flow run. Possible values:
STOPPED - Flow has stoppedWAITING - Flow is waiting for inputRUNNING - Flow is currently executingCOMPLETE - Flow completed successfullyERROR - Flow encountered an error
Map of node IDs to their current stateShow NodeState properties
Node execution status: IDLE, READY, RUNNING, RETRYING, COMPLETE, or ERROR
Array of log records from the node execution
Error message if the node failed
Maximum number of retry attempts
Map of edge IDs to artifact locations
Array of presigned URLs waiting for data upload
ISO 8601 timestamp of when the flow started
Example request
curl -X POST http://localhost:1234/api/v1/flow/test \
-H "Content-Type: application/json" \
-d '{
"Flow": {
"Name": "image-resize",
"Nodes": [
{
"ID": "resize-1",
"Uses": "pupload/resize",
"Inputs": [{"Name": "image", "Edge": "input-image"}],
"Outputs": [{"Name": "resized", "Edge": "output-image"}],
"Flags": [{"Name": "width", "Value": "800"}]
}
]
},
"NodeDefs": [
{
"Publisher": "pupload",
"Name": "resize",
"Image": "pupload/resize:latest",
"Tier": "c-small",
"MaxAttempts": 3
}
]
}'
Example response
{
"ID": "run_abc123xyz",
"Status": "RUNNING",
"NodeState": {
"resize-1": {
"Status": "RUNNING",
"Logs": [],
"Error": "",
"Attempt": 1,
"MaxAttempts": 3
}
},
"Artifacts": {},
"WaitingURLs": [],
"StartedAt": "2026-03-03T10:30:00Z"
}
Get flow run status
GET /api/v1/flow/status/{flowRunID}
Path parameters
The unique identifier of the flow run
Response
Returns the same FlowRun object structure as the test flow endpoint (see above).
Example request
curl http://localhost:1234/api/v1/flow/status/run_abc123xyz
Example response
{
"ID": "run_abc123xyz",
"Status": "COMPLETE",
"NodeState": {
"resize-1": {
"Status": "COMPLETE",
"Logs": [
{
"timestamp": "2026-03-03T10:30:05Z",
"message": "Image resized successfully"
}
],
"Error": "",
"Attempt": 1,
"MaxAttempts": 3
}
},
"Artifacts": {
"output-image": {
"StoreName": "default",
"ObjectName": "abc123.jpg",
"EdgeName": "output-image"
}
},
"WaitingURLs": [],
"StartedAt": "2026-03-03T10:30:00Z"
}
Error responses
"Flow run does not exist."