Update Structure

Update the nodes and edges of an assistant graph

PUT /api/v1/assistant-graphs/{graph_id}/structure

cURL

curl -X PUT https://api.burki.dev/api/v1/assistant-graphs/1/structure \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {
        "assistant_id": 1,
        "node_type": "entry",
        "position": {"x": 0, "y": 0}
      },
      {
        "assistant_id": 2,
        "node_type": "standard",
        "position": {"x": 250, "y": -150}
      },
      {
        "assistant_id": 3,
        "node_type": "standard",
        "position": {"x": 250, "y": 150}
      },
      {
        "assistant_id": 4,
        "node_type": "escalation",
        "position": {"x": 500, "y": 0}
      }
    ],
    "edges": [
      {
        "from_node_id": 0,
        "to_node_id": 1,
        "condition_type": "intent",
        "intent_pattern": "sales,purchase,buy,pricing",
        "priority": 1,
        "handoff_sentence": "Connecting 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": "Let me transfer you to support."
      },
      {
        "from_node_id": 1,
        "to_node_id": 3,
        "condition_type": "natural_language",
        "natural_language_trigger": "Customer requests to speak with a human or manager",
        "priority": 1,
        "handoff_sentence": "I will connect you with a human agent."
      },
      {
        "from_node_id": 2,
        "to_node_id": 3,
        "condition_type": "mathematical",
        "mathematical_expression": "call_duration > 600",
        "priority": 2,
        "handoff_sentence": "Let me get a specialist to help you."
      }
    ]
  }'

Response

{
  "id": 1,
  "organization_id": 1,
  "name": "Customer Service Router",
  "description": "Routes customers to the appropriate department",
  "is_active": true,
  "configuration": {},
  "nodes": [
    {
      "id": 201,
      "graph_id": 1,
      "assistant_id": 1,
      "node_type": "entry",
      "position": {"x": 0, "y": 0},
      "configuration": {},
      "created_at": "2025-01-19T16:00:00Z",
      "assistant_name": "Receptionist",
      "assistant_description": "Greets callers"
    },
    {
      "id": 202,
      "graph_id": 1,
      "assistant_id": 2,
      "node_type": "standard",
      "position": {"x": 250, "y": -150},
      "configuration": {},
      "created_at": "2025-01-19T16:00:00Z",
      "assistant_name": "Sales Specialist",
      "assistant_description": "Handles sales"
    },
    {
      "id": 203,
      "graph_id": 1,
      "assistant_id": 3,
      "node_type": "standard",
      "position": {"x": 250, "y": 150},
      "configuration": {},
      "created_at": "2025-01-19T16:00:00Z",
      "assistant_name": "Support Agent",
      "assistant_description": "Handles support"
    },
    {
      "id": 204,
      "graph_id": 1,
      "assistant_id": 4,
      "node_type": "escalation",
      "position": {"x": 500, "y": 0},
      "configuration": {},
      "created_at": "2025-01-19T16:00:00Z",
      "assistant_name": "Human Agent Router",
      "assistant_description": "Routes to human agents"
    }
  ],
  "edges": [
    {
      "id": 301,
      "graph_id": 1,
      "from_node_id": 201,
      "to_node_id": 202,
      "condition_type": "intent",
      "intent_pattern": "sales,purchase,buy,pricing",
      "condition_logic": "AND",
      "priority": 1,
      "is_active": true,
      "handoff_sentence": "Connecting you with our sales team.",
      "created_at": "2025-01-19T16:00:00Z",
      "updated_at": "2025-01-19T16:00:00Z"
    },
    {
      "id": 302,
      "graph_id": 1,
      "from_node_id": 201,
      "to_node_id": 203,
      "condition_type": "intent",
      "intent_pattern": "support,help,issue,problem",
      "condition_logic": "AND",
      "priority": 1,
      "is_active": true,
      "handoff_sentence": "Let me transfer you to support.",
      "created_at": "2025-01-19T16:00:00Z",
      "updated_at": "2025-01-19T16:00:00Z"
    }
  ],
  "total_nodes": 4,
  "total_edges": 2,
  "created_at": "2025-01-19T10:00:00Z",
  "updated_at": "2025-01-19T16:00:00Z"
}

Update the complete structure (nodes and edges) of an assistant graph. This endpoint replaces all existing nodes and edges with the provided data, making it ideal for use with visual graph builders.

This endpoint replaces all existing nodes and edges. Any nodes or edges not included in the request will be deleted. Active conversation sessions for this graph will also be cleared.

Path Parameters

graph_id · integer · required

The unique identifier of the graph to update.

Request Body

nodes · array · required

Array of nodes to create. Replaces all existing nodes.

Show Node properties

assistant_id · integer · required

ID of the assistant for this node.

node_type · string · default: "assistant"

Type of node: entry, standard, exit, escalation

position · object

Position in the visual graph builder.

Show Position properties

x · number

X coordinate

y · number

Y coordinate

configuration · object

Node-specific configuration.

edges · array · required

Array of edges to create. Replaces all existing edges.

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 · default: "natural_language"

Type of condition: intent, natural_language, mathematical, state_variable

intent_pattern · string

Comma-separated intent keywords.

natural_language_trigger · string

Natural language condition description.

mathematical_expression · string

Mathematical expression.

state_variable_condition · object

State variable condition configuration.

condition_logic · string · default: "AND"

Logic for combining conditions: AND or OR

priority · integer · default: "0"

Priority for evaluation (lower = higher priority).

handoff_sentence · string

Message spoken during transition.

description · string

Human-readable description.

Response

Returns the updated graph with all new nodes and edges.

cURL

curl -X PUT https://api.burki.dev/api/v1/assistant-graphs/1/structure \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {
        "assistant_id": 1,
        "node_type": "entry",
        "position": {"x": 0, "y": 0}
      },
      {
        "assistant_id": 2,
        "node_type": "standard",
        "position": {"x": 250, "y": -150}
      },
      {
        "assistant_id": 3,
        "node_type": "standard",
        "position": {"x": 250, "y": 150}
      },
      {
        "assistant_id": 4,
        "node_type": "escalation",
        "position": {"x": 500, "y": 0}
      }
    ],
    "edges": [
      {
        "from_node_id": 0,
        "to_node_id": 1,
        "condition_type": "intent",
        "intent_pattern": "sales,purchase,buy,pricing",
        "priority": 1,
        "handoff_sentence": "Connecting 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": "Let me transfer you to support."
      },
      {
        "from_node_id": 1,
        "to_node_id": 3,
        "condition_type": "natural_language",
        "natural_language_trigger": "Customer requests to speak with a human or manager",
        "priority": 1,
        "handoff_sentence": "I will connect you with a human agent."
      },
      {
        "from_node_id": 2,
        "to_node_id": 3,
        "condition_type": "mathematical",
        "mathematical_expression": "call_duration > 600",
        "priority": 2,
        "handoff_sentence": "Let me get a specialist to help you."
      }
    ]
  }'

Response

{
  "id": 1,
  "organization_id": 1,
  "name": "Customer Service Router",
  "description": "Routes customers to the appropriate department",
  "is_active": true,
  "configuration": {},
  "nodes": [
    {
      "id": 201,
      "graph_id": 1,
      "assistant_id": 1,
      "node_type": "entry",
      "position": {"x": 0, "y": 0},
      "configuration": {},
      "created_at": "2025-01-19T16:00:00Z",
      "assistant_name": "Receptionist",
      "assistant_description": "Greets callers"
    },
    {
      "id": 202,
      "graph_id": 1,
      "assistant_id": 2,
      "node_type": "standard",
      "position": {"x": 250, "y": -150},
      "configuration": {},
      "created_at": "2025-01-19T16:00:00Z",
      "assistant_name": "Sales Specialist",
      "assistant_description": "Handles sales"
    },
    {
      "id": 203,
      "graph_id": 1,
      "assistant_id": 3,
      "node_type": "standard",
      "position": {"x": 250, "y": 150},
      "configuration": {},
      "created_at": "2025-01-19T16:00:00Z",
      "assistant_name": "Support Agent",
      "assistant_description": "Handles support"
    },
    {
      "id": 204,
      "graph_id": 1,
      "assistant_id": 4,
      "node_type": "escalation",
      "position": {"x": 500, "y": 0},
      "configuration": {},
      "created_at": "2025-01-19T16:00:00Z",
      "assistant_name": "Human Agent Router",
      "assistant_description": "Routes to human agents"
    }
  ],
  "edges": [
    {
      "id": 301,
      "graph_id": 1,
      "from_node_id": 201,
      "to_node_id": 202,
      "condition_type": "intent",
      "intent_pattern": "sales,purchase,buy,pricing",
      "condition_logic": "AND",
      "priority": 1,
      "is_active": true,
      "handoff_sentence": "Connecting you with our sales team.",
      "created_at": "2025-01-19T16:00:00Z",
      "updated_at": "2025-01-19T16:00:00Z"
    },
    {
      "id": 302,
      "graph_id": 1,
      "from_node_id": 201,
      "to_node_id": 203,
      "condition_type": "intent",
      "intent_pattern": "support,help,issue,problem",
      "condition_logic": "AND",
      "priority": 1,
      "is_active": true,
      "handoff_sentence": "Let me transfer you to support.",
      "created_at": "2025-01-19T16:00:00Z",
      "updated_at": "2025-01-19T16:00:00Z"
    }
  ],
  "total_nodes": 4,
  "total_edges": 2,
  "created_at": "2025-01-19T10:00:00Z",
  "updated_at": "2025-01-19T16:00:00Z"
}

Error Responses

Status Code	Description
400	Invalid request - nodes or edges array missing
401	Unauthorized - Invalid or missing API key
404	Graph not found in your organization
500	Server error updating structure

Important Notes

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

Session Cleanup: Updating the graph structure invalidates existing conversation sessions. All active sessions for this graph will be cleared to prevent routing errors with outdated node references.

Visual Graph Builder: This endpoint is designed to work seamlessly with visual graph builders. Simply serialize your canvas state (nodes with positions and edges with connections) and send it to this endpoint.