Skip to main content
PATCH
/
agents
/
{id}
Update Agent
curl --request PATCH \
  --url https://eu-gcp-api.vg-stuff.com/v3/agents/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent": {
    "title": "<string>",
    "description": "<string>",
    "ownerID": "<string>",
    "theme": "<string>",
    "voiceConfig": {
      "transcriber": {
        "provider": "deepgram",
        "speechConfig": {
          "format": "<string>",
          "sampleRate": 123
        },
        "modelId": "<string>",
        "patienceFactor": 123,
        "language": "<string>",
        "randomOptions": "<unknown>",
        "internal": {
          "inputAudioStream": "<unknown>",
          "debug": true
        },
        "apiKey": "<string>",
        "platformSpecific": {
          "deepgram": {
            "keywords": [
              "<string>"
            ],
            "language": "<string>",
            "smart_format": true,
            "model": "<string>",
            "interim_results": true,
            "endpointing": 123,
            "no_delay": true
          },
          "assemblyai": {
            "modelId": "<string>"
          }
        },
        "utteranceThreshold": 123,
        "inputVoiceEnhancer": true
      },
      "speechGen": {
        "provider": "elevenlabs",
        "highAudioQuality": true,
        "modelId": "<string>",
        "voiceId": "<string>",
        "apiKey": "<string>",
        "region": "<string>",
        "backgroundNoise": "restaurant",
        "punctuationBreaks": [
          "<string>"
        ],
        "platformSpecific": {
          "elevenLabs": {
            "stability": 123,
            "similarity_boost": 123,
            "use_speaker_boost": true,
            "speed": 123,
            "style": 123
          },
          "playht": {
            "voiceId": "<string>"
          }
        },
        "backChannelling": true,
        "language": "<string>",
        "enableLongMessageBackchannelling": true,
        "backchannelMessages": [
          "<string>"
        ],
        "backchannelInterval": 123,
        "wordsReplacements": [
          {
            "word": "<string>",
            "replacement": "<string>"
          }
        ],
        "internal": {
          "inputTextStream": "<unknown>",
          "audioConfig": {
            "format": "<string>",
            "sampleRate": 123,
            "channels": 123
          },
          "emitOnComplete": true
        }
      },
      "config": {
        "recordAudio": true,
        "backgroundNoise": "restaurant",
        "enableWebCalling": true,
        "firstInputChunkUNIXMs": 123,
        "firstOutputChunkUNIXMs": 123
      }
    },
    "createdAtUNIX": 123,
    "disabled": true,
    "vectorDb": "<unknown>",
    "withRefresh": true,
    "agentPlatform": "<unknown>",
    "ID": "<string>",
    "storageID": "<string>",
    "VF_DIALOGUE_API_KEY": "<string>",
    "VF_PROJECT_API_KEY": "<string>",
    "VF_PROJECT_ID": "<string>",
    "VF_KB_API_KEY": "<string>",
    "roundedImageURL": "<string>",
    "rectangeImageURL": "<string>",
    "messageDelayMS": 123,
    "scrollAnimation": true,
    "proactiveMessage": "<string>",
    "acceptFileUpload": true,
    "recordChatHistory": true,
    "chatBgURL": "<string>",
    "disableSmoothScroll": true,
    "isDeployed": true,
    "tokensUsage": "<unknown>",
    "maxTokensUsage": "<unknown>",
    "lastModified": 123,
    "fontFamily": "<string>",
    "branding": "<string>",
    "customThemeJSONString": "<string>",
    "autoStartWidget": true,
    "allTimeTriggers": 123,
    "syncBrowser": true,
    "delayBeforeSubmit": 123,
    "region": "eu",
    "listenForUrlChanges": true,
    "chatForget": true,
    "lang": "<string>",
    "enableAudioSupport": true,
    "AITranslateTo": "<string>",
    "enableAITranslate": true,
    "disableNoReplyListener": true,
    "disableHumanHandoff": true,
    "alwaysShowHandoff": true,
    "manualControl": true,
    "enableVGHandoff": true,
    "enableGeoAnalytics": true,
    "fixedHandoffPopup": true,
    "buttonsLayout": "horizontal",
    "ADVANCED_customCSS": "<string>",
    "messagesLimit": 123,
    "whatsappToken": "<string>",
    "whatsappNumberId": "<string>",
    "whatsappBusniessId": "<string>",
    "waTestNumber": "<string>",
    "waVerifyPassed": true,
    "waTestPassed": true,
    "webhookUrl": "<string>",
    "gcloudPrivateKey": "<string>",
    "gcloudClientEmail": "<string>",
    "smartInit": true,
    "UIhandoffTitle": "<string>",
    "UIhandoffSubtitle": "<string>",
    "igVerified": true,
    "igAccessToken": "<string>",
    "showHandoffEvenIfOffline": true,
    "customButtonJSON_STRING": "<string>",
    "vg_initPrompt": "<string>",
    "vg_prompt": "<string>",
    "vg_initMessages": [
      "<string>"
    ],
    "vg_systemPrompt": "<string>",
    "vg_temperature": 123,
    "vg_defaultModel": "gpt-3.5-turbo-0125",
    "vg_maxTokens": 123,
    "vg_kbDefaultDimension": 123,
    "vg_kbTopChunks": 123,
    "SECRET_API_KEY": "<string>",
    "vg_kbCharCount": 123,
    "vg_kbDocsNum": 123,
    "vg_enableUIEngine": true,
    "vg_enableAboutContext": true,
    "vg_kb_llm": {
      "searchMethod": "smart",
      "searchPrompt": "<string>",
      "modelId": "gpt-3.5-turbo-0125",
      "temprature": 123,
      "maxTokens": 123
    },
    "vg_max_messages_history": 123,
    "ifKnowsThreshold": 123,
    "avatarImageUrl": "<string>",
    "headerImageUrl": "<string>",
    "bannerImageUrl": "<string>",
    "soundEffectUrl": "<string>",
    "soundEffectEnabled": true,
    "enableQuickFileUpload": true,
    "instagramOptions": {
      "pageId": "<string>",
      "accessToken": "<string>"
    },
    "translateUserResponse": true,
    "starred": true,
    "flowise": {
      "webhookUrl": "<string>",
      "webhookSecret": "<string>"
    },
    "vfSettings": {
      "enableIgnoreUrlPaths": true
    },
    "vapi": "<unknown>",
    "vapiConfig": {
      "syncKbOnSave": true,
      "PUBLIC_API_KEY": "<string>",
      "PRIVATE_API_KEY": "<string>",
      "enableVapiOnWeb": true,
      "overrideWithVG": true,
      "promptOnWeb": true,
      "maxCostMonthly": 123,
      "maxMinutesMonthly": 123,
      "useVfProject": true,
      "syncTools": true
    },
    "vgOptions": {
      "isLlmStudio": true,
      "showSources": true,
      "lightUiEngine": true,
      "legacyKb": true,
      "maxChunkSize": 123,
      "handoffTimeout": 123
    },
    "ui": {
      "bgImageVisible": true,
      "widgetType": "direct-chat",
      "enableFixedFeedbackBtns": true,
      "voice": {
        "question": "<string>",
        "continueBtnLabel": "<string>",
        "dismissBtnLabel": "<string>"
      }
    },
    "assignedToolsIds": [
      "<string>"
    ],
    "tools": [
      {
        "id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "isDefault": true,
        "method": "GET",
        "serverUrl": "<string>",
        "serverUrlSecret": "<string>",
        "createdAt": "<string>",
        "updatedAt": "<string>",
        "disabled": true,
        "isVapiTool": true,
        "vapiId": "<string>",
        "isGlobal": true,
        "variablesIds": [
          "<string>"
        ],
        "agentId": "<string>",
        "userId": "<string>",
        "backchannellingPhrases": [
          "<string>"
        ],
        "fields": [
          {
            "id": "<string>",
            "in": "<string>",
            "type": "string",
            "value": "<unknown>",
            "defaultValue": "<unknown>",
            "key": "<string>",
            "description": "<string>",
            "required": true,
            "reusable": true,
            "isEnv": true,
            "isSystem": true,
            "isGlobal": true,
            "agentId": "<string>",
            "userId": "<string>"
          }
        ],
        "channels": [
          "web-chat"
        ]
      }
    ],
    "internal": {
      "accountCreationConfig": "v2",
      "websocketServer": "edge",
      "setOnResponse": true,
      "enableSetOnLoad": true
    },
    "disableAutoTranscribeAudio": true,
    "instaAgentUsername": "<string>",
    "convoTags": [
      "<string>"
    ],
    "vfConfig": {
      "alwaysEnableCardButtons": true
    },
    "discord": {
      "channelIds": [
        "<string>"
      ],
      "webhookUrls": [
        "<string>"
      ]
    },
    "limits": {
      "maxInteractionsPerUserId": 123,
      "maxAnnualCreditsUsage": 123,
      "maxMonthlyCreditsUsage": 123
    },
    "tabs": "<array>",
    "kbTags": [
      "<string>"
    ],
    "kbTagsDataMap": "<array>",
    "nodes": [
      {
        "id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "instructions": "<string>",
        "llmConfig": {
          "modelId": "gpt-3.5-turbo-0125",
          "temperature": 123,
          "maxTokens": 123
        },
        "isGlobal": true,
        "toolsIds": [
          "<string>"
        ],
        "childrenNodes": [
          {
            "nodeId": "<string>",
            "condition": "<string>"
          }
        ],
        "routerLlmConfig": {
          "modelId": "gpt-3.5-turbo-0125",
          "temperature": 123,
          "maxTokens": 123
        },
        "toolUseBias": 123,
        "autoRerouter": {
          "enabled": true,
          "level": 123
        },
        "type": "start",
        "rf": "<unknown>",
        "kb": {
          "enabled": true,
          "maxChunks": 123,
          "tags": [
            "<string>"
          ],
          "smartSearch": true
        },
        "conditionData": {
          "condition": "<string>"
        },
        "preStart": {
          "url": "<string>",
          "enabled": true,
          "testConvoIdValue": "<string>"
        }
      }
    ],
    "enableNodes": true,
    "advanced": {
      "serverUrl": "<string>",
      "serverUrlSecret": "<string>"
    },
    "nodesSettings": {
      "appendBeforePrompt": "<string>",
      "routerLLmOptions": {
        "modelId": "gpt-3.5-turbo-0125",
        "temperature": 123,
        "maxTokens": 123
      },
      "defaultLLmOptions": {
        "modelId": "gpt-3.5-turbo-0125",
        "temperature": 123,
        "maxTokens": 123
      },
      "backchannelOnChoosingNodes": true,
      "enableUiEngine": true,
      "fallbackModelIds": [
        "gpt-3.5-turbo-0125"
      ],
      "silenceDetection": {
        "enabled": false,
        "timeoutSeconds": 60,
        "endCallAfterNPhrases": 1
      },
      "startCallPhrases": [
        "<string>"
      ],
      "fillerWordsOnToolUsage": true,
      "smartEndpointing": {
        "enabled": true,
        "waitSeconds": 123,
        "onPunctuationSeconds": 123,
        "onNoPunctuationSeconds": 123,
        "onNumberSeconds": 123
      },
      "stopSpeakPlan": {
        "minWords": 123
      },
      "callTimeoutSeconds": 123
    },
    "id": "<string>",
    "enableFallback": true,
    "fallbackSettings": {
      "model": "gpt-3.5-turbo-0125",
      "creditThreshold": 123
    },
    "marketplace": {
      "enabled": true,
      "priceUSD": 123
    },
    "disableRating": true,
    "chatEndMessage": "<string>",
    "aiIntroductionMessage": "<string>",
    "deployed": true
  }
}
'
{
  "success": true,
  "message": "<string>",
  "data": {
    "title": "<string>",
    "description": "<string>",
    "ownerID": "<string>",
    "theme": "<string>",
    "voiceConfig": {
      "transcriber": {
        "provider": "deepgram",
        "speechConfig": {
          "format": "<string>",
          "sampleRate": 123
        },
        "modelId": "<string>",
        "patienceFactor": 123,
        "language": "<string>",
        "randomOptions": "<unknown>",
        "internal": {
          "inputAudioStream": "<unknown>",
          "debug": true
        },
        "apiKey": "<string>",
        "platformSpecific": {
          "deepgram": {
            "keywords": [
              "<string>"
            ],
            "language": "<string>",
            "smart_format": true,
            "model": "<string>",
            "interim_results": true,
            "endpointing": 123,
            "no_delay": true
          },
          "assemblyai": {
            "modelId": "<string>"
          }
        },
        "utteranceThreshold": 123,
        "inputVoiceEnhancer": true
      },
      "speechGen": {
        "provider": "elevenlabs",
        "highAudioQuality": true,
        "modelId": "<string>",
        "voiceId": "<string>",
        "apiKey": "<string>",
        "region": "<string>",
        "backgroundNoise": "restaurant",
        "punctuationBreaks": [
          "<string>"
        ],
        "platformSpecific": {
          "elevenLabs": {
            "stability": 123,
            "similarity_boost": 123,
            "use_speaker_boost": true,
            "speed": 123,
            "style": 123
          },
          "playht": {
            "voiceId": "<string>"
          }
        },
        "backChannelling": true,
        "language": "<string>",
        "enableLongMessageBackchannelling": true,
        "backchannelMessages": [
          "<string>"
        ],
        "backchannelInterval": 123,
        "wordsReplacements": [
          {
            "word": "<string>",
            "replacement": "<string>"
          }
        ],
        "internal": {
          "inputTextStream": "<unknown>",
          "audioConfig": {
            "format": "<string>",
            "sampleRate": 123,
            "channels": 123
          },
          "emitOnComplete": true
        }
      },
      "config": {
        "recordAudio": true,
        "backgroundNoise": "restaurant",
        "enableWebCalling": true,
        "firstInputChunkUNIXMs": 123,
        "firstOutputChunkUNIXMs": 123
      }
    },
    "createdAtUNIX": 123,
    "disabled": true,
    "vectorDb": "<unknown>",
    "withRefresh": true,
    "agentPlatform": "<unknown>",
    "ID": "<string>",
    "storageID": "<string>",
    "VF_DIALOGUE_API_KEY": "<string>",
    "VF_PROJECT_API_KEY": "<string>",
    "VF_PROJECT_ID": "<string>",
    "VF_KB_API_KEY": "<string>",
    "roundedImageURL": "<string>",
    "rectangeImageURL": "<string>",
    "messageDelayMS": 123,
    "scrollAnimation": true,
    "proactiveMessage": "<string>",
    "acceptFileUpload": true,
    "recordChatHistory": true,
    "chatBgURL": "<string>",
    "disableSmoothScroll": true,
    "isDeployed": true,
    "tokensUsage": "<unknown>",
    "maxTokensUsage": "<unknown>",
    "lastModified": 123,
    "fontFamily": "<string>",
    "branding": "<string>",
    "customThemeJSONString": "<string>",
    "autoStartWidget": true,
    "allTimeTriggers": 123,
    "syncBrowser": true,
    "delayBeforeSubmit": 123,
    "region": "eu",
    "listenForUrlChanges": true,
    "chatForget": true,
    "lang": "<string>",
    "enableAudioSupport": true,
    "AITranslateTo": "<string>",
    "enableAITranslate": true,
    "disableNoReplyListener": true,
    "disableHumanHandoff": true,
    "alwaysShowHandoff": true,
    "manualControl": true,
    "enableVGHandoff": true,
    "enableGeoAnalytics": true,
    "fixedHandoffPopup": true,
    "buttonsLayout": "horizontal",
    "ADVANCED_customCSS": "<string>",
    "messagesLimit": 123,
    "whatsappToken": "<string>",
    "whatsappNumberId": "<string>",
    "whatsappBusniessId": "<string>",
    "waTestNumber": "<string>",
    "waVerifyPassed": true,
    "waTestPassed": true,
    "webhookUrl": "<string>",
    "gcloudPrivateKey": "<string>",
    "gcloudClientEmail": "<string>",
    "smartInit": true,
    "UIhandoffTitle": "<string>",
    "UIhandoffSubtitle": "<string>",
    "igVerified": true,
    "igAccessToken": "<string>",
    "showHandoffEvenIfOffline": true,
    "customButtonJSON_STRING": "<string>",
    "vg_initPrompt": "<string>",
    "vg_prompt": "<string>",
    "vg_initMessages": [
      "<string>"
    ],
    "vg_systemPrompt": "<string>",
    "vg_temperature": 123,
    "vg_defaultModel": "gpt-3.5-turbo-0125",
    "vg_maxTokens": 123,
    "vg_kbDefaultDimension": 123,
    "vg_kbTopChunks": 123,
    "SECRET_API_KEY": "<string>",
    "vg_kbCharCount": 123,
    "vg_kbDocsNum": 123,
    "vg_enableUIEngine": true,
    "vg_enableAboutContext": true,
    "vg_kb_llm": {
      "searchMethod": "smart",
      "searchPrompt": "<string>",
      "modelId": "gpt-3.5-turbo-0125",
      "temprature": 123,
      "maxTokens": 123
    },
    "vg_max_messages_history": 123,
    "ifKnowsThreshold": 123,
    "avatarImageUrl": "<string>",
    "headerImageUrl": "<string>",
    "bannerImageUrl": "<string>",
    "soundEffectUrl": "<string>",
    "soundEffectEnabled": true,
    "enableQuickFileUpload": true,
    "instagramOptions": {
      "pageId": "<string>",
      "accessToken": "<string>"
    },
    "translateUserResponse": true,
    "starred": true,
    "flowise": {
      "webhookUrl": "<string>",
      "webhookSecret": "<string>"
    },
    "vfSettings": {
      "enableIgnoreUrlPaths": true
    },
    "vapi": "<unknown>",
    "vapiConfig": {
      "syncKbOnSave": true,
      "PUBLIC_API_KEY": "<string>",
      "PRIVATE_API_KEY": "<string>",
      "enableVapiOnWeb": true,
      "overrideWithVG": true,
      "promptOnWeb": true,
      "maxCostMonthly": 123,
      "maxMinutesMonthly": 123,
      "useVfProject": true,
      "syncTools": true
    },
    "vgOptions": {
      "isLlmStudio": true,
      "showSources": true,
      "lightUiEngine": true,
      "legacyKb": true,
      "maxChunkSize": 123,
      "handoffTimeout": 123
    },
    "ui": {
      "bgImageVisible": true,
      "widgetType": "direct-chat",
      "enableFixedFeedbackBtns": true,
      "voice": {
        "question": "<string>",
        "continueBtnLabel": "<string>",
        "dismissBtnLabel": "<string>"
      }
    },
    "assignedToolsIds": [
      "<string>"
    ],
    "tools": [
      {
        "id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "isDefault": true,
        "method": "GET",
        "serverUrl": "<string>",
        "serverUrlSecret": "<string>",
        "createdAt": "<string>",
        "updatedAt": "<string>",
        "disabled": true,
        "isVapiTool": true,
        "vapiId": "<string>",
        "isGlobal": true,
        "variablesIds": [
          "<string>"
        ],
        "agentId": "<string>",
        "userId": "<string>",
        "backchannellingPhrases": [
          "<string>"
        ],
        "fields": [
          {
            "id": "<string>",
            "in": "<string>",
            "type": "string",
            "value": "<unknown>",
            "defaultValue": "<unknown>",
            "key": "<string>",
            "description": "<string>",
            "required": true,
            "reusable": true,
            "isEnv": true,
            "isSystem": true,
            "isGlobal": true,
            "agentId": "<string>",
            "userId": "<string>"
          }
        ],
        "channels": [
          "web-chat"
        ]
      }
    ],
    "internal": {
      "accountCreationConfig": "v2",
      "websocketServer": "edge",
      "setOnResponse": true,
      "enableSetOnLoad": true
    },
    "disableAutoTranscribeAudio": true,
    "instaAgentUsername": "<string>",
    "convoTags": [
      "<string>"
    ],
    "vfConfig": {
      "alwaysEnableCardButtons": true
    },
    "discord": {
      "channelIds": [
        "<string>"
      ],
      "webhookUrls": [
        "<string>"
      ]
    },
    "limits": {
      "maxInteractionsPerUserId": 123,
      "maxAnnualCreditsUsage": 123,
      "maxMonthlyCreditsUsage": 123
    },
    "tabs": "<array>",
    "kbTags": [
      "<string>"
    ],
    "kbTagsDataMap": "<array>",
    "nodes": [
      {
        "id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "instructions": "<string>",
        "llmConfig": {
          "modelId": "gpt-3.5-turbo-0125",
          "temperature": 123,
          "maxTokens": 123
        },
        "isGlobal": true,
        "toolsIds": [
          "<string>"
        ],
        "childrenNodes": [
          {
            "nodeId": "<string>",
            "condition": "<string>"
          }
        ],
        "routerLlmConfig": {
          "modelId": "gpt-3.5-turbo-0125",
          "temperature": 123,
          "maxTokens": 123
        },
        "toolUseBias": 123,
        "autoRerouter": {
          "enabled": true,
          "level": 123
        },
        "type": "start",
        "rf": "<unknown>",
        "kb": {
          "enabled": true,
          "maxChunks": 123,
          "tags": [
            "<string>"
          ],
          "smartSearch": true
        },
        "conditionData": {
          "condition": "<string>"
        },
        "preStart": {
          "url": "<string>",
          "enabled": true,
          "testConvoIdValue": "<string>"
        }
      }
    ],
    "enableNodes": true,
    "advanced": {
      "serverUrl": "<string>",
      "serverUrlSecret": "<string>"
    },
    "nodesSettings": {
      "appendBeforePrompt": "<string>",
      "routerLLmOptions": {
        "modelId": "gpt-3.5-turbo-0125",
        "temperature": 123,
        "maxTokens": 123
      },
      "defaultLLmOptions": {
        "modelId": "gpt-3.5-turbo-0125",
        "temperature": 123,
        "maxTokens": 123
      },
      "backchannelOnChoosingNodes": true,
      "enableUiEngine": true,
      "fallbackModelIds": [
        "gpt-3.5-turbo-0125"
      ],
      "silenceDetection": {
        "enabled": false,
        "timeoutSeconds": 60,
        "endCallAfterNPhrases": 1
      },
      "startCallPhrases": [
        "<string>"
      ],
      "fillerWordsOnToolUsage": true,
      "smartEndpointing": {
        "enabled": true,
        "waitSeconds": 123,
        "onPunctuationSeconds": 123,
        "onNoPunctuationSeconds": 123,
        "onNumberSeconds": 123
      },
      "stopSpeakPlan": {
        "minWords": 123
      },
      "callTimeoutSeconds": 123
    },
    "id": "<string>",
    "enableFallback": true,
    "fallbackSettings": {
      "model": "gpt-3.5-turbo-0125",
      "creditThreshold": 123
    },
    "marketplace": {
      "enabled": true,
      "priceUSD": 123
    },
    "disableRating": true,
    "chatEndMessage": "<string>",
    "aiIntroductionMessage": "<string>",
    "deployed": true
  }
}

​
Usage

The Update Agent endpoint allows you to update an existing agent’s configuration. The API uses deep merging, so you only need to provide the fields you want to update.
Important: Agent instructions are stored in the nodes array, not at the top level. To update your agent’s prompt/instructions, you must update the nodes[0].instructions field where the node has id: "__start__".

​
Updating Agent Instructions

Agent instructions are stored within the nodes array. Each agent has a start node with id: "__start__" that contains the main instructions.

​
Example: Update Instructions Only

{
  "id": "your_agent_id",
  "agent": {
    "nodes": [
      {
        "id": "__start__",
        "instructions": "Your new instructions here. Be a helpful assistant that answers questions about our products."
      }
    ]
  }
}

​
Example: Update Instructions and LLM Model

{
  "id": "your_agent_id",
  "agent": {
    "nodes": [
      {
        "id": "__start__",
        "instructions": "You are a friendly customer support agent. Help users with their questions.",
        "llmConfig": {
          "modelId": "gpt-4o",
          "temperature": 0.7,
          "maxTokens": 2048
        }
      }
    ]
  }
}

​
Example: Update Agent Metadata and Instructions

{
  "id": "your_agent_id",
  "agent": {
    "title": "My Updated Agent",
    "description": "A helpful customer support assistant",
    "nodes": [
      {
        "id": "__start__",
        "instructions": "Greet users warmly and help them with their inquiries."
      }
    ]
  }
}

​
Node Structure

Each node in the nodes array can have the following properties:
PropertyTypeDescription
idstringRequired. The node identifier. Use "__start__" for the main start node.
instructionsstringThe prompt/instructions for the LLM at this node.
namestringDisplay name for the node.
descriptionstringDescription of what the node does.
llmConfigobjectLLM configuration including modelId, temperature, and maxTokens.
toolsIdsarrayArray of tool IDs assigned to this node.
kbobjectKnowledge base settings with enabled (boolean) and maxChunks (number).

​
Using Variables and Tools in Instructions

You can reference variables and tools in your instructions using the following syntax:
  • Variables: {{var:variable_id}}
  • Tools: {{tool:tool_id}}
{
  "id": "your_agent_id",
  "agent": {
    "nodes": [
      {
        "id": "__start__",
        "instructions": "Greet the user and store their name in {{var:user_name_variable_id}}. When they ask for help, use the {{tool:search_tool_id}} tool to find relevant information."
      }
    ]
  }
}

​
Updating Custom Theme & Color Palette

You can customize your agent’s appearance by setting a custom color palette. This requires setting both the theme field and the customThemeJSONString field.

​
Example: Custom Dark Theme

{
  "agent": {
    "theme": "custom-dark",
    "customThemeJSONString": "{\"themeType\":\"dark\",\"primary\":\"#8A2BE2\",\"nineColorPallet\":[[270,15,10],[270,15,15],[270,10,25],[270,10,50],[270,15,85],[270,25,95],[270,80,55],[270,85,65],[270,90,75],[270,95,85]],\"autogenTheme\":false}"
  }
}

​
Example: Custom Light Theme

{
  "agent": {
    "theme": "custom-light",
    "customThemeJSONString": "{\"themeType\":\"light\",\"primary\":\"#0096c7\",\"nineColorPallet\":[[199,100,39],[45,100,50],[0,0,10],[142,76,45],[217,100,61],[25,89,56],[280,83,57],[160,100,40],[187,85,55],[142,100,30]],\"autogenTheme\":false}"
  }
}

​
Custom Theme JSON Structure

The customThemeJSONString is a stringified JSON object with the following properties:
PropertyTypeDescription
themeType"light" or "dark"Base theme mode. Must match the theme field suffix.
primarystringPrimary accent color in hex format (e.g., "#8A2BE2").
nineColorPalletarrayArray of 10 HSL color values, each as [Hue, Saturation, Lightness].
autogenThemebooleanIf true, auto-generates the palette from the primary color.

​
HSL Color Format

Each color in nineColorPallet is an array of 3 numbers:
  • Hue: 0-360 (position on the color wheel)
  • Saturation: 0-100 (color intensity percentage)
  • Lightness: 0-100 (brightness percentage)
Important: When updating the custom theme, ensure that:
  1. The theme field matches the themeType in the JSON string (e.g., "custom-dark" with "themeType": "dark")
  2. The nineColorPallet array contains exactly 10 HSL color values
  3. The customThemeJSONString is a properly escaped JSON string

​
Auto-Generate Palette

If you only want to set a primary color and have the palette auto-generated: 
{
  "agent": {
    "theme": "custom-light",
    "customThemeJSONString": "{\"themeType\":\"light\",\"primary\":\"#6366f1\",\"autogenTheme\":true}"
  }
}

​
Example Response

{
  "success": true,
  "message": "Agent updated successfully",
  "data": {
    "ID": "your_agent_id",
    "title": "My Updated Agent",
    "description": "A helpful customer support assistant",
    "nodes": [
      {
        "id": "__start__",
        "name": "Start",
        "instructions": "Greet users warmly and help them with their inquiries.",
        "llmConfig": {
          "modelId": "gpt-4o",
          "temperature": 0.7,
          "maxTokens": 2048
        }
      }
    ]
  }
}

​
Legacy Fields (Deprecated)

The following top-level fields are legacy fields and should not be used for new integrations. They are only used during migration from older agent formats:
  • vg_systemPrompt
  • vg_initPrompt
  • vg_prompt
  • vg_initMessages
  • instructions (at the top level)
Always use the nodes array to update agent instructions.

​
Notes

  • The API uses deep merging, so only the fields you specify will be updated
  • When updating nodes, the merge is performed by matching the id field
  • You only need to provide the node properties you want to change; other properties will be preserved
  • The lastModified timestamp is automatically updated
  • If the agent doesn’t exist, a 404 error will be returned
  • You must be the owner of the agent to update it

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string
required

The unique identifier of the agent to update

Body

application/json
​
agent
object
required

Response

Successful response

​
success
boolean
required
​
message
string
required
​
data
object
required