Flow Nodes

← Back to API Reference

Flow nodes define a multi-step conversation as a finite state machine. Each node has its own persona, task, transition functions, and tools. The pipeline enters the node marked is_initial: true and follows function calls to move between nodes.

Prerequisite: Flow nodes belong to an agent. Create the agent first via POST /api/agents.

---

Contents

• How flows work
• List nodes
• Save entire flow
• Create single node
• Update node
• Delete node
• Field reference

---

How Flows Work

1. The initial node (is_initial: true) loads when the call connects.
2. The LLM follows task_messages at each node.
3. When the LLM calls one of the functions, the pipeline transitions to the next_node_key node.
4. Terminal nodes (is_terminal: true) get end_call automatically — no explicit function needed to end the call.
5. pre_actions fire on node entry (before the LLM speaks). Use these for data lookups that should be available immediately.
6. post_actions fire on node exit (after the LLM calls a transition function).

---

GET /api/agents/{agent_id}/flow

List all flow nodes for an agent, ordered by position.

---

PUT /api/agents/{agent_id}/flow

Bulk replace the entire flow. Deletes all existing nodes first, then creates the new set. This is what the visual flow editor calls when saving the canvas.

Request: Array of node objects (see field reference below).

Response: Array of created FlowNodeResponse objects.

Example:

[
  {
    "node_key": "greeting",
    "is_initial": true,
    "is_terminal": false,
    "position": 0,
    "role_messages": [
      { "role": "system", "content": "You are a friendly receptionist for Acme Corp." }
    ],
    "task_messages": [
      { "role": "system", "content": "Greet the caller and ask whether they need sales or support." }
    ],
    "functions": [
      {
        "name": "go_to_sales",
        "description": "Caller wants to buy or learn about pricing",
        "properties": {},
        "required": [],
        "next_node_key": "sales"
      },
      {
        "name": "go_to_support",
        "description": "Caller has a technical issue or account question",
        "properties": {},
        "required": [],
        "next_node_key": "support"
      }
    ],
    "tool_ids": [],
    "builtin_tools": ["end_call"],
    "pre_actions": [],
    "post_actions": [],
    "position_xy": { "x": 100, "y": 200 }
  },
  {
    "node_key": "sales",
    "is_initial": false,
    "is_terminal": true,
    "position": 1,
    "role_messages": [
      { "role": "system", "content": "You are an enthusiastic sales rep." }
    ],
    "task_messages": [
      { "role": "system", "content": "Help the caller understand the product and pricing. Book a demo if they're interested." }
    ],
    "functions": [],
    "tool_ids": ["uuid-of-book-demo-tool"],
    "builtin_tools": ["end_call"],
    "pre_actions": [],
    "post_actions": [],
    "position_xy": { "x": 400, "y": 100 }
  }
]

---

POST /api/agents/{agent_id}/flow

Create a single flow node. Useful for programmatically building flows one node at a time.

---

PATCH /api/agents/{agent_id}/flow/{node_id}

Update a single flow node. All fields are optional — send only what you want to change.

---

DELETE /api/agents/{agent_id}/flow/{node_id}

Delete a single flow node.

---

Field Reference

Node fields

Field	Type	Required	Description
node_key	string	Yes	Unique ID within this flow. Referenced by next_node_key in transitions.
is_initial	bool	—	Starting node. Exactly one required per flow.
is_terminal	bool	—	Ending node. end_call is added automatically.
position	int	—	Display order (0 = first).
role_messages	list	—	System messages defining the agent's persona at this node.
task_messages	list	—	System messages defining what the agent must accomplish.
functions	list	—	Transition functions (see below).
tool_ids	list	—	UUIDs of webhook tools available at this node. See Tools.
builtin_tools	list	—	Platform tools: ["end_call"]. Recommended on every non-terminal node.
pre_actions	list	—	Tools that fire automatically on node entry, before the LLM speaks.
post_actions	list	—	Tools that fire automatically on node exit, after a transition is called.
position_xy	object	—	{ "x": number, "y": number } canvas coordinates for the visual editor.

functions item fields

Field	Description
name	Function name the LLM calls to trigger the transition
description	Tells the LLM when to call this function — be specific
next_node_key	node_key of the destination node
properties	JSON Schema properties for arguments the LLM must pass (can be {})
required	List of required argument names

role_messages / task_messages item fields

{ "role": "system", "content": "You are..." }

Both accept the standard OpenAI message format. role is typically "system".