Chatbot External API

Manage keyword-triggered chatbot flow records programmatically. These endpoints operate on the same flows as the portal Chatbot Builders (v1 and V2).

Base path: https://chatyug.com/api/external
Auth: Authorization: Bearer ck_<your_api_key>

Relationship to the portal builders

• List / create / get / update flow metadata and flowData JSON
• Design complex graphs most easily in the portal UI, then manage publish state or sync via API
• Only the four endpoints below are exposed under /api/external/chatbot — there is no separate External API publish-only route; use PUT with isPublished / isActive

List flows

Auth: Bearer API key (required)

Query parameters

curl -X GET "https://chatyug.com/api/external/chatbot/flows?published=true" \
  -H "Authorization: Bearer ck_your_api_key_here"

Success: { "success": true, "flows": [ ... ] }

Create flow

Body fields

curl -X POST https://chatyug.com/api/external/chatbot/flows \
  -H "Authorization: Bearer ck_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "flowName": "Shop keyword",
    "triggerKeywords": "SHOP,CATALOGUE",
    "flowDescription": "Menu for shoppers",
    "flowData": { "nodes": [], "edges": [] }
  }'

Success (201): { "success": true, "message": "Chatbot flow created successfully", "flowId": <id> }

Keyword conflict (409): { "success": false, "message": "...", "conflictType": "...", "conflictName": "..." }

Invalid flowData: HTTP 400 with message Invalid flowData JSON format.

Get one flow

curl -X GET https://chatyug.com/api/external/chatbot/flows/42 \
  -H "Authorization: Bearer ck_your_api_key_here"

Success: { "success": true, "flow": { ... } }. When possible, Flow_Data_JSON is parsed into a JSON object in the response.

Not found: HTTP 404.

Update flow

Body fields (all optional; send only what you change)

curl -X PUT https://chatyug.com/api/external/chatbot/flows/42 \
  -H "Authorization: Bearer ck_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "flowName": "Updated name",
    "isActive": true,
    "isPublished": true
  }'

Success: { "success": true, "message": "Chatbot flow updated successfully" }

Keyword updates that conflict return HTTP 409 with the same conflict payload shape as create.

flowData shape

Flows built in the portal store a JSON graph of nodes (ids, types, positions, data configs, and connections). When creating via API, supply a valid JSON object compatible with the ChatYug chatbot engine (nodes/edges or the structure exported from the portal).

Recommended workflow for complex bots:

1. Design in Chatbot Builder v1 or V2
2. Export from /chatbot-flows.html if you need a JSON backup
3. Use External API to list, sync, or toggle isPublished / isActive

Error summary

Related

• Chatbot Overview
• Authentication
• API Keys