Create Graph

Create a new assistant graph with nodes and edges

POST /api/v1/assistant-graphs

cURL

curl -X POST https://api.burki.dev/api/v1/assistant-graphs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Service Router",
    "description": "Routes customers to the appropriate department",
    "nodes": [
      {
        "assistant_id": 1,
        "node_type": "entry",
        "position": {"x": 0, "y": 0}
      },
      {
        "assistant_id": 2,
        "node_type": "standard",
        "position": {"x": 200, "y": -100}
      },
      {
        "assistant_id": 3,
        "node_type": "standard",
        "position": {"x": 200, "y": 100}
      }
    ],
    "edges": [
      {
        "from_node_id": 0,
        "to_node_id": 1,
        "condition_type": "intent",
        "intent_pattern": "sales,purchase,buy",
        "priority": 1,
        "handoff_sentence": "Let me connect you with our sales team."
      },
      {
        "from_node_id": 0,
        "to_node_id": 2,
        "condition_type": "intent",
        "intent_pattern": "support,help,issue,problem",
        "priority": 1,
        "handoff_sentence": "I will transfer you to our support team."
      }
    ]
  }'

Response

{
  "id": 1,
  "organization_id": 1,
  "name": "Customer Service Router",
  "description": "Routes customers to the appropriate department",
  "is_active": true,
  "configuration": {},
  "nodes": [
    {
      "id": 101,
      "graph_id": 1,
      "assistant_id": 1,
      "node_type": "entry",
      "position": {"x": 0, "y": 0},
      "configuration": {},
      "created_at": "2025-01-19T10:00:00Z",
      "assistant_name": "Receptionist",
      "assistant_description": "Greets callers and routes to departments"
    },
    {
      "id": 102,
      "graph_id": 1,
      "assistant_id": 2,
      "node_type": "standard",
      "position": {"x": 200, "y": -100},
      "configuration": {},
      "created_at": "2025-01-19T10:00:00Z",
      "assistant_name": "Sales Specialist",
      "assistant_description": "Handles sales inquiries"
    },
    {
      "id": 103,
      "graph_id": 1,
      "assistant_id": 3,
      "node_type": "standard",
      "position": {"x": 200, "y": 100},
      "configuration": {},
      "created_at": "2025-01-19T10:00:00Z",
      "assistant_name": "Support Agent",
      "assistant_description": "Handles support requests"
    }
  ],
  "edges": [
    {
      "id": 201,
      "graph_id": 1,
      "from_node_id": 101,
      "to_node_id": 102,
      "condition_type": "intent",
      "intent_pattern": "sales,purchase,buy",
      "natural_language_trigger": null,
      "mathematical_expression": null,
      "state_variable_condition": null,
      "condition_logic": "AND",
      "priority": 1,
      "is_active": true,
      "handoff_sentence": "Let me connect you with our sales team.",
      "description": null,
      "created_at": "2025-01-19T10:00:00Z",
      "updated_at": "2025-01-19T10:00:00Z"
    },
    {
      "id": 202,
      "graph_id": 1,
      "from_node_id": 101,
      "to_node_id": 103,
      "condition_type": "intent",
      "intent_pattern": "support,help,issue,problem",
      "natural_language_trigger": null,
      "mathematical_expression": null,
      "state_variable_condition": null,
      "condition_logic": "AND",
      "priority": 1,
      "is_active": true,
      "handoff_sentence": "I will transfer you to our support team.",
      "description": null,
      "created_at": "2025-01-19T10:00:00Z",
      "updated_at": "2025-01-19T10:00:00Z"
    }
  ],
  "total_nodes": 3,
  "total_edges": 2,
  "created_at": "2025-01-19T10:00:00Z",
  "updated_at": "2025-01-19T10:00:00Z"
}

Create a new multi-assistant orchestration graph that defines how conversations flow between different specialized assistants based on various conditions.

Request Body

name · string · required

Name of the assistant graph. Must be unique within your organization.

description · string

Human-readable description of the graph’s purpose.

configuration · object

Optional graph-level configuration settings.

nodes · array

Array of nodes to create with the graph.

Show Node properties

assistant_id · integer · required

ID of the assistant for this node. Must belong to your organization.

node_type · string · default: "standard"

Type of node. One of: entry, standard, exit, escalation

position · object

Position in the visual graph builder UI.

Show Position properties

x · number

X coordinate

y · number

Y coordinate

configuration · object

Node-specific configuration.

Show Configuration properties

knowledge_base_files · array

Array of document IDs for this node

custom_tools · array

Array of tool IDs for this node

max_session_duration · integer

Max session duration in minutes

custom_settings · object

Node-specific settings

edges · array

Array of edges (transitions) to create with the graph.

Show Edge properties

from_node_id · integer · required

Index of the source node in the nodes array (0-based).

to_node_id · integer · required

Index of the target node in the nodes array (0-based).

condition_type · string · required

Type of condition. One of: intent, natural_language, mathematical, state_variable

intent_pattern · string

Comma-separated intent keywords for intent-based transitions.

natural_language_trigger · string

Natural language description for LLM-evaluated transitions.

mathematical_expression · string

Mathematical expression for expression-based transitions.

state_variable_condition · object

State variable condition for variable-based transitions.

condition_logic · string · default: "AND"

Logic for combining multiple conditions: AND or OR

priority · integer · default: "0"

Priority for condition evaluation. Lower numbers = higher priority.

handoff_sentence · string

Custom message spoken during the transition.

description · string

Human-readable description of the edge.

Response

id · integer

Unique identifier for the graph.

organization_id · integer

Organization that owns this graph.

name · string

Name of the graph.

description · string

Description of the graph.

is_active · boolean

Whether the graph is active.

configuration · object

Graph configuration settings.

nodes · array

Array of created nodes with their IDs.

edges · array

Array of created edges with their IDs.

total_nodes · integer

Total number of nodes in the graph.

total_edges · integer

Total number of edges in the graph.

created_at · string

ISO 8601 timestamp of creation.

updated_at · string

ISO 8601 timestamp of last update.

cURL

curl -X POST https://api.burki.dev/api/v1/assistant-graphs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Service Router",
    "description": "Routes customers to the appropriate department",
    "nodes": [
      {
        "assistant_id": 1,
        "node_type": "entry",
        "position": {"x": 0, "y": 0}
      },
      {
        "assistant_id": 2,
        "node_type": "standard",
        "position": {"x": 200, "y": -100}
      },
      {
        "assistant_id": 3,
        "node_type": "standard",
        "position": {"x": 200, "y": 100}
      }
    ],
    "edges": [
      {
        "from_node_id": 0,
        "to_node_id": 1,
        "condition_type": "intent",
        "intent_pattern": "sales,purchase,buy",
        "priority": 1,
        "handoff_sentence": "Let me connect you with our sales team."
      },
      {
        "from_node_id": 0,
        "to_node_id": 2,
        "condition_type": "intent",
        "intent_pattern": "support,help,issue,problem",
        "priority": 1,
        "handoff_sentence": "I will transfer you to our support team."
      }
    ]
  }'

Response

{
  "id": 1,
  "organization_id": 1,
  "name": "Customer Service Router",
  "description": "Routes customers to the appropriate department",
  "is_active": true,
  "configuration": {},
  "nodes": [
    {
      "id": 101,
      "graph_id": 1,
      "assistant_id": 1,
      "node_type": "entry",
      "position": {"x": 0, "y": 0},
      "configuration": {},
      "created_at": "2025-01-19T10:00:00Z",
      "assistant_name": "Receptionist",
      "assistant_description": "Greets callers and routes to departments"
    },
    {
      "id": 102,
      "graph_id": 1,
      "assistant_id": 2,
      "node_type": "standard",
      "position": {"x": 200, "y": -100},
      "configuration": {},
      "created_at": "2025-01-19T10:00:00Z",
      "assistant_name": "Sales Specialist",
      "assistant_description": "Handles sales inquiries"
    },
    {
      "id": 103,
      "graph_id": 1,
      "assistant_id": 3,
      "node_type": "standard",
      "position": {"x": 200, "y": 100},
      "configuration": {},
      "created_at": "2025-01-19T10:00:00Z",
      "assistant_name": "Support Agent",
      "assistant_description": "Handles support requests"
    }
  ],
  "edges": [
    {
      "id": 201,
      "graph_id": 1,
      "from_node_id": 101,
      "to_node_id": 102,
      "condition_type": "intent",
      "intent_pattern": "sales,purchase,buy",
      "natural_language_trigger": null,
      "mathematical_expression": null,
      "state_variable_condition": null,
      "condition_logic": "AND",
      "priority": 1,
      "is_active": true,
      "handoff_sentence": "Let me connect you with our sales team.",
      "description": null,
      "created_at": "2025-01-19T10:00:00Z",
      "updated_at": "2025-01-19T10:00:00Z"
    },
    {
      "id": 202,
      "graph_id": 1,
      "from_node_id": 101,
      "to_node_id": 103,
      "condition_type": "intent",
      "intent_pattern": "support,help,issue,problem",
      "natural_language_trigger": null,
      "mathematical_expression": null,
      "state_variable_condition": null,
      "condition_logic": "AND",
      "priority": 1,
      "is_active": true,
      "handoff_sentence": "I will transfer you to our support team.",
      "description": null,
      "created_at": "2025-01-19T10:00:00Z",
      "updated_at": "2025-01-19T10:00:00Z"
    }
  ],
  "total_nodes": 3,
  "total_edges": 2,
  "created_at": "2025-01-19T10:00:00Z",
  "updated_at": "2025-01-19T10:00:00Z"
}

Error Responses

Status Code	Description
400	Invalid request body or assistant not found
401	Unauthorized - Invalid or missing API key
500	Server error creating the graph

When creating edges, from_node_id and to_node_id refer to the index of the node in the nodes array (0-based), not the database ID. The actual node IDs are assigned after creation.