Skip to main content

​
List All Agents

Retrieve all agents in the current workspace. GET /agents Authentication: JWT cookie or API key 
curl -X GET "https://api.vaani.ai/agents" \
  -H "Cookie: access_token=YOUR_TOKEN" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID"

​
Get Agent by ID

GET /agents/{agent_id} Authentication: JWT cookie or API key 
curl -X GET "https://api.vaani.ai/agents/ag_550e8400" \
  -H "Cookie: access_token=YOUR_TOKEN"

​
Create Agent

POST /agents Authentication: JWT cookie (Developer or Admin role) Request Body: 
curl -X POST "https://api.vaani.ai/agents" \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=YOUR_TOKEN" \
  -d '{
    "agent_name": "Sales Bot",
    "LLM_provider": "open ai",
    "LLM_model": "gpt-4o",
    "temperature": 0.7,
    "system_prompt": "You are a helpful sales assistant for Acme Corp.",
    "first_message": "Hello! Thanks for calling Acme Corp.",
    "STT_provider": "deepgram",
    "STT_model": "nova-3",
    "TTS_provider": "elevenlabs",
    "TTS_voice": "Rachel"
  }'

​
Update Agent

PUT /agents/{agent_id} Authentication: JWT cookie (Developer or Admin role) Accepts the same body as Create. Fields not provided retain their current values. 
curl -X PUT "https://api.vaani.ai/agents/ag_550e8400" \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=YOUR_TOKEN" \
  -d '{
    "system_prompt": "Updated system prompt...",
    "temperature": 0.5
  }'

​
Delete Agent

DELETE /agents/{agent_id} Authentication: JWT cookie (Admin role) 
curl -X DELETE "https://api.vaani.ai/agents/ag_550e8400" \
  -H "Cookie: access_token=YOUR_TOKEN"

​
Upload Knowledge Base Files

POST /agents/{agent_id}/upload Authentication: JWT cookie (Developer or Admin role) Upload documents to an agent’s knowledge base for RAG. 
curl -X POST "https://api.vaani.ai/agents/ag_550e8400/upload" \
  -H "Cookie: access_token=YOUR_TOKEN" \
  -F "files=@product_catalog.pdf" \
  -F "[email protected]"

​
Query Knowledge Base

POST /agents/{agent_id}/query Test RAG retrieval against an agent’s knowledge base. 
curl -X POST "https://api.vaani.ai/agents/ag_550e8400/query" \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=YOUR_TOKEN" \
  -d '{
    "query": "What are your business hours?"
  }'

​
Error Responses

StatusDetailCause
401"Invalid or missing token"Authentication failed
403"Insufficient permissions"Role too low (need Developer+)
404"Agent not found"Agent doesn’t exist or not in workspace
422Validation errorsMissing required fields or invalid types