Trillet AI logo

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:

  1. The graph (the nodes, edges and variables), which you edit with the routes on these pages.
  2. 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:

IDWhat it isUsed with
Graph _idThe graph documentEvery /v2/api/node-graphs/{id} route. Also the nodeGraphId of a subflow node.
Call flow _idThe 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, so pathway._id is 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 when promptType is nodes). List Call Flows returns it for every flow in the workspace.

What lives where

You want to changeWhereHow
Conversation steps, routing, variables, persona, guardrails, router, knowledge bases on the graphThe graphThe routes on these pages
Voice, model, phone numbers, transfers, webhooks, post-call analysis, greeting, call limits and other settingsThe companion call flowUpdate Call Flow with PUT /v1/api/call-flows/{id}
Agent name, voice and model fieldsThe agentUpdate 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:

RouteWritesValidatesEffect on calls
Update Node Flow PUTThe live fields, and also merges the same fields into an open draftNoNone until you publish. The compiled version that calls use only changes on publish.
Save Draft PATCHThe draft onlyNeverNone
Validate POSTNothingYes, on the effective graphNone
Publish POSTPromotes the effective graph to live, clears the draftYes, blocks on errorsNew 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

1
Create the flow

Create Node Flow, optionally from a template or with your own nodes and edges.

2
Read both IDs

Get Node Flow and note graph._id and pathway._id.

3
Build the graph

Update Node Flow to set the whole graph from your code, or Save Draft while you iterate.

4
Configure the call flow

PUT /v1/api/call-flows/{pathway._id} for voice, model, phone numbers, transfers, webhooks and post-call analysis.

5
Validate

Validate and fix every error problem.

6
Publish

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.

namestring

The flow's name. Required on the graph; defaults to Untitled node flow on create. Publishing copies it to the companion call flow's name.

descriptionstring

A description of the flow.

startNodeIdstring

The nodeId of the first node. Must exist and cannot be an end node.

variablesarray

The call state the graph reads and writes. Declare a variable here before a node refers to it.

globalsobject

Content that applies to the whole call.

routerobject

Settings for the model that picks the next edge.

nodesarray

The steps. See Nodes.

edgesarray

The transitions. See Edges.

dataSourcesarray

Stored as sent and not checked by validation. No node type documented here uses it.

Nodes

Every node has these fields:

nodeIdstringrequired

Unique within the graph. Edges and startNodeId refer to it.

typestringrequired

One of the types below.

namestring

A display name. Validation warns when it is missing.

configobject

The per-type settings below.

stagestring

Editor grouping label. No effect on calls.

canvasPositionobject

{ x, y } position in the editor. No effect on calls.

behaviourobject

Optional 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.

onErrorstring

fallback (default), end or transfer. What happens when the node fails and no error edge handles it.

maxTurnsnumber

Default 8. How many caller turns a conversation or wait node may use before the flow forces its fallback edge. Must be at least 1.

timeoutMsnumber

Optional node timeout in milliseconds.

typeWhat it doesconfig
conversationThe 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)
saySays fixed text.text (required), interruptible
decisionRoutes only on its condition edges, with no config.none
classifyThe router picks one option.question, options: array of { handle, description }, at least 2, unique handles
toolRuns one action.toolName (required, from the list below), arguments, resultVariable (a declared variable), retry (attempts 0 to 3, backoffMs 0 to 5000)
endEnds the call.message, disposition, messageMode (instruction, the default, writes a closing line from message; verbatim says it exactly)
waitListens without speaking and collects fields.requiredFields (required, non-empty), prompt
subflowHands the call to another node flow.nodeGraphId (required), returnAfter (come back when it finishes)
codeRuns your JavaScript over the call variables.code (required), referenceVariables, arguments, resultVariable
parallelRuns several actions at once and joins.tools: at least 2 of { toolName, arguments, resultVariable }, joinPolicy (all_success or any_success)
ivrNavigates 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

idstringrequired

Unique edge ID.

sourcestringrequired

The nodeId the edge leaves.

targetstringrequired

The nodeId the edge enters.

kindstring

Who 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).

sourceHandlestring

Which 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.

labelstring

Required on intent edges: describe the caller's situation, for example wants a different date.

conditionobject

Required 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).

prioritynumber

Default 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.

CodeSeverityMeaning
NO_NODESerrorThe graph has no nodes.
NODE_ID_MISSING, DUPLICATE_NODE_IDerrorA node has no nodeId, or two nodes share one.
NO_START_NODE, START_NODE_MISSING, START_NODE_TERMINALerrorstartNodeId is missing, points at no node, or points at an end node.
UNKNOWN_NODE_TYPEerrortype is not one of the types above.
VARIABLE_KEY_MISSING, DUPLICATE_VARIABLE_KEY, ENUM_WITHOUT_VALUESerrorA 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_UNDECLAREDerrorA node or {{_variable.x}} placeholder uses a variable that is not in variables.
CONVERSATION_WITHOUT_OBJECTIVE, SAY_WITHOUT_TEXT, WAIT_WITHOUT_FIELDS, CODE_EMPTYerrorA required config field is empty.
DECISION_WITHOUT_CONDITIONSerrorA decision node has no condition edge.
CLASSIFY_WITHOUT_OPTIONS, CLASSIFY_OPTION_HANDLE_MISSING, CLASSIFY_DUPLICATE_HANDLEerrorA 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_INVALIDerrorInvalid tool, parallel or abilities configuration.
SUBFLOW_WITHOUT_TARGET, SUBFLOW_HANDOFF_HAS_OUTGOINGerrorA subflow has no nodeGraphId, or has outgoing edges without returnAfter.
END_MESSAGE_MODE_INVALID, MAX_TURNS_INVALID, TEMPERATURE_OUT_OF_RANGE, ROUTER_CONFIDENCE_RANGEerrorA value is outside its allowed range.
SKIP_USER_RESPONSE_WRONG_TYPE, SKIP_USER_RESPONSE_WITH_FIELDSerrorbehaviour.skipUserResponse on a node that cannot use it.
EDGE_ID_MISSING, UNKNOWN_EDGE_SOURCE, UNKNOWN_EDGE_TARGETerrorAn edge has no id or points at a node that does not exist.
TERMINAL_HAS_OUTGOINGerrorAn edge leaves an end node.
HANDLE_MISSING, UNKNOWN_HANDLE, HANDLE_NOT_ALLOWED, HANDLE_MULTIPLE_EDGES, HANDLE_NOT_CONNECTEDerrorsourceHandle 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_LABELerrorA condition edge has no conditions, or an intent edge has no label.
NO_OUTGOING, MULTIPLE_FALLBACK, MISSING_FALLBACKerrorA node has no way out, has more than one fallback edge, or has condition or intent edges and no fallback.
INTERRUPT_TARGET_MISSINGerrorAn interrupt's targetNodeId does not exist.
IVR_* (for example IVR_NODE_HAS_INCOMING, IVR_NODE_DUPLICATE, IVR_SEQUENCE_REQUIRED, IVR_EDGE_HANDLE_INVALID)errorAn 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 otherswarningWorth fixing but does not block publishing.
ABILITY_NOT_CONNECTEDwarningReturned 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 pathPermissionWhat it does
POST /v2/api/node-graphspathway:createCreate Node Flow: create a graph and its companion call flow.
GET /v2/api/node-graphspathway:viewList Node Flows: paginated summaries, without the graph body.
GET /v2/api/node-graphs/{id}pathway:viewGet Node Flow: the graph, the effective graph and the companion call flow.
PUT /v2/api/node-graphs/{id}pathway:editUpdate Node Flow: write the live fields without validating, merging into any open draft.
PATCH /v2/api/node-graphs/{id}/draftpathway:editSave Draft: autosave a draft. Never validates.
POST /v2/api/node-graphs/{id}/validatepathway:viewValidate: check the effective graph, or one you send.
POST /v2/api/node-graphs/{id}/publishpathway:editPublish: validate, compile and make the graph live.
GET /v2/api/node-graphs/templatespathway:viewLists 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}/draftpathway:editDiscards the draft. Returns { graph, effective }.
GET /v2/api/node-graphs/{id}/versionspathway:viewLists 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}/restorepathway:editCopies 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}/duplicatepathway:createCopies 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}/archivepathway:editSets 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:deleteDeletes 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}/simulatepathway:viewLess 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-codepathway:editLess 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}/runspathway:viewLess 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:viewLess commonly used. One run with its full event trace: { run }. 404 with NODE_GRAPH_RUN_NOT_FOUND.
POST /v2/api/node-graphs/{id}/apply-livepathway:editLess 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