Flow builder

Sellable product

This capability is granted by an API key scoped to the `` product (product face). See the product reference below.

A conversational flow ENGINE as a shared capability. Author a flow as a JSON graph (nodes + edges); POST /v1/flows stores it (versioned); POST /v1/flows/{id}/execute advances one turn (walk the graph from the current node, applying the user input — emit message outputs, follow each routing decision, record tool/handoff actions — until it lands on a collect node that waits for input or a terminal). Edges route deterministically (offline) or by an LLM branch classifier for natural-language conditions (advisory to the default edge — fail-closed). POST /v1/flows/{id}/validate does static graph analysis.

• Group: Governance & platform
• Contract: contracts/flow-builder/v1/openapi.yaml
• Public base: https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
• Auth: a product API key (vgk_…) issued from the console — Authorization: Bearer vgk_…
• Product face (customer-keyed):
  • https://api.vagarylabs.com/product/v1/flows

Endpoints

Method	Path	Summary
POST	/v1/flows	Create a flow from a JSON graph (validated; a graph with errors is rejected)
GET	/v1/flows	List an org's flows (heads only — no definitions)
GET	/v1/flows/{flow_id}	Fetch a flow (head, or a specific immutable version)
PATCH	/v1/flows/{flow_id}	Versioned upsert — append a new immutable version
POST	/v1/flows/{flow_id}/execute	Advance the flow one turn
POST	/v1/flows/{flow_id}/validate	Static graph validation (an inline definition, or the stored flow)
GET	/v1/flows/{flow_id}/versions	The version ledger (newest first), each row tagged is_draft / is_published — the console's version-history and rollback picker.
POST	/v1/flows/{flow_id}/publish	Move the publish pointer — the draft→production gate
DELETE	/v1/flows/{flow_id}/publish	Clear the publish pointer — the flow returns to draft-only
GET	/v1/flows/{flow_id}/diff	Structural diff between two versions of a flow
POST	/v1/flows/{flow_id}/duplicate	Clone a flow into a NEW artifact (new flow_id) at version 1, unpublished
GET	/health	liveness + store/classifier readiness
GET	/metrics	Prometheus exposition (fleet observability SDK — fail-open)

Schemas

Node

A typed flow node. type selects behavior (aliases accepted). message/say emits text; collect/input emits prompt and captures the next user turn into variable; branch/condition is a pure routing node; tool/action emits an action (tool name + args); autonomous/agent delegates to a bounded agentic loop (a goal + a bounded tool-set) then follows the edge; handoff + end are terminal. The DECLARATIVE lifecycle/config types (global/trigger/webhook/qa) carry configuration + graph-cardinality rules and round-trip through the store, but are NOT part of the one-turn walk (consumed out-of-band). Any node may declare an extraction schema (a per-node LLM variable-extraction pass), a graph_constraints override, and tools/documents/mcp bindings.

Field	Type	Description
id	string
type	string
text	string	message/end utterance ({{ var }} interpolated)
prompt	string	collect prompt ({{ var }} interpolated); global: the persona/system prompt
variable	string	collect: the variable the answer is captured into
cast	string	collect: coerce the answer (default string)
tool	string	tool: the action name emitted to the caller
args	object	tool: structured args ({{ var }} interpolated recursively)
output_var	string	tool: the variable the caller writes the tool result into; autonomous: the var the agent outcome is merged into (default agent_result)
goal	string	autonomous: the agent's objective ({{ var }} interpolated) — delegated to a bounded agentic loop
tools	array	autonomous: the bounded function-calling tool-set; any node: a declarative tool binding
tool_dispatch	object	autonomous: name -> {url, method?, headers?} customer HTTP endpoint each tool dispatches to (I5)
documents	array	declarative KB binding — knowledge-base document ids (threaded into an autonomous spec)
mcp	object	declarative MCP binding (object or list) — MCP server/tool filter (threaded into an autonomous spec)
add_global_prompt	boolean	autonomous: when not false (default true), the flow's global-node prompt is prepended to this node's system
extraction	object	per-node variable-extraction schema (dograh-shape). When a collect node captures an answer and an extractor is available, the typed variables are merged into the bag.
graph_constraints	object	per-node override of the canonical-type GraphConstraints default (enforced in /validate)
max_iterations	integer	autonomous: loop-cap bound (exit condition)
turn_budget	number	autonomous: wall-clock budget in seconds (exit condition)
context_vars	array	autonomous: variable names handed to the agent as prior flow state
target	string	handoff: the destination the caller routes to
reason	string	handoff: a human reason ({{ var }} interpolated)
message	string	end/handoff final utterance ({{ var }} interpolated)

Edge

A directed edge carrying the routing decision. DETERMINISTIC = {variable, op, value} (offline, no LLM). NATURAL-LANGUAGE = {nl: "<intent description>"} (resolved by the provider-gateway branch classifier). DEFAULT = no condition or {default: true} (the fallback). From a node, deterministic edges are tried first (declared order), then NL edges (one classifier call), then the default edge.

Field	Type	Description
source	string	the node this edge leaves (must be a declared node)
target	string	the node this edge routes to
variable	string	deterministic: the variable compared (or 'user_input')
op	string	deterministic comparison operator
value	object	deterministic: the expected value (string
nl	string	natural-language condition — classified via provider-gateway
condition	string	alias for nl (dograh-compatible edge label)
label	string	optional human label (also a classifier hint)
default	boolean	mark the fallback edge taken when no condition matched

FlowDefinition

the flow graph — nodes + edges + an optional explicit start node id.

Field	Type	Description
flow_id	string
name	string
start	string	the entry node id; defaults to a node id 'start' else the first node
nodes	array
edges	array

FlowRequest

Field	Type	Description
organization_id	string	product-tier end-customer tenant (I6). OPTIONAL — derived from the verified identity token; when supplied must MATCH the token claim (mismatch = 403).
flow_id	string	idempotent key; generated when omitted
name	string
definition	object

FlowHead

Field	Type	Description
flow_id	string
name	string
latest_version	integer
created_at	number
updated_at	number

StoredFlow

Field	Type	Description
flow_id	string
name	string
version	integer
latest_version	integer
definition	object
validation	object
created_at	number
updated_at	number

ExecuteRequest

Field	Type	Description
session_id	string	a correlation label — the engine stores no session (stateless)
current_node	string	the node to resume at (the prior turn's next_node); null = start
user_input	string	the user's utterance this turn
variables	object	the running variable bag (carried back each turn)

Action

a side-effect the caller executes or records (a tool call, an autonomous-agent delegation, or a handoff). An autonomous action carries the delegated bounded-loop outcome (when the flow ran it in-process) OR the run spec (goal + tools + tool_dispatch) for out-of-band dispatch.

Field	Type	Description
type	string
tool	string	tool action: the action name
args	object	tool action: interpolated args
output_var	object
goal	string	autonomous action: the agent goal (interpolated)
status	object	autonomous action: goal_reached
iterations	object	autonomous action: loop iterations spent
tool_calls	object	autonomous action: tool calls the agent executed
tools	array	autonomous action (out-of-band): the tool-set to run the loop with
tool_dispatch	object	autonomous action (out-of-band): the tool dispatch endpoints
target	object	handoff: destination
reason	object

---

Generated by scripts/gen-capability-docs.py from contracts/flow-builder/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page.