Testing & the trigger URL

Every flow is a live HTTP endpoint the moment it has a Start node. This page covers the trigger-URL bar, testing a run right inside the editor, tracing over the raw API, and the static checks that catch a broken flow before you ever call it.

The trigger URL

Along the top of the flow canvas is the trigger bar. It shows the public URL your flow answers at:

https://<your-host>/api/run/<project>/<flow-name>

The path is built from your project and the flow file's name, so the URL changes if you rename the file. The bar also shows a chip for each HTTP method the flow answers — one per Start node — and a copy button that puts the full URL on your clipboard.

Call it with any HTTP client. The method must match a Start node, or you get a 404:

curl -X POST https://your-host/api/run/acme/new-order \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@acme.com","amount":42}'

The request's path segments, query string, headers, and JSON body are validated against the Start node's schema and handed to the flow as its starting inputs. If validation fails you get a 400 listing what was wrong; a run error gives a 500 — and, for an authorized caller (see the tracing note below), that response names the failing node. An anonymous caller of a public flow gets a generic 500 with no node id.

NOTE

The endpoint is rate limited per client IP (60 requests per minute) and sends permissive CORS headers, so you can call it from a browser front-end as well as from a server.

Test a run in the editor

You don't need a terminal to exercise a flow. The trigger bar has a green Test run ▶ button that opens a run inspector — fill in the inputs, run it, and see exactly what happened, node by node.

Enter any query string, headers (JSON, for a flow that needs auth), and a request body (JSON, for POST/PUT/PATCH), then click Run. The result comes back in three tabs:

• Trace — every node in the order it ran, with a status dot (green ok, amber for an author-handled error, red for an unhandled failure), the port it took, iteration count, and its duration. Click any step to expand the value that node produced, and to highlight it on the canvas.
• Data — every variable the run produced (start.*, response.*, your Set/Template variables, …). This is the ground truth later nodes read, so it's where you confirm why a value came out the way it did.
• Response — the composed HTTP body the flow actually returned.

After a run, the canvas paints each node's outcome: a ✓/×/! corner badge and a coloured ring — green for success, amber for a handled error, red for a failure — with never-reached nodes dimmed. One glance shows how far the run got and where it broke. The badges clear when you edit the graph.

NOTE

The inspector's trace and produced values are only shown to a signed-in project member — the editor sends your session with the request. An anonymous caller of a public flow never receives them. See tracing over the API for the underlying mechanism.

Tracing a run with ?_trace=1

To see exactly which nodes ran, in what order, and how long each took, add ?_trace=1 to the URL:

curl "https://your-host/api/run/acme/new-order?_trace=1"

With the flag on, the response body includes a _trace array and the same data is echoed in an X-Flow-Trace response header. Each trace entry records the node, the port it chose, whether it succeeded, its duration in milliseconds, and — for a failed node — the error message.

NOTE

The _trace array and the X-Flow-Trace header are only returned to an authorized caller: a signed-in project member (as the editor's Test-run inspector is), a caller who passed the flow's Basic/Bearer credentials, or any caller when FLOW_TRACE=1 is set. An anonymous caller of a public (auth:none) flow gets a generic 500 and no _trace — even with ?_trace=1 on the URL.

_trace is the quickest way to answer "which branch did my If take?" or "which node is slow?" without opening the run history.

TIP

A self-hosted deployment can turn tracing on globally by setting FLOW_TRACE=1, so every response carries the header without needing the query flag.

Static validation

You don't have to call the endpoint to catch a broken flow. As you edit, FlowRunner validates the graph and shows the result in the trigger bar — a green Wiring OK chip, or a count of issues you can hover to read. Three problems are surfaced:

Check	Level	Meaning
No Start node	Error	The flow has no Start, so it can't be triggered at all.
No End node	Warning	Nothing shapes a response, so the flow never returns a proper result.
Unreachable node	Warning	A node isn't connected back to any Start, so it will never run.

Reachability is checked by walking outward from every Start node along the connections; anything the walk never touches is flagged as dead. Fixing these before you deploy means the first real call behaves the way you expect.

WARNING

Only No Start node is a hard error — the flow genuinely cannot run. The two warnings still let the endpoint respond, but almost always mean the flow isn't finished: wire an End node, and connect any stray nodes.

See also

• The flow canvas
• Run history
• Error handling
• HTTP triggers