Node Flows Overview
Build a call flow as a graph of nodes and edges through the API: how node flows relate to call flows, draft versus live, and every route.
A node flow is a call flow whose conversation is a graph instead of one prompt. The graph is made of nodes (a step the agent performs, such as talking, asking a question, routing, running an action or ending the call) joined by edges (the transitions between them). Only one node is active at a time, and a small routing model decides which edge to take.
The routes below live under /v2/api/node-graphs. They use the same authentication as Call Flows: send x-api-key and x-workspace-id on every request (see Authentication). Partner API keys work too. Access follows the call flow permissions: pathway:view to read, validate and simulate, pathway:create to create and duplicate, pathway:edit to change, publish and archive, and pathway:delete to delete.
These routes are plain REST routes, not part of the OpenAPI reference. They are documented here as regular pages.
A node flow is a graph plus a call flow
Creating a node flow creates two things:
- The graph (the nodes, edges and variables), which you edit with the routes on these pages.
- A companion call flow with
promptType: "nodes",direction: "bidirectional"and its own agent (a default voice and model). The call flow is what makes the graph callable: it carries the agent, voice, model, phone numbers, transfers, webhooks, recording, post-call analysis and call history.
The graph and the call flow have different IDs:
| ID | What it is | Used with |
|---|---|---|
Graph _id | The graph document | Every /v2/api/node-graphs/{id} route. Also the nodeGraphId of a subflow node. |
Call flow _id | The companion call flow | /v1/api/call-flows/{id}, phone number assignment and starting calls. |
Getting from one ID to the other
- Graph to call flow: Get Node Flow returns the companion call flow in
pathway, sopathway._idis the call flow ID. Create Node Flow returns only the graph, so call Get Node Flow right after creating to read it. - Call flow to graph: Get Call Flow returns the flow's
nodeGraphId(set only whenpromptTypeisnodes). List Call Flows returns it for every flow in the workspace.
What lives where
| You want to change | Where | How |
|---|---|---|
| Conversation steps, routing, variables, persona, guardrails, router, knowledge bases on the graph | The graph | The routes on these pages |
| Voice, model, phone numbers, transfers, webhooks, post-call analysis, greeting, call limits and other settings | The companion call flow | Update Call Flow with PUT /v1/api/call-flows/{id} |
| Agent name, voice and model fields | The agent | Update Call Agent |
A prompt sent to Update Call Flow is saved but ignored on node flows: the published graph drives the call.
Draft versus live
A graph has live fields (what new calls run) and an optional draft (work in progress). Which route writes where matters:
| Route | Writes | Validates | Effect on calls |
|---|---|---|---|
Update Node Flow PUT | The live fields, and also merges the same fields into an open draft | No | None until you publish. The compiled version that calls use only changes on publish. |
Save Draft PATCH | The draft only | Never | None |
Validate POST | Nothing | Yes, on the effective graph | None |
Publish POST | Promotes the effective graph to live, clears the draft | Yes, blocks on errors | New calls use it immediately |
The effective graph is the draft merged over the live fields when a draft exists, otherwise the live fields. Get, Validate and Publish all work on the effective graph.
Calls run the published version. A node flow that has never been published cannot take calls.
Suggested workflow
Create Node Flow, optionally from a template or with your own nodes and edges.
Get Node Flow and note graph._id and pathway._id.
Update Node Flow to set the whole graph from your code, or Save Draft while you iterate.
PUT /v1/api/call-flows/{pathway._id} for voice, model, phone numbers, transfers, webhooks and post-call analysis.
Validate and fix every error problem.
Publish to make the graph live.
Graph fields
These are the fields you can write (name, description, startNodeId, variables, globals, router, nodes, edges, dataSources). Any other field on the graph is set by the server and ignored if you send it. Arrays and objects you send replace the stored value for that field as a whole.
namestringThe flow's name. Required on the graph; defaults to Untitled node flow on create. Publishing copies it to the companion call flow's name.
descriptionstringA description of the flow.
startNodeIdstringThe nodeId of the first node. Must exist and cannot be an end node.
variablesarrayThe call state the graph reads and writes. Declare a variable here before a node refers to it.
globalsobjectContent that applies to the whole call.
routerobjectSettings for the model that picks the next edge.
nodesarrayThe steps. See Nodes.
edgesarrayThe transitions. See Edges.
dataSourcesarrayStored as sent and not checked by validation. No node type documented here uses it.
Nodes
Every node has these fields:
nodeIdstringrequiredUnique within the graph. Edges and startNodeId refer to it.
typestringrequiredOne of the types below.
namestringA display name. Validation warns when it is missing.
configobjectThe per-type settings below.
stagestringEditor grouping label. No effect on calls.
canvasPositionobject{ x, y } position in the editor. No effect on calls.
behaviourobjectOptional per-node overrides: temperature (0 to 2), model (a different model for this node; validation warns because it discards the prompt cache for that turn), blockInterruptions, interruptionThreshold, responseEagerness, resumptionSpeed, reminderSeconds, reminderTimes, disableSilenceRepeat, skipUserResponse (speak and continue without waiting; conversation nodes without requiredFields only), overridesInterrupts and excludeFromHistory. A field you leave out uses the flow's setting.
onErrorstringfallback (default), end or transfer. What happens when the node fails and no error edge handles it.
maxTurnsnumberDefault 8. How many caller turns a conversation or wait node may use before the flow forces its fallback edge. Must be at least 1.
timeoutMsnumberOptional node timeout in milliseconds.
type | What it does | config |
|---|---|---|
conversation | The agent talks to the caller toward an objective. | objective (required), prompt, requiredFields (variable keys to collect), exitCriteria, allowedDigressions, skipIfSatisfied, clearFieldsOnReentry (true or a list of variable keys), confirmBeforeExit, knowledgeBases (IDs), abilities ([{ toolName }] the model may call during the node) |
say | Says fixed text. | text (required), interruptible |
decision | Routes only on its condition edges, with no config. | none |
classify | The router picks one option. | question, options: array of { handle, description }, at least 2, unique handles |
tool | Runs one action. | toolName (required, from the list below), arguments, resultVariable (a declared variable), retry (attempts 0 to 3, backoffMs 0 to 5000) |
end | Ends the call. | message, disposition, messageMode (instruction, the default, writes a closing line from message; verbatim says it exactly) |
wait | Listens without speaking and collects fields. | requiredFields (required, non-empty), prompt |
subflow | Hands the call to another node flow. | nodeGraphId (required), returnAfter (come back when it finishes) |
code | Runs your JavaScript over the call variables. | code (required), referenceVariables, arguments, resultVariable |
parallel | Runs several actions at once and joins. | tools: at least 2 of { toolName, arguments, resultVariable }, joinPolicy (all_success or any_success) |
ivr | Navigates a phone menu at pickup, before the graph starts. Entry only: no edges into it, and at most one per graph. | mode (sequence or auto), keySequence (up to 10 steps of 0-9*#, 1 to 32 characters each), priorityList, holdQueue (enabled, maxWaitSeconds 15 to 900), screeningAction (respond or hangup) |
tool and parallel actions can use these toolName values: realtime_api, execute_code_action, search_knowledge_base, transfer_call, end_call, get_time_for_timezone, next_available_callback_time, trigger_workflow, and the ServiceTitan actions lookup_servicetitan_customer, check_servicetitan_availability, create_servicetitan_booking_request, book_servicetitan_job, add_servicetitan_note, find_servicetitan_location, get_servicetitan_job_questions, create_servicetitan_job and update_servicetitan_job_summary. Prefer an end node over the end_call action: validation warns about end_call.
Edges
idstringrequiredUnique edge ID.
sourcestringrequiredThe nodeId the edge leaves.
targetstringrequiredThe nodeId the edge enters.
kindstringWho decides the edge: auto (default; always taken, no model call), condition (checked against call state, no model call), intent (the router reads label) or fallback (taken when nothing else matches or a limit is hit).
sourceHandlestringWhich output of the source node the edge leaves through. Required for classify (an option handle), tool, code and parallel (success or error) and subflow with returnAfter (returned or error). For ivr it is human, exhausted or voicemail. Not allowed on other node types. Each handle takes one edge.
labelstringRequired on intent edges: describe the caller's situation, for example wants a different date.
conditionobjectRequired on condition edges: { conditions: [...], error_message }. Each condition is { conditional_variable, operator, value, connector }. Conditions chain left to right with each condition's connector (AND by default, or OR), with no precedence.
operator is one of exists (default), not_empty, equals, not_equals, equals_ci, not_equals_ci, contains, not_contains, greater_than, less_than. equals is case-sensitive, the _ci versions are not, and contains is a case-insensitive substring test. conditional_variable and value accept placeholders such as {{_variable.x}}, {{_dynamic_variable.x}}, {{_response.x}}, {{_metadata.x}} and {{_time_context.currentDate}} (also currentTime, currentDay).
prioritynumberDefault 0. Lower runs first among condition edges out of one node.
Minimal valid graph
A start node, an end node and one edge. This passes validation with no problems, so it can be published as is:
{
"startNodeId": "start",
"nodes": [
{
"nodeId": "start",
"type": "conversation",
"name": "Greeting",
"config": {
"objective": "Greet the caller, say the business name, and ask how you can help today."
}
},
{
"nodeId": "done",
"type": "end",
"name": "End call",
"config": {
"message": "Thank the caller and end the call politely.",
"disposition": "completed"
}
}
],
"edges": [
{ "id": "e1", "source": "start", "target": "done", "kind": "auto" }
]
}
A flow created with no template and no nodes starts as just the start node above, with no edge. That is not publishable yet: a node that is not an end node needs at least one outgoing edge (NO_OUTGOING).
Validation problems
Validate and Publish return problems as { code, severity, nodeId?, edgeId?, params? }. An error blocks publishing and a warning does not. The codes are stable identifiers, not sentences.
| Code | Severity | Meaning |
|---|---|---|
NO_NODES | error | The graph has no nodes. |
NODE_ID_MISSING, DUPLICATE_NODE_ID | error | A node has no nodeId, or two nodes share one. |
NO_START_NODE, START_NODE_MISSING, START_NODE_TERMINAL | error | startNodeId is missing, points at no node, or points at an end node. |
UNKNOWN_NODE_TYPE | error | type is not one of the types above. |
VARIABLE_KEY_MISSING, DUPLICATE_VARIABLE_KEY, ENUM_WITHOUT_VALUES | error | A variable has no key, repeats a key, or is an enum with no values. |
UNDECLARED_VARIABLE, REQUIRED_FIELD_UNDECLARED, CLEAR_FIELDS_UNDECLARED, TOOL_RESULT_VARIABLE_UNDECLARED | error | A node or {{_variable.x}} placeholder uses a variable that is not in variables. |
CONVERSATION_WITHOUT_OBJECTIVE, SAY_WITHOUT_TEXT, WAIT_WITHOUT_FIELDS, CODE_EMPTY | error | A required config field is empty. |
DECISION_WITHOUT_CONDITIONS | error | A decision node has no condition edge. |
CLASSIFY_WITHOUT_OPTIONS, CLASSIFY_OPTION_HANDLE_MISSING, CLASSIFY_DUPLICATE_HANDLE | error | A classify node has fewer than 2 options, an option without a handle, or a repeated handle. |
TOOL_WITHOUT_NAME, TOOL_NOT_ALLOWED, ABILITY_NOT_ALLOWED, PARALLEL_NEEDS_TOOLS, PARALLEL_JOIN_POLICY_INVALID | error | Invalid tool, parallel or abilities configuration. |
SUBFLOW_WITHOUT_TARGET, SUBFLOW_HANDOFF_HAS_OUTGOING | error | A subflow has no nodeGraphId, or has outgoing edges without returnAfter. |
END_MESSAGE_MODE_INVALID, MAX_TURNS_INVALID, TEMPERATURE_OUT_OF_RANGE, ROUTER_CONFIDENCE_RANGE | error | A value is outside its allowed range. |
SKIP_USER_RESPONSE_WRONG_TYPE, SKIP_USER_RESPONSE_WITH_FIELDS | error | behaviour.skipUserResponse on a node that cannot use it. |
EDGE_ID_MISSING, UNKNOWN_EDGE_SOURCE, UNKNOWN_EDGE_TARGET | error | An edge has no id or points at a node that does not exist. |
TERMINAL_HAS_OUTGOING | error | An edge leaves an end node. |
HANDLE_MISSING, UNKNOWN_HANDLE, HANDLE_NOT_ALLOWED, HANDLE_MULTIPLE_EDGES, HANDLE_NOT_CONNECTED | error | sourceHandle rules were broken, or a declared output has no edge. A tool or code error output may stay unconnected. |
CONDITION_EDGE_WITHOUT_CONDITION, INTENT_EDGE_WITHOUT_LABEL | error | A condition edge has no conditions, or an intent edge has no label. |
NO_OUTGOING, MULTIPLE_FALLBACK, MISSING_FALLBACK | error | A node has no way out, has more than one fallback edge, or has condition or intent edges and no fallback. |
INTERRUPT_TARGET_MISSING | error | An interrupt's targetNodeId does not exist. |
IVR_* (for example IVR_NODE_HAS_INCOMING, IVR_NODE_DUPLICATE, IVR_SEQUENCE_REQUIRED, IVR_EDGE_HANDLE_INVALID) | error | An ivr node breaks the rules in the table above. |
NODE_NAME_MISSING, UNREACHABLE_NODE, NO_END_NODE, DUPLICATE_EDGE, END_WITHOUT_MESSAGE, CLASSIFY_NO_FALLBACK, COLLECTION_WITHOUT_FALLBACK, TOOL_ERROR_PATH_UNWIRED, END_CALL_TOOL_NODE, PER_NODE_MODEL_COSTS_PROMPT_CACHE, INTERRUPT_WITHOUT_PATTERNS, NON_SPEAKING_CYCLE, CHAIN_DEPTH_NEAR_LIMIT, RETRY_INVALID and others | warning | Worth fixing but does not block publishing. |
ABILITY_NOT_CONNECTED | warning | Returned by Validate only: a conversation ability needs an integration the call flow has not connected. |
Error responses
Errors from these routes are JSON with a code, and sometimes problems and params:
{ "code": "NODE_GRAPH_NOT_FOUND" }
A missing x-workspace-id returns 400 with { "code": "WORKSPACE_ID_REQUIRED" }. A graph ID that does not exist in your workspace returns 404 with NODE_GRAPH_NOT_FOUND. A malformed graph ID is not checked up front and returns 500. Unexpected failures return 500 with a route-specific code such as NODE_GRAPH_UPDATE_FAILED. Authentication and permission failures come from the shared API layer, as on every other endpoint.
All routes
Base URL: https://api.trillet.ai. Every route needs x-api-key and x-workspace-id.
| Method and path | Permission | What it does |
|---|---|---|
POST /v2/api/node-graphs | pathway:create | Create Node Flow: create a graph and its companion call flow. |
GET /v2/api/node-graphs | pathway:view | List Node Flows: paginated summaries, without the graph body. |
GET /v2/api/node-graphs/{id} | pathway:view | Get Node Flow: the graph, the effective graph and the companion call flow. |
PUT /v2/api/node-graphs/{id} | pathway:edit | Update Node Flow: write the live fields without validating, merging into any open draft. |
PATCH /v2/api/node-graphs/{id}/draft | pathway:edit | Save Draft: autosave a draft. Never validates. |
POST /v2/api/node-graphs/{id}/validate | pathway:view | Validate: check the effective graph, or one you send. |
POST /v2/api/node-graphs/{id}/publish | pathway:edit | Publish: validate, compile and make the graph live. |
GET /v2/api/node-graphs/templates | pathway:view | Lists the starter templates: { templates: [{ key, name, description, category, nodeCount }] }. The keys are receptionist, appointment_booking and lead_qualification. Pass a key as template to Create. |
DELETE /v2/api/node-graphs/{id}/draft | pathway:edit | Discards the draft. Returns { graph, effective }. |
GET /v2/api/node-graphs/{id}/versions | pathway:view | Lists saved versions, newest first, as metadata only: { publishedVersion, publishedAt, versions: [{ _id, version, note, createdBy, createdAt }] }. Publishing saves the outgoing version automatically, and the last 20 are kept. |
POST /v2/api/node-graphs/{id}/versions/{version}/restore | pathway:edit | Copies a saved version into the draft and returns { restoredVersion, hasDraft }. The live graph does not change until you publish. 404 with VERSION_NOT_FOUND if there is no such version. |
POST /v2/api/node-graphs/{id}/duplicate | pathway:create | Copies the graph's live fields into a new unpublished graph named <name> (copy). Returns 201 with the new graph. The draft and version history are not copied. The call flow for the copy is created the first time you get or publish it. |
POST /v2/api/node-graphs/{id}/archive | pathway:edit | Sets the graph to archived, archives the companion call flow and removes the graph's code runtime. Returns the graph. An archived flow is restored from the dashboard, and cannot be published while archived. |
DELETE /v2/api/node-graphs/{id} | pathway:delete | Deletes the graph and its companion call flow. Returns { "deleted": true }. 409 with NODE_GRAPH_IN_USE (and params.pathwayCount) if another active call flow still points at the graph. |
POST /v2/api/node-graphs/{id}/simulate | pathway:view | Less commonly used. Walks the effective graph through scripted caller turns with the models mocked, without placing a call. Optional body: turns (array), routerScript (array), initialState (object), timeContext (object), direction (inbound or outbound). A wrong type returns 400 with INVALID_SIMULATE_BODY and a problem string. |
POST /v2/api/node-graphs/{id}/test-code | pathway:edit | Less commonly used. Runs one code node's JavaScript against values you supply. Body: code (string, required), variables (object), timeoutMs (default 5000, capped at 10000), secretAliases (object). Returns 200 with { ok, result, elapsedMs }, or { ok: false, error, detail, elapsedMs } when the script fails. 400 with CODE_REQUIRED if code is missing. |
GET /v2/api/node-graphs/{id}/runs | pathway:view | Less commonly used. Recent run records for the graph, newest first, without the event trace: { runs }. Query limit (default 25, maximum 100). |
GET /v2/api/node-graphs/{id}/runs/{runId} | pathway:view | Less commonly used. One run with its full event trace: { run }. 404 with NODE_GRAPH_RUN_NOT_FOUND. |
POST /v2/api/node-graphs/{id}/apply-live | pathway:edit | Less commonly used. Applies one change to the live graph and publishes it as a new version in one step, keeping unpublished draft edits. Body: { graph: { ...fields } }. 400 with NODE_GRAPH_INVALID and problems if the result is not publishable, 409 with NODE_GRAPH_DRAFT_CONFLICT and params.conflicts if the draft changed the same items. |
Last updated on