Trillet AI logo

Create Node Flow

Create a node flow: a graph plus its companion call flow and agent.

POSThttps://api.trillet.ai/v2/api/node-graphs

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-idstringrequired

Workspace identifier for the API.

Request Body

All fields are optional.

namestring

The flow's name. Defaults to Untitled node flow. The companion call flow gets the same name.

descriptionstring

A description of the flow.

templatestring

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

startNodeIdstring

The first node. Send it whenever you send nodes, because it is not guessed.

nodesarray

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

edgesarray

The graph's edges. See Edges.

variablesarray

Declared call variables. See Graph fields.

globalsobject

persona, guardrails, knowledgeBases and interrupts. Knowledge bases must belong to your workspace.

routerobject

Router settings.

dataSourcesarray

Stored as sent.

llmModelstring

Partner 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

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

_idstring

The graph ID. Use it in every /v2/api/node-graphs/{id} route.

workspaceIdstring

The workspace that owns the graph.

namestring

The flow's name.

descriptionstring

The flow's description.

statusstring

draft on create. Becomes active when published and archived when archived.

startNodeIdstring

The first node.

variablesarray

The declared variables.

globalsobject

persona, guardrails, knowledgeBases and interrupts.

routerobject

Router settings, with defaults filled in.

nodesarray

The nodes, with defaults such as onError and maxTurns filled in.

edgesarray

The edges.

hasDraftboolean

false on create.

publishedVersionnumber

0 until the first publish.

createdAtstring

When the graph was created.

The document also carries server-owned fields such as draftData, compiled, versions, stats and updatedAt.

From a template
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"
  }'
With your own graph
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" }
    ]
  }'
201 Created
{
  "_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"
}
400 Unknown template
{ "code": "NODE_GRAPH_TEMPLATE_NOT_FOUND" }

Last updated on