architect-edit-workflows
An agent's workflow (its nodes and edges) lives inside the agent config. Over REST you read it from GET /v1/convai/agents/$AGENT_ID?branch_id=$BRANCH_ID (the workflow object) and write whole-config changes with PATCH /v1/convai/agents/$AGENT_ID?branch_id=$BRANCH_ID. There is NO granular per-node/per-edge endpoint from the API. If the user needs interactive node-by-node editing on a canvas, that is only in the web app; say so plainly and either make the whole-config edit here or point them there. All calls use xi-api-key: $API_KEY.
Workflow writes are error-prone. Go slow, change one thing at a time, and read the current graph before every write.
1. Read the current graph first, always
GET /v1/convai/agents/$AGENT_ID?branch_id=$BRANCH_ID and read the workflow object. Nodes and edges are keyed maps (not arrays): every node has a type, a position, and an edge_order; the graph always contains start_node. You need existing node ids to connect, update, or delete, and you need to see which pairs already have an edge. Also GET /v1/convai/tools for the real tool ids: expression edges and tool nodes reference tool ids, and a guessed id fails validation.
2. Make one change at a time
Take the workflow you read, apply a single change, and PATCH the whole workflow back. Do not hand-build a partial workflow from memory and do not drop nodes, edges, or nested config you did not mean to change: omissions are treated as deletions and cause schema_mismatch. After each successful write, re-read the config to confirm the change landed before the next one.