Skip to main content
POST
/
api
/
agents
/
create
curl -X POST "https://api.zudu.ai/api/agents/create" \
  -H "X-API-KEY: sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234Yz" \
  -H "X-API-SECRET: s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234" \
  -d '{
    "agent_name": "Customer Support Agent",
    "language": "en",
    "voice": {
      "provider": "openai",
      "voice_id": "alloy"
    },
    "first_message": "Hello! How can I help you today?",
    "model": "gpt-4",
    "transcription_model": "whisper-1"
  }'

{
  "message": "Agent created successfully",
  "status": "success",
  "error": null,
  "data": {
    "agent_id": "agent_abc123def456...",
    "agent_name": "Customer Support Agent",
    "organization_id": "org_1234567890",
    "language": "en",
    "voice": {
      "provider": "openai",
      "voice_id": "alloy"
    },
    "first_message": "Hello! How can I help you today?",
    "model": "gpt-4",
    "transcription_model": "whisper-1",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
Create a new agent with complete configuration including voice settings, language, models, tools, and more. 
curl -X POST "https://api.zudu.ai/api/agents/create" \
  -H "X-API-KEY: sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234Yz" \
  -H "X-API-SECRET: s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234" \
  -d '{
    "agent_name": "Customer Support Agent",
    "language": "en",
    "voice": {
      "provider": "openai",
      "voice_id": "alloy"
    },
    "first_message": "Hello! How can I help you today?",
    "model": "gpt-4",
    "transcription_model": "whisper-1"
  }'

{
  "message": "Agent created successfully",
  "status": "success",
  "error": null,
  "data": {
    "agent_id": "agent_abc123def456...",
    "agent_name": "Customer Support Agent",
    "organization_id": "org_1234567890",
    "language": "en",
    "voice": {
      "provider": "openai",
      "voice_id": "alloy"
    },
    "first_message": "Hello! How can I help you today?",
    "model": "gpt-4",
    "transcription_model": "whisper-1",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }

​
Headers

​
X-API-KEY
string
required
Your API key (format: sk_...)
​
X-API-SECRET
string
required
Your API secret (format: s3cr3t_...)

​
Request Body

​
agent_name
string
required
The name of the agent
  • Maximum length: 50 characters
  • Cannot be empty or whitespace only
  • Will be trimmed automatically
Example: "Customer Support Agent"
​
language
string
required
Language code for the agent (ISO 639-1)Examples: en, es, fr, de, jaExample: "en"
​
voice
object
Voice configuration for the agent
  • provider: Voice provider (e.g., openai, elevenlabs, playht)
  • voice_id: Specific voice ID from the provider
Example:
{
  "provider": "openai",
  "voice_id": "alloy"
}
​
first_message
string
The initial message the agent will say when a call startsExample: "Hello! How can I help you today?"
​
model
string
LLM model to use (e.g., gpt-4, gpt-3.5-turbo)If not provided, will be auto-selected based on language configuration
​
transcription_model
string
Transcription model to use (e.g., whisper-1)If not provided, will be auto-selected based on language configuration
​
knowledge_base_ids
array
Array of knowledge base IDs to attach to the agent for RAG (Retrieval-Augmented Generation)Example: ["kb_123", "kb_456"]
​
rag_config
object
RAG configuration for knowledge base retrieval
  • chunks_to_retrieve: Number of chunks to retrieve (default: 10)
  • similarity_threshold: Similarity threshold for retrieval (default: 0.2)
Example:
{
  "chunks_to_retrieve": 10,
  "similarity_threshold": 0.2
}
​
widget_config
object
Widget configuration for the agentIf not provided, default widget config will be initialized

​
Response Fields

​
agent_id
string
The unique identifier for the newly created agent
​
agent_name
string
The name of the agent
​
organization_id
string
The organization ID the agent belongs to
​
created_at
string
ISO 8601 timestamp when the agent was created
​
updated_at
string
ISO 8601 timestamp when the agent was last updated

​
Error Responses

​
error
string
Bad Request - Validation error or invalid agent data
{
  "message": "Validation error",
  "status": "error",
  "error": "Agent name cannot be empty"
}
​
error
string
Unauthorized - Missing or invalid API key/secret
​
error
string
Internal Server Error - Failed to create agent
{
  "message": "Failed to create agent",
  "status": "error",
  "error": "Database connection failed"
}

​
Notes

  • The agent will be automatically assigned to your organization based on the API key (organization ID is automatically extracted)
  • Models will be auto-selected based on language if not explicitly provided
  • Default RAG config will be initialized if knowledge bases are provided but RAG config is not
  • Default widget config will be initialized if not provided
  • The response returns a frontend-safe version of the agent data (hides internal model/provider details)