Create Node Flow
Create a node flow: a graph plus its companion call flow and agent.
Creates the graph and, with it, a companion call flow (promptType: "nodes") with a default agent. The response is the graph only. To get the call flow's ID, call Get Node Flow and read pathway._id. See the overview for how the two relate.
The graph is created as a draft and is not live. Nothing in the request body is validated, so you can create an incomplete graph and fix it later. Use Validate and Publish when you are ready.
Headers
x-workspace-idstringrequiredWorkspace identifier for the API.
Request Body
All fields are optional.
namestringThe flow's name. Defaults to Untitled node flow. The companion call flow gets the same name.
descriptionstringA description of the flow.
templatestringStart from a template. Any graph field you also send replaces that field of the template. An unknown key returns 400 with NODE_GRAPH_TEMPLATE_NOT_FOUND.
startNodeIdstringThe first node. Send it whenever you send nodes, because it is not guessed.
nodesarrayThe graph's nodes. If you send no template and no nodes (or an empty array), the flow starts with a single start node. See Nodes.
edgesarrayThe graph's edges. See Edges.
variablesarrayDeclared call variables. See Graph fields.
globalsobjectpersona, guardrails, knowledgeBases and interrupts. Knowledge bases must belong to your workspace.
routerobjectRouter settings.
dataSourcesarrayStored as sent.
llmModelstringPartner API keys only: the model for the flow's agent, checked like an agent create. Ignored for other keys.
Other fields in the body are ignored.
Errors
| Status | Body | When |
|---|---|---|
400 | {"code": "WORKSPACE_ID_REQUIRED"} | No x-workspace-id |
400 | {"code": "NODE_GRAPH_TEMPLATE_NOT_FOUND"} | template is not a known key |
400 | {"code": "KNOWLEDGE_BASE_NOT_IN_WORKSPACE", "params": {"knowledgeBaseIds": [...]}} | A knowledge base in globals or a node is not in your workspace |
400 | {"code", "field", "message"} | Partner keys only: llmModel is not allowed |
502 | {"code": "NODE_FLOW_AGENT_CREATE_FAILED"} | The agent or call flow could not be created. The graph is removed, so nothing is left behind. |
500 | {"code": "NODE_GRAPH_CREATE_FAILED"} | Unexpected server error, including a graph the database cannot store |
Response Fields
The response status is 201. The body is the graph document.
_idstringThe graph ID. Use it in every /v2/api/node-graphs/{id} route.
workspaceIdstringThe workspace that owns the graph.
namestringThe flow's name.
descriptionstringThe flow's description.
statusstringdraft on create. Becomes active when published and archived when archived.
startNodeIdstringThe first node.
variablesarrayThe declared variables.
globalsobjectpersona, guardrails, knowledgeBases and interrupts.
routerobjectRouter settings, with defaults filled in.
nodesarrayThe nodes, with defaults such as onError and maxTurns filled in.
edgesarrayThe edges.
hasDraftbooleanfalse on create.
publishedVersionnumber0 until the first publish.
createdAtstringWhen the graph was created.
The document also carries server-owned fields such as draftData, compiled, versions, stats and updatedAt.
curl -X POST "https://api.trillet.ai/v2/api/node-graphs" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-workspace-id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Front desk",
"template": "receptionist"
}'curl -X POST "https://api.trillet.ai/v2/api/node-graphs" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-workspace-id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Front desk",
"startNodeId": "start",
"nodes": [
{
"nodeId": "start",
"type": "conversation",
"name": "Greeting",
"config": { "objective": "Greet the caller 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" }
]
}'{
"_id": "a1a1a1a1a1a1a1a1a1a1a1a1",
"workspaceId": "c1c1c1c1c1c1c1c1c1c1c1c1",
"name": "Front desk",
"description": "",
"status": "draft",
"startNodeId": "start",
"variables": [],
"globals": { "persona": "", "guardrails": "", "knowledgeBases": [], "interrupts": [] },
"router": {
"model": "",
"maxCandidates": 8,
"historyTurns": 4,
"confidenceFloor": 0.5,
"sequential": false,
"speculative": false,
"timeoutMs": 2500
},
"nodes": [
{
"nodeId": "start",
"type": "conversation",
"name": "Greeting",
"config": { "objective": "Greet the caller and ask how you can help today." },
"onError": "fallback",
"maxTurns": 8
},
{
"nodeId": "done",
"type": "end",
"name": "End call",
"config": { "message": "Thank the caller and end the call politely.", "disposition": "completed" },
"onError": "fallback",
"maxTurns": 8
}
],
"edges": [
{ "id": "e1", "source": "start", "target": "done", "kind": "auto", "priority": 0 }
],
"dataSources": [],
"hasDraft": false,
"publishedVersion": 0,
"createdAt": "2025-01-03T11:00:00Z",
"updatedAt": "2025-01-03T11:00:00Z"
}{ "code": "NODE_GRAPH_TEMPLATE_NOT_FOUND" }Last updated on