Skip to main content
The agent creation system allows users to create and configure AI agents with comprehensive settings in a single request. You can set up basic details, configuration, knowledge base, calling numbers, denied words, dispositions, guardrails, and metadata all at once when creating a new agent.

API Endpoint

Endpoint: POST /api/agent/createagentorupdate Content-Type: multipart/form-data Authentication: Required (Token header: token or api_access_token)

Request Structure

The endpoint accepts a multipart/form-data request with the following structure:
{
  "basic_details": {
    "agent_name": "Customer Support",   // Required
    "description": "Agent description",
    "category": 1,
    "purpose": 1,
    "agent_type": 1,                    // 1=Voice, 2=Chat, 3=Telephony, 4=General
    "chatbot_name": "Support Bot",
    "chatbot_welcome_message": "Welcome!",
    "chatbot_image": "image_url",       // Can be uploaded as file
    "agent_privacy": 0,                 // 0=Private, 1=Public
    "agent_prompt": "You are a helpful assistant...",
    "voice_id": "KYiVPerWcenyBTIvWbfY",
    "voice_provider": 1,
    "transcriber_provider": 2,
    "transcriber_language": "en",
    "tone": "professional",
    "style": "conversational",
    "instruction_sensitivity": "medium"
  },
  "configuration": {
    "context_awareness": true,
    "memory_recall": true,
    "sentiment_analysis": true,
    "interruption_handling": true,
    "agent_terminate_instruction": "...",
    "agent_terminate_messages": "..."
  },
  "knowledge_base": {
    "tools": [
      { "id": 1, "isEnabled": true }
    ],
    "sub_agents": [
      { "id": 2, "isEnabled": true }
    ],
    "text_knowledge_bases": [
      { "name": "KB1", "content": "..." }
    ]
  },
  "phone_numbers": ["+1234567890"],
  "denials": {
    "denied_words": ["word1", "word2"],
    "denied_topics": ["topic1", "topic2"]
  },
  "dispositions_config": {
    "dispositions": [...]
  },
  "guardrails": {
    ...
  },
  "metadata_config": {
    "metadata_input": ["field1", "field2"],
    "metadata_output": ["field1", "field2"]
  }
}
File Uploads:
  • basic_details[chatbot_image] - Chatbot image file
  • Knowledge base files (PDF, DOC, DOCX, XLSX, CSV) - Up to 3 files, max 10MB each

cURL Example

curl -X POST "https://your-api-domain.com/api/agent/createagentorupdate" \
  -H "token: YOUR_AUTH_TOKEN" \
  -F "basic_details[agent_name]=Customer Support Agent" \
  -F "basic_details[description]=A helpful customer support agent" \
  -F "basic_details[category]=1" \
  -F "basic_details[purpose]=1" \
  -F "basic_details[agent_type]=1" \
  -F "basic_details[chatbot_name]=Support Bot" \
  -F "basic_details[chatbot_welcome_message]=Welcome! How can I help you today?" \
  -F "basic_details[chatbot_image]=@/path/to/image.png" \
  -F "basic_details[agent_privacy]=0" \
  -F "basic_details[agent_prompt]=You are a helpful customer support assistant." \
  -F "basic_details[voice_id]=KYiVPerWcenyBTIvWbfY" \
  -F "basic_details[voice_provider]=1" \
  -F "basic_details[transcriber_provider]=2" \
  -F "basic_details[transcriber_language]=en" \
  -F "basic_details[tone]=professional" \
  -F "basic_details[style]=conversational" \
  -F "basic_details[instruction_sensitivity]=medium" \
  -F "configuration[context_awareness]=true" \
  -F "configuration[memory_recall]=true" \
  -F "configuration[sentiment_analysis]=true" \
  -F "configuration[interruption_handling]=true" \
  -F "configuration[agent_terminate_instruction]=End conversation politely" \
  -F "configuration[agent_terminate_messages]=Thank you for contacting us" \
  -F "knowledge_base[tools][0][id]=1" \
  -F "knowledge_base[tools][0][isEnabled]=true" \
  -F "knowledge_base[sub_agents][0][id]=2" \
  -F "knowledge_base[sub_agents][0][isEnabled]=true" \
  -F "knowledge_base[text_knowledge_bases][0][name]=KB1" \
  -F "knowledge_base[text_knowledge_bases][0][content]=Knowledge base content here" \
  -F "FILE_KNOWLEDGE_BASES=@/path/to/document.pdf" \
  -F "phone_numbers[]=+1234567890" \
  -F "phone_numbers[]=+0987654321" \
  -F "denials[denied_words][]=word1" \
  -F "denials[denied_words][]=word2" \
  -F "denials[denied_topics][]=topic1" \
  -F "denials[denied_topics][]=topic2" \
  -F "metadata_config[metadata_input][]=field1" \
  -F "metadata_config[metadata_input][]=field2" \
  -F "metadata_config[metadata_output][]=field1" \
  -F "metadata_config[metadata_output][]=field2"
Note: Remove any fields you don’t need. Only basic_details[agent_name] is required.

Response

Success Response

Status Code: 200 OK
{
  "message": "Agent updated successfully",
  "data": {
    "agent_id": 123
  }
}
Note: The response message says “updated” but this is the standard response for both create and update operations. The agent_id in the response is the newly created agent’s ID.

Error Responses

422 - Validation Error

Status Code: 422 Unprocessable Entity
{
  "error": true,
  "code": 422,
  "message": "Agent Name is missing",
  "data": {}
}
Common Error Messages:
  • "Agent Name is missing" - Required field agent_name is missing in basic_details
  • "Basic details are required" - basic_details object is missing
  • "Agent Name is invalid" - Invalid format for agent_name

401 - Authentication Error

Status Code: 401 Unauthorized
{
  "error": true,
  "code": 401,
  "message": "Invalid Auth Key or Session Expired",
  "data": {}
}

500 - Server Error

Status Code: 500 Internal Server Error
{
  "error": true,
  "code": 500,
  "message": "Internal server error",
  "data": {}
}

Error Codes

Status CodeError CodeDescription
200-Success
401AUTH_REQUIREDAuthentication required - Missing or invalid token
401AUTH_INVALIDInvalid authentication token or session expired
422VALIDATION_ERRORValidation failed - Check required fields and data format
422MISSING_FIELDRequired field missing
422INVALID_FORMATInvalid data format or type
500SERVER_ERRORInternal server error

Important Notes

  • agent_name is required in basic_details for creating new agents
  • All configuration sections (configuration, knowledge_base, phone_numbers, denials, dispositions_config, guardrails, metadata_config) are optional
  • File uploads are optional and limited to 3 files, 10MB each
  • Knowledge base files can be uploaded during creation using the FILE_KNOWLEDGE_BASES field
  • The endpoint uses database transactions - if any part fails, all changes are rolled back
  • All sections can be configured in a single request to create a fully configured agent