Version: 1.3.4

Agent API Documentation

Models Retrieval Endpoint

Method: GET
Path: https://api.kadal.ai/aiwb/bot/api/v2/models
Summary: Pull the model details with all required parameters needed to define a Bot.

Description

This endpoint retrieves comprehensive model information required for bot configuration, including provider-specific details and model parameters to balance quality and performance.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
provider	Provider of the model	String	openai, palm	No
model_name	Name of the model	String	gpt-4o, gpt-4o-mini	No

Response

{
  "status_code": 200,
  "message": "Success: Model details retrieved successfully.",
  "data": {
    "models": [
      {
        "provider": "openai",
        "model_name": "gpt-4o",
        "parameters": {}
      }
    ]
  }
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v2/models"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

params = {
    "provider": "openai",
    "model_name": "gpt-4o"
}

# Make the GET request
response = requests.get(url, headers=headers, params=params)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Chat Bot Creation Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/bot/api/v3
Summary: Create and configure customized chatbots with comprehensive options.

Description

This API enables users to create and configure customized chatbots with comprehensive options. Users can specify model details (OpenAI/Palm), context, temperature, token limits, and other generation parameters. The API supports four bot types (Custom, Super Agent, Orchestrator, External) with knowledge from content folders/objects, guidelines, and examples. Advanced features include tool_config for enabling/disabling tools like content_lake and web_search, opening conversation lines, token_usage tracking for monitoring token consumption and costs, category classification, and custom bot icon. The V3 endpoint provides enhanced configurability with additional metadata fields.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
chatbotName	Name of the chatbot (min 3 characters)	String		Yes
chatbotDescription	Description of the chatbot	String		No
folder_ids	List of folder IDs associated with the chatbot	Array	Array of strings (UUIDs). Default: `[]`	No
object_ids	List of object IDs associated with the chatbot	Array	Array of strings (UUIDs). Default: `[]`	No
composite_object_ids	List of composite objects associated with the chatbot	Array	Array of objects. Default: `[]`	No
guideline_object_ids	List of guideline IDs associated with the chatbot	Array	Array of strings (UUIDs). Default: `[]`	No
template_object_id	Template object IDs	Array	Array of strings (UUIDs). Default: `[]`	No
modelId	Model provider/identifier (min 3 characters)	String	Azure, OpenAI, Palm, etc.	Yes
modelVersion	Model version (min 2 characters)	String	gpt-35-turbo, gpt-4, gpt-4o-mini, chat-bison@001, gemini-pro, etc.	Yes
context	Context/instructions for the chatbot	String		Yes
temperature	Controls creativity of output	Number	0–2. Default: `0.5`	No
max_tokens	Maximum token limit (auto-generated from modelId + modelVersion if not set)	Integer		No
top_p	Nucleus sampling probability	Number	0–1	Yes
top_k	Top-k sampling	Number	1–500	Yes
frequency_penalty	Penalises repeated tokens	Number	0–2	Yes
presence_penalty	Encourages diverse token usage	Number	0–2	Yes
best_of	Number of completions to generate	Integer	Default: `1`	No
guard_rail	Guardrail settings	Array	Array of strings. Default: `[]`	No
examples	Example prompts for the chatbot	Array	Array of objects. Default: `[]`	No
embed_profiles	Embedding profiles	Array	Default: `[]`	No
category	Category classification	String	Default: `""`	No
bot_icon	S3 file path for bot icon	String	Default: `""`	No
tool_config	Tool configuration (keys are tool names, values are booleans)	Object	Default: `{ content_lake: true, web_search: false, image_generation: false }`	No
tool_settings	Settings for various tools	Object	`{ image_generation: { ... } }`	No
opening_line_for_conversation	Opening line to start conversation with the chatbot	String	Default: `""`	No
token_usage	Dictionary tracking token usage and cost for different operations	Object		No
type	Type of the chatbot	String	Custom, External. Default: `"Custom"`	No
is_default	Flag indicating if the chatbot is an Orchestrator or other agent	Boolean	Default: `false`	No
conversation_id	Conversation ID (UUID) for conversation with SuperBot	String	Default: `""`	No
chatbot_memory	Memory configuration for the chatbot	Object	`{ if_short_term: bool, if_long_term: bool }`	No
allow_duplication	Allow other users in the tenant to duplicate this chatbot	Boolean	Default: `false`	No
project_id	Project ID when the bot is being created from within a project	String	Default: `""`	No

Response

{
  "status_code": 201,
  "message": "Bot Created Successfully",
  "chat_bot_id": "string"
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "chatbotName": "Customer Support Bot",
    "chatbotDescription": "A bot that helps answer customer service questions",
    "folder_ids": ["folder-123", "folder-456"],
    "object_ids": ["obj-123", "obj-456"],
    "composite_object_ids": [{}],
    "guideline_object_ids": ["guide-123"],
    "template_object_id": ["template-123"],
    "modelId": "Azure",
    "modelVersion": "gpt-4o-mini",
    "context": "You are a helpful customer service assistant",
    "temperature": 0.7,
    "max_tokens": 4096,
    "top_p": 0.95,
    "top_k": 50,
    "frequency_penalty": 0.5,
    "presence_penalty": 0.5,
    "best_of": 1,
    "guard_rail": ["no_profanity", "safe_content"],
    "examples": [],
    "embed_profiles": [],
    "category": "Science",
    "bot_icon": "https://xxx/xxx/xx/1.0.0/public/emojis/assignmentA.svg",
    "tool_config": {
        "content_lake": True,
        "web_search": False,
        "image_generation": False
    },
    "tool_settings": {
        "image_generation": {}
    },
    "opening_line_for_conversation": "Hi! How can I help you today?",
    "token_usage": {},
    "type": "Custom",
    "is_default": False,
    "conversation_id": "",
    "chatbot_memory": {
        "if_short_term": False,
        "if_long_term": False
    },
    "allow_duplication": False,
    "project_id": ""
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response
if response.status_code == 201:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Chat Bots Listing Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/bot/api/v3/List/
Summary: Retrieve a list of available chat bots with filtering and pagination.

Description

This endpoint provides functionality to retrieve a list of available chat bots. The API supports filtering, pagination, and sorting of chat bots. The API also supports grouping of bots by created_by field.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
page_no	Page number to retrieve	Integer		No
page_size	Number of items per page	Integer		No
order	Sort order by creation time	String	asc, desc	No
is_published	Filter by published status	Boolean	true, false	No
group_by	Field to group by	String	created_by	No

Response

{
  "status_code": 200,
  "message": "Success: Chat bots retrieved successfully.",
  "total_bot_count": 10,
  "chat_bots": []
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/List/"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "page_no": 1,
    "page_size": 10,
    "order": "asc",
    "is_published": True,
    "group_by": "created_by"
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Chat Bot Retrieval Endpoint

Method: GET
Path: https://api.kadal.ai/aiwb/bot/api/v3/{chatbot_id}
Summary: Retrieve a specific chatbot by its ID.

Description

This endpoint allows users to retrieve details of a specific chatbot using its unique identifier.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
chatbot_id	Unique chatbot identifier	String		Yes (Path)

Response

{
  "status_code": 200,
  "chat_bot_id": "5869c849-5555-4c7b-ba79-d7404fc7f1a7",
  "data": [
    {
      "_id": "694a46d8f42bc8526fce4575",
      "chatbot_global_id": "5869c849-5555-4c7b-ba79-d7404fc7f1a7",
      "chatbot_version_id": "e18cbde4-e820-4223-bfb3-9475fb78fe13",
      "created_by_name": "System",
      "updated_by": "System",
      "created_by_ID": "System",
      "tenant_id": "8cfc8013-eb69-44ff-8dde-34b7699b3f37",
      "is_latest": true,
      "is_active": true,
      "creation_time": "2025-12-23T07:38:00.181000",
      "update_time": "2025-12-23T07:39:48.318000",
      "is_ready": null,
      "is_published": false,
      "metadata": {
        "modelId": "Azure",
        "folder_ids": "",
        "object_ids": "",
        "guideline_object_ids": "",
        "template_object_id": "",
        "modelVersion": "gpt-4o",
        "chatbotName": "Image_Bot_2312",
        "chatbotDescription": "A bot that helps answer questions",
        "context": "You are a helpful assistant",
        "temperature": 0.5,
        "max_tokens": 4096,
        "top_p": 0.95,
        "top_k": 1,
        "best_of": 1,
        "algorithm": 1,
        "frequency_penalty": 0.5,
        "presence_penalty": 0.5,
        "creator_role": "",
        "category": "",
        "bot_icon": "",
        "tool_config": {
          "content_lake": true,
          "web_search": false,
          "image_generation": true
        },
        "tool_settings": {
          "image_generation": {
            "model_provider": "VertexAI",
            "model_version": "imagen-4.0-fast-generate-001",
            "aspect_ratio": "AUTO",
            "num_images": 1
          }
        }
      },
      "chatbot_guardrails": [],
      "chatbot_examples": [],
      "embed_profiles": [],
      "is_deleted": false,
      "type": "External",
      "opening_line_for_conversation": "",
      "token_usage": {
        "additionalProp1": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "additionalProp2": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "additionalProp3": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        }
      },
      "is_default": false,
      "conversation_id": "",
      "chatbot_memory": {
        "if_short_term": false,
        "if_long_term": false
      }
    }
  ]
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/{chatbot_id}"
token = "your_token_here"
chatbot_id = "your_chatbot_id"

headers = {
    "Authorization": f"Bearer {token}"
}

# Make the GET request
response = requests.get(url.format(chatbot_id=chatbot_id), headers=headers)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Chat Bot Update Endpoint

Method: PUT
Path: https://api.kadal.ai/aiwb/bot/api/v3/{chatbot_id}
Summary: Update an existing chatbot configuration.

Description

This endpoint allows users to update the configuration of an existing chatbot by providing the chatbot ID and updated parameters.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
chatbot_id	Unique chatbot identifier	String		Yes (Path)
chatbotName	Updated name of the chatbot	String		No
chatbotDescription	Description of the chatbot	String		No
folder_ids	Linked folder IDs	Array	Array of strings (UUIDs)	No
object_ids	Linked object IDs	Array	Array of strings (UUIDs)	No
guideline_object_ids	Linked guideline object IDs	Array	Array of strings (UUIDs)	No
template_object_id	Linked template object IDs	Array	Array of strings (UUIDs)	No
modelId	Model provider/identifier	String	Azure, gpt-4o, gpt-4o-mini, etc.	No
modelVersion	Model version	String	gpt-4o-mini, latest, etc.	No
context	Bot context/instructions	String		No
temperature	Model temperature	Number	0.0-1.0	No
max_tokens	Maximum token limit	Integer		No
top_p	Nucleus sampling probability	Number	0.0-1.0	No
top_k	Top-k sampling	Integer		No
frequency_penalty	Frequency penalty	Number	0.0-2.0	No
presence_penalty	Presence penalty	Number	0.0-2.0	No
best_of	Number of completions to generate	Integer		No
guard_rail	Guardrail settings	Array		No
embed_profiles	Embedding profiles	Array		No
examples	Example prompts (Q&A)	Array	Array of objects: `{question, answer}`	No
category	Category	String		No
bot_icon	Bot icon URL or data	String		No
conversation_id	Conversation ID	String		No
opening_line_for_conversation	Opening line for conversation	String		No
tool_config	Tool configuration	Object	`{ additionalProp1, additionalProp2, ... }`	No
tool_settings	Tool settings	Object	`{ image_generation: { ... } }`	No
chatbot_memory	Chatbot memory settings	Object	`{ if_short_term: bool, if_long_term: bool }`	No
allow_duplication	Allow Duplication	Boolean	true, false	No

Response

{
  "status_code": 200,
  "message": "Success: Chat bot updated successfully.",
  "data": {}
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/{chatbot_id}"
token = "your_token_here"
chatbot_id = "your_chatbot_id"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "chatbotName": "Updated Bot Name",
    "context": "Updated context for the bot",
    "temperature": 0.8
}

# Make the PUT request
response = requests.put(url.format(chatbot_id=chatbot_id), headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Chat Bot Deletion Endpoint

Method: DELETE
Path: https://api.kadal.ai/aiwb/bot/api/v3/{chatbot_id}
Summary: Delete a specific chatbot by its ID.

Description

This endpoint allows users to permanently delete a chatbot using its unique identifier.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
chatbot_id	Unique chatbot identifier	String		Yes (Path)

Response

{
  "status_code": 200,
  "message": "Success: Chat bot deleted successfully.",
  "data": {}
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/{chatbot_id}"
token = "your_token_here"
chatbot_id = "your_chatbot_id"

headers = {
    "Authorization": f"Bearer {token}"
}

# Make the DELETE request
response = requests.delete(url.format(chatbot_id=chatbot_id), headers=headers)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Chat Bot Publish Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/bot/api/v3/publish/{chatbot_id}
Summary: Publish a chatbot to make it available for public use.

Description

This endpoint allows users to publish a chatbot, making it available for public access and deployment.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
chatbot_id	Unique chatbot identifier	String		Yes (Path)

Response

{
  "status_code": 200,
  "message": "Success: Chat bot published successfully.",
  "data": {}
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/publish/{chatbot_id}"
token = "your_token_here"
chatbot_id = "your_chatbot_id"

headers = {
    "Authorization": f"Bearer {token}"
}

# Make the POST request
response = requests.post(url.format(chatbot_id=chatbot_id), headers=headers)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Chat Bot Unpublish Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/bot/api/v3/unpublish/{chatbot_id}
Summary: Unpublish a chatbot to remove it from public access.

Description

This endpoint allows users to unpublish a chatbot, removing it from public access while keeping it available for editing.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
chatbot_id	Unique chatbot identifier	String		Yes (Path)

Response

{
  "status_code": 200,
  "message": "Success: Chat bot unpublished successfully.",
  "data": {}
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/unpublish/{chatbot_id}"
token = "your_token_here"
chatbot_id = "your_chatbot_id"

headers = {
    "Authorization": f"Bearer {token}"
}

# Make the POST request
response = requests.post(url.format(chatbot_id=chatbot_id), headers=headers)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Get Embed Credentials Endpoint

Method: GET
Path: https://api.kadal.ai/aiwb/bot/api/v3/embed/get_credentials/{chatbot_id}
Summary: Retrieve embed credentials for a chatbot.

Description

This endpoint allows users to retrieve embed credentials for integrating a chatbot into external websites or applications.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
chatbot_id	Unique chatbot identifier	String		Yes (Path)

Response

{
  "status_code": 200,
  "message": "Success: Embed credentials retrieved successfully.",
  "data": {
    "embed_token": "embed-token-here",
    "embed_url": "https://embed.kadal.ai"
  }
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/embed/get_credentials/{chatbot_id}"
token = "your_token_here"
chatbot_id = "your_chatbot_id"

headers = {
    "Authorization": f"Bearer {token}"
}

# Make the GET request
response = requests.get(url.format(chatbot_id=chatbot_id), headers=headers)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Generate Embed Credentials Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/bot/api/v3/embed/generate_credentials/{chatbot_id}
Summary: Generate new embed credentials for a chatbot.

Description

This endpoint allows users to generate new embed credentials for a chatbot, including target configuration for deployment.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
chatbot_id	Unique chatbot identifier	String		Yes (Path)
target_id	Target deployment identifier	String		Yes

Response

{
  "status_code": 200,
  "message": "Success: Embed credentials generated successfully.",
  "data": {
    "embed_token": "new-embed-token-here",
    "embed_url": "https://embed.kadal.ai"
  }
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/embed/generate_credentials/{chatbot_id}"
token = "your_token_here"
chatbot_id = "your_chatbot_id"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "target_id": "your_target_id"
}

# Make the POST request
response = requests.post(url.format(chatbot_id=chatbot_id), headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Set Active/Inactive Status Endpoint

Method: PATCH
Path: https://api.kadal.ai/aiwb/bot/api/v3/{chatbot_id}
Summary: Set a chatbot to active or inactive status.

Description

This endpoint allows users to set the active or inactive status of a chatbot. Only superadmin can set the active status of any agent belonging to any tenant. Tenant admin can set the active status of agents belonging to their tenant.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
chatbot_id	Unique chatbot identifier	String		Yes (Path)
is_active	Active status flag	Boolean	true, false	Yes

Response

{
  "status_code": 200,
  "message": "Success: Chatbot status updated successfully.",
  "data": {}
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/{chatbot_id}"
token = "your_token_here"
chatbot_id = "your_chatbot_id"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "is_active": True
}

# Make the PATCH request
response = requests.patch(url.format(chatbot_id=chatbot_id), headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Agent Maker Bot Creation Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/bot/api/v3/agent_maker
Summary: Create an agent maker bot with specialized capabilities.

Description

This endpoint allows users to create an agent maker bot with selected modelID and modelVersion. When not specified, GPT-4o is set as the default model.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
modelId	Model identifier	String	gpt-4o, gpt-4o-mini	No
modelVersion	Model version	String	latest	No
chatbotName	Name of the agent maker bot	String		Yes

Response

{
  "status_code": 200,
  "message": "Success: Agent maker bot created successfully.",
  "chatbot_global_id": "uuid-here",
  "data": {}
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/agent_maker"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "chatbotName": "My Agent Maker Bot",
    "modelId": "gpt-4o",
    "modelVersion": "latest"
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Orchestrator Bot Creation Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/bot/api/v3/orchestrator
Summary: Create an orchestrator bot for managing multiple agents.

Description

This endpoint allows users to create an orchestrator bot with selected modelID and modelVersion. When not specified, GPT-4o is set as the default model. Orchestrator bots can coordinate multiple agents and manage complex workflows.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
modelId	Model identifier	String	gpt-4o, gpt-4o-mini	No
modelVersion	Model version	String	latest	No
chatbotName	Name of the orchestrator bot	String		Yes

Response

{
  "status_code": 200,
  "message": "Success: Orchestrator bot created successfully.",
  "chatbot_global_id": "uuid-here",
  "data": {}
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/orchestrator"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "chatbotName": "My Orchestrator Bot",
    "modelId": "gpt-4o",
    "modelVersion": "latest"
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Target Creation Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/bot/api/v3/targets
Summary: Create deployment targets for chatbots.

Description

This endpoint allows users to create deployment targets for their chatbots with specified domain configurations.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
target_name	Name of the target	String		Yes
domain_name	Domain name for deployment	String		Yes

Response

{
  "status_code": 200,
  "message": "Success: Target created successfully.",
  "target_id": "target-id-here"
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/targets"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "target_name": "Production Target",
    "domain_name": "example.com"
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Targets Listing Endpoint

Method: GET
Path: https://api.kadal.ai/aiwb/bot/api/v3/targets
Summary: Retrieve list of deployment targets.

Description

This endpoint retrieves a list of all deployment targets available for the authenticated user's tenant.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required

Response

{
  "status_code": 200,
  "message": "Success: Targets retrieved successfully.",
  "targets": []
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/targets"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

# Make the GET request
response = requests.get(url, headers=headers)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Target Update Endpoint

Method: PUT
Path: https://api.kadal.ai/aiwb/bot/api/v3/targets/{target_id}
Summary: Update an existing target deployment configuration.

Description

This endpoint allows users to update the configuration of an existing target deployment.

Request

Headers: Authorization: Bearer <token>
Payload

Field	Description	Type	Example	Required
url	Target deployment URL	String	"https://example.com/api"	Yes
label	Target deployment label	String	"Production API"	Yes
description	Target deployment description	String	"Main production environment"	No

Response

{
  "message": "Success: Target updated successfully.",
  "target_id": "target-id-here"
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/bot/api/v3/targets/target-id-here"

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}

payload = {
    "url": "https://updated-example.com/api",
    "label": "Updated Production API",
    "description": "Updated main production environment"
}

response = requests.put(url, headers=headers, json=payload)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Target Deletion Endpoint

Method: DELETE
Path: https://api.kadal.ai/aiwb/bot/api/v3/targets/{target_id}
Summary: Delete a target deployment configuration.

Description

This endpoint allows users to permanently delete a target deployment configuration.

Request

Headers: Authorization: Bearer <token>
Payload

None required. The target ID is specified in the URL path.

Response

{
  "message": "Success: Target deleted successfully."
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/bot/api/v3/targets/target-id-here"

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

response = requests.delete(url, headers=headers)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Category Creation Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/bot/api/v3/categories
Summary: Create categories for organizing chatbots.

Description

This endpoint enables users to create categories for organizing chatbots with customizable labels and descriptions.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
label	Category label	String		Yes
description	Category description	String		No

Response

{
  "status_code": 200,
  "message": "Success: Category created successfully.",
  "category_id": "category-id-here"
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/categories"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "label": "Customer Support",
    "description": "Bots for customer support functions"
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Categories Listing Endpoint

Method: GET
Path: https://api.kadal.ai/aiwb/bot/api/v3/categories/List/
Summary: Retrieve a list of available categories.

Description

This endpoint provides functionality to retrieve a list of available categories for organizing chatbots.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required

Response

{
  "status_code": 200,
  "message": "Success: Categories retrieved successfully.",
  "categories": []
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v3/categories/List/"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

# Make the GET request
response = requests.get(url, headers=headers)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Chat Bots Category-wise Listing v5 Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/bot/api/v5/CategoryWise/List/
Summary: Retrieve a list of available chat bots organized by categories (v5).

Description

The List Chat Bots V5 API retrieves a list of available chat bots category wise. It is identical to v4 with one addition: the metadata.category field now accepts a list of strings so that multiple categories can be filtered in a single request. Use ["all"] (the default) to return bots from all categories. This API searches using created_by, tenant_id, is_published, metadata.chatbotName, metadata.category, metadata.modelVersion, metadata.creator_role, location, and is_deleted fields. Supports filtering by project_id to show only agents assigned to a specific project.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
created_by	Username of the creator	String		No
tenant_id	Tenant identifier for multi-tenancy	String		No
is_published	Whether the chatbot is published	Boolean	true, false	No
metadata	Configuration metadata for filtering	Object	See below	No
metadata.chatbotName	Filter by chatbot name	String		No
metadata.category	Filter by one or more categories	Array	Array of strings; use `["all"]` to return all	No
metadata.modelVersion	Filter by model version	String		No
metadata.creator_role	Filter by creator role	String		No
is_deleted	Soft delete flag	Integer	Default: 1	No
order	Sort order	String	asc, desc	No
project_id	Filter bots by project ID	String		No
location	Filter bots by location	String	Agent Library, Project	No

Response

{
  "status_code": 200,
  "message": "Bots fetched successfully",
  "total_bot_count": 34,
  "chat_bots": [
    {
      "Technology and Computer Science": [
        {
          "chat_bot_id": "xxxx-xxxx-xxxx-xxxx",
          "chatbotName": "Agent1",
          "creation_time": "2024-03-27 11:15:42",
          "created_by": "abc",
          "chatbotDescription": "Test Agent",
          "modelVersion": "gpt-35-turbo",
          "modelId": "OpenAI",
          "is_editable": false
        }
      ],
      "Extracurricular Activities": [
        {
          "chat_bot_id": "xxxx-xxxx-xxxx-xxxx",
          "chatbotName": "Agent3",
          "creation_time": "2024-05-02 02:34:22",
          "created_by": "xyz",
          "chatbotDescription": "Test Agent",
          "modelVersion": "gemini-pro",
          "modelId": "Palm",
          "is_editable": false
        }
      ]
    }
  ],
  "total_category_count": 5,
  "categories": [
    "Technology and Computer Science",
    "Extracurricular Activities"
  ]
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v5/CategoryWise/List/"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "created_by": "string",
    "tenant_id": "string",
    "is_published": False,
    "metadata": {
        "chatbotName": "string",
        "category": ["all"],
        "modelVersion": "string",
        "creator_role": "string"
    },
    "is_deleted": 1,
    "order": "asc",
    "project_id": "string",
    "location": "string"
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Bot Projects Listing Endpoint

Method: GET
Path: https://api.kadal.ai/aiwb/bot/api/v5/Bot/{chatbot_id}/Projects/
Summary: Retrieve a list of projects associated with a specific chatbot.

Description

This endpoint allows users to retrieve all projects linked to a specific chatbot identified by its unique ID. Projects represent deployment contexts or logical groupings that a bot has been associated with.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
chatbot_id	Unique chatbot identifier	String		Yes (Path)

Response

{
  "status_code": 200,
  "message": "Success: Projects retrieved successfully.",
  "chatbot_id": "5869c849-5555-4c7b-ba79-d7404fc7f1a7",
  "total_project_count": 3,
  "projects": [
    {
      "project_id": "project-uuid-here",
      "project_name": "Customer Support Project",
      "description": "Project for customer support bots",
      "created_by": "user@example.com",
      "creation_time": "2025-12-23T07:38:00.181000",
      "is_active": true
    }
  ]
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v5/Bot/{chatbot_id}/Projects/"
token = "your_token_here"
chatbot_id = "your_chatbot_id"

headers = {
    "Authorization": f"Bearer {token}"
}

# Make the GET request
response = requests.get(url.format(chatbot_id=chatbot_id), headers=headers)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Category Update Endpoint

Method: PUT
Path: https://api.kadal.ai/aiwb/bot/api/v3/categories
Summary: Update an existing category configuration.

Description

This endpoint allows users to update the configuration of an existing category.

Request

Headers: Authorization: Bearer <token>
Query Parameters:
- label (string, required): The current label of the category to update
Payload

Field	Description	Type	Example	Required
label	New category label	String	"Updated Category"	Yes
description	New category description	String	"Updated description"	No

Response

{
  "message": "Success: Category updated successfully.",
  "category_id": "category-id-here"
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/bot/api/v3/categories?label=OldCategoryLabel"

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}

payload = {
    "label": "Updated Category Label",
    "description": "Updated category description"
}

response = requests.put(url, headers=headers, json=payload)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Category Deletion Endpoint

Method: DELETE
Path: https://api.kadal.ai/aiwb/bot/api/v3/categories
Summary: Delete a category configuration.

Description

This endpoint allows users to permanently delete a category configuration.

Request

Headers: Authorization: Bearer <token>
Query Parameters:
- label (string, required): The label of the category to delete
Payload

None required. The category label is specified as a query parameter.

Response

{
  "message": "Success: Category deleted successfully."
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/bot/api/v3/categories?label=CategoryToDelete"

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

response = requests.delete(url, headers=headers)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Chat Bots Category-wise Listing Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/bot/api/v4/CategoryWise/List/
Summary: Retrieve a list of available chat bots organized by categories.

Description

The List Chat Bots V4 API provides functionality to retrieve a list of available chat bots category wise. This API searches using created_by, tenant_id, is_published, metadata.chatbotName, metadata.category, metadata.modelVersion, metadata.creator_role, location, and is_deleted fields. Supports filtering by project_id to show only agents assigned to a specific project. This API uses the MongoDB find query method.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
created_by	Username of the creator	String		No
tenant_id	Tenant identifier for multi-tenancy	String		No
is_published	Whether the chatbot is published	Boolean	true, false	No
metadata	Configuration metadata for filtering	Object	See below	No
metadata.chatbotName	Filter by chatbot name	String		No
metadata.category	Filter by category	String	Default: "all"	No
metadata.modelVersion	Filter by model version	String		No
metadata.creator_role	Filter by creator role	String		No
is_deleted	Soft delete flag	Integer	Default: 1	No
order	Sort order	String	asc, desc	No
project_id	Filter bots by project ID	String		No
location	Filter bots by location	String	Agent Library, Project	No

Response

{
  "status_code": 200,
  "message": "Bots fetched successfully",
  "total_bot_count": 34,
  "chat_bots": [
    {
      "Technology and Computer Science": [
        {
          "chat_bot_id": "xxxx-xxxx-xxxx-xxxx",
          "chatbotName": "Agent1",
          "creation_time": "2024-03-27 11:15:42",
          "created_by": "abc",
          "chatbotDescription": "Test Agent",
          "modelVersion": "gpt-35-turbo",
          "modelId": "OpenAI",
          "is_editable": false
        },
        {
          "chat_bot_id": "xxxx-xxxx-xxxx-xxxx",
          "chatbotName": "Agent2",
          "creation_time": "2024-03-27 11:33:06",
          "created_by": "abc",
          "chatbotDescription": "Test Agent",
          "modelVersion": "gpt-35-turbo",
          "modelId": "OpenAI",
          "is_editable": false
        }
      ],
      "Extracurricular Activities": [
        {
          "chat_bot_id": "xxxx-xxxx-xxxx-xxxx",
          "chatbotName": "Agent3",
          "creation_time": "2024-05-02 02:34:22",
          "created_by": "xyz",
          "chatbotDescription": "Test Agent",
          "modelVersion": "gemini-pro",
          "modelId": "Palm",
          "is_editable": false
        }
      ]
    }
  ],
  "total_category_count": 5,
  "categories": [
    "Technology and Computer Science",
    "Extracurricular Activities"
  ]
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/bot/api/v4/CategoryWise/List/"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "created_by": "string",
    "tenant_id": "string",
    "is_published": False,
    "metadata": {
        "chatbotName": "string",
        "category": "all",
        "modelVersion": "string",
        "creator_role": "string"
    },
    "is_deleted": 1,
    "order": "asc",
    "project_id": "string",
    "location": "string"
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Chat Bot Duplication Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/bot/api/v3/{chatbot_id}/duplicate
Summary: Duplicate an existing chatbot with specified components.

Description

This endpoint allows users to create a duplicate copy of an existing chatbot. Users can specify which components to copy (knowledge base, guidelines, templates) and optionally link it to a specific conversation.

Request

Content-Type: application/json
Payload

Parameter	Description	Data Type	Allowed Values	Required
new_chatbot_name	Name for the duplicated chatbot	String		No
components	Components to duplicate	Object		Yes
components.knowledge_base	Include knowledge base	Boolean	true, false	Yes
components.guidelines	Include guidelines	Boolean	true, false	Yes
components.templates	Include templates	Boolean	true, false	Yes
conversation_id	Conversation ID to link	String	UUID	No

Response

{
  "status_code": 200,
  "message": "Success: Chatbot duplicated successfully.",
  "data": {
    "chatbot_id": "new-chatbot-uuid",
    "chatbot_name": "Copy_TestAgent_1602"
  }
}

Usage

import requests

# Define the API endpoint and the payload
chatbot_id = "120d4950-ec47-41b9-a1fd-4609ef3a35b7"
url = f"https://api.kadal.ai/aiwb/bot/api/v3/{chatbot_id}/duplicate"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
    "new_chatbot_name": "Copy_TestAgent_1602",
    "components": {
        "knowledge_base": True,
        "guidelines": True,
        "templates": True
    },
    "conversation_id": "42b4efeb-dfeb-4374-8e96-c24210551607"
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Models Retrieval Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Chat Bot Creation Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Chat Bots Listing Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Chat Bot Retrieval Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Chat Bot Update Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Chat Bot Deletion Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Chat Bot Publish Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Chat Bot Unpublish Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Get Embed Credentials Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Generate Embed Credentials Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Set Active/Inactive Status Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Agent Maker Bot Creation Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Orchestrator Bot Creation Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Target Creation Endpoint​

Description​

Models Retrieval Endpoint

Description

Request

Payload

Response

Usage

Chat Bot Creation Endpoint

Description

Request

Payload

Response

Usage

Chat Bots Listing Endpoint

Description

Request

Payload

Response

Usage

Chat Bot Retrieval Endpoint

Description

Request

Payload

Response

Usage

Chat Bot Update Endpoint

Description

Request

Payload

Response

Usage

Chat Bot Deletion Endpoint

Description

Request

Payload

Response

Usage

Chat Bot Publish Endpoint

Description

Request

Payload

Response

Usage

Chat Bot Unpublish Endpoint

Description

Request

Payload

Response

Usage

Get Embed Credentials Endpoint

Description

Request

Payload

Response

Usage

Generate Embed Credentials Endpoint

Description

Request

Payload

Response

Usage

Set Active/Inactive Status Endpoint

Description

Request

Payload

Response

Usage

Agent Maker Bot Creation Endpoint

Description

Request

Payload

Response

Usage

Orchestrator Bot Creation Endpoint

Description

Request

Payload

Response

Usage

Target Creation Endpoint

Description