Update Flow

PUT/api/v1/ai-agents/{id}/flow

Replaces the agent's whole draft flow. Customers are not affected until you Publish.

Because this is a full replace, send every node and edge. To change one prompt, Get Flow first, edit it, and send everything back. Builder-only settings (integration tools, layout) are kept for nodes whose id and type are unchanged.

Takes about 4 seconds.

Flow rules. Exactly one startingPoint, and it must connect to another node. Node and edge IDs must be unique, and every edge must point at existing nodes. Also follow the builder's wiring rules, which the API does not check: a humanAgentNode may only be reached from a conditionNode; a conditionNode has exactly one outgoing edge and never leads to another conditionNode; an agentNode never connects directly to a knowledgeBaseNode. Typical shape: startingPoint → agentNode → conditionNode → humanAgentNode.

Request

Authorization

Bearer Token

Provide your API token in the Authorization header. See Authentication to issue one.

Example:Authorization: Bearer ********************

Path Params

idstringrequired
AI agent ID.

Example:6ad97ee52845b4f2c8daca55

Body Paramsapplication/json

modelstringrequired
A slug from AI Agent → List Models that is not legacy. Anything else is 422.
nodesarray[object]required
Every node of the flow (up to 200).
Child attributes
- idstringrequired
  Your own unique ID, e.g. agent-main. Keep it stable across saves: settings added in the dashboard are kept per node ID.
- typestringrequired
  startingPoint entry (exactly one per flow) · agentNode the AI that replies, instruction is its prompt · conditionNode a decision, instruction is the condition in plain language · humanAgentNode hands the chat to human agents (may only follow a conditionNode) · knowledgeBaseNode answers from knowledgeSourceIds. endingPoint, waitNode and replyCheckerNode are best configured in the dashboard builder.
  
  Allowed values:"startingPoint", "agentNode", "conditionNode", "humanAgentNode", "knowledgeBaseNode", "endingPoint", "waitNode", "replyCheckerNode"
- labelstringrequired
  Name shown in the dashboard builder.
- positionobjectoptional
  Canvas position. Optional; nodes are laid out left to right when omitted.
  Child attributes
  xnumberrequired
  ynumberrequired
- instructionstringoptional
  Plain text, newlines allowed. Prompt for agentNode, condition for conditionNode, handoff note for humanAgentNode. Use [contact name] for the customer's name.
- toolIdsarray[string]optional
  IDs of tools already set up in this workspace (copy them from an existing flow). Unknown IDs are rejected with 422.
- knowledgeSourceIdsarray[string]optional
  Knowledge base source IDs already set up in this workspace.
- vectorStoreIdsarray[string]optional
  OpenAI vector store IDs (vs_...) attached in this workspace.
- correctionbooleanoptional
  Apply saved corrections.
- correctionGroupIdsarray[string]optional
  Limit corrections to these groups. Empty = all.
- waitSecondsintegeroptional
  waitNode only: how long to wait.
edgesarray[object]required
Every edge of the flow (up to 500).
Child attributes
- idstringrequired
  Unique edge ID.
- sourcestringrequired
  Node ID the edge leaves.
- targetstringrequired
  Node ID the edge enters.
- sourceHandlestring | nulloptional
  Reply-checker branch: replied or timeout. Otherwise omit.
- targetHandlestring | nulloptional

Responses

200

The saved draft flow.

requestIdstringrequired
Unique ID for this request. Quote it when reporting a problem.
dataobjectrequired
Child attributes
- idstringrequired
  Flow version ID.
- statusstringrequired
  Allowed values:"draft", "live"
- versionstringrequired
  draft, or the label given at publish.
- modelstringrequired
- savedAtstring | nulloptional
  ISO 8601.
- nodesarray[object]required
  Child attributes
  idstringrequired
  Your own unique ID, e.g. agent-main. Keep it stable across saves: settings added in the dashboard are kept per node ID.
  
  typestringrequired
  startingPoint entry (exactly one per flow) · agentNode the AI that replies, instruction is its prompt · conditionNode a decision, instruction is the condition in plain language · humanAgentNode hands the chat to human agents (may only follow a conditionNode) · knowledgeBaseNode answers from knowledgeSourceIds. endingPoint, waitNode and replyCheckerNode are best configured in the dashboard builder.
  
  Allowed values:"startingPoint", "agentNode", "conditionNode", "humanAgentNode", "knowledgeBaseNode", "endingPoint", "waitNode", "replyCheckerNode"
  labelstringrequired
  Name shown in the dashboard builder.
  
  positionobject | nulloptional
  Child attributes
  xnumberoptional
  ynumberoptional
  instructionstringrequired
  Plain text, newlines allowed. Prompt for agentNode, condition for conditionNode, handoff note for humanAgentNode. Use [contact name] for the customer's name.
  
  toolIdsarray[string]required
  IDs of tools already set up in this workspace (copy them from an existing flow). Unknown IDs are rejected with 422.
  
  toolsarray[object]required
  Names of the attached tools, read only. Send toolIds when saving.
  
  Child attributes
  idstringoptional
  namestring | nulloptional
  descriptionstring | nulloptional
  providerToolsarray[object]required
  Integration tools, read only. Attached in the dashboard and kept when you save, as long as the node id and type are unchanged.
  
  Child attributes
  idstring | nulloptional
  namestring | nulloptional
  knowledgeSourceIdsarray[string]required
  Knowledge base source IDs already set up in this workspace.
  
  vectorStoreIdsarray[string]required
  OpenAI vector store IDs (vs_...) attached in this workspace.
  
  correctionbooleanrequired
  Apply saved corrections.
  
  correctionGroupIdsarray[string]required
  Limit corrections to these groups. Empty = all.
  
  waitSecondsinteger | nulloptional
- edgesarray[object]required
  Child attributes
  idstringrequired
  Unique edge ID.
  
  sourcestringrequired
  Node ID the edge leaves.
  
  targetstringrequired
  Node ID the edge enters.
  
  sourceHandlestring | nulloptional
  Reply-checker branch: replied or timeout. Otherwise omit.
  
  targetHandlestring | nulloptional

400

Invalid body or parameters, e.g. an empty name, an unknown node type or a malformed ID.

messagestringrequired

401

API key missing, invalid, revoked or expired.

messagestringrequired

404

No AI agent with this ID in your workspace.

messagestringrequired

422

Flow rejected: problems lists graph errors, supportedModels is returned for an unknown or legacy model, and toolIds lists tools that are not in your workspace.

messagestringrequired

429

Rate limit reached. Retry after a short pause.

messagestringrequired

502

The AI agent service is temporarily unavailable. Retry shortly.

messagestringrequired

Request

curl -X PUT "https://apigw.klinkcx.com/api/v1/ai-agents/{id}/flow" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6-luna",
  "nodes": [
    {
      "id": "start",
      "type": "startingPoint",
      "label": "Start",
      "position": {
        "x": 0,
        "y": 0
      }
    },
    {
      "id": "agent-main",
      "type": "agentNode",
      "label": "Sales Assistant",
      "position": {
        "x": 320,
        "y": 0
      },
      "instruction": "You are the sales assistant for Example Co. Reply in the customer'\''s language.\n\nGreet [contact name] and ask how you can help.\nOpening hours: Mon-Fri 9:00-18:00."
    },
    {
      "id": "cond-human",
      "type": "conditionNode",
      "label": "Needs a human",
      "position": {
        "x": 640,
        "y": 0
      },
      "instruction": "The customer asks to talk to a person, wants to place an order, or complains. Otherwise, no."
    },
    {
      "id": "human",
      "type": "humanAgentNode",
      "label": "Sales team",
      "position": {
        "x": 960,
        "y": 0
      },
      "instruction": "Tell the customer a sales specialist will join shortly."
    }
  ],
  "edges": [
    {
      "id": "e1",
      "source": "start",
      "target": "agent-main"
    },
    {
      "id": "e2",
      "source": "agent-main",
      "target": "cond-human"
    },
    {
      "id": "e3",
      "source": "cond-human",
      "target": "human"
    }
  ]
}'

Response

{
  "requestId": "string",
  "data": {
    "id": "string",
    "status": "draft",
    "version": "string",
    "model": "string",
    "savedAt": "string",
    "nodes": [
      {
        "id": "string",
        "type": "startingPoint",
        "label": "string",
        "position": {
          "x": 0,
          "y": 0
        },
        "instruction": "string",
        "toolIds": [
          "string"
        ],
        "tools": [
          {
            "id": "string",
            "name": "string",
            "description": "string"
          }
        ],
        "providerTools": [
          {
            "id": "string",
            "name": "string"
          }
        ],
        "knowledgeSourceIds": [
          "string"
        ],
        "vectorStoreIds": [
          "string"
        ],
        "correction": true,
        "correctionGroupIds": [
          "string"
        ],
        "waitSeconds": 0
      }
    ],
    "edges": [
      {
        "id": "string",
        "source": "string",
        "target": "string",
        "sourceHandle": "string",
        "targetHandle": "string"
      }
    ]
  }
}