API Reference
Complete v2 REST API reference. Manage agents, calls, chat sessions, knowledge bases, and webhooks programmatically.
Authentication
Authenticated requests use a Bearer token in the Authorization header. Secret keys (sk_live_* or sk_test_*) are for server-side integrations. Origin-restricted publishable keys (pk_live_* or pk_test_*) may only create voice and chat sessions.
curl https://api.converse.axllabs.in/v2/agents \ -H "Authorization: Bearer sk_live_..."
Keep secret keys server-side
Base URL
https://api.converse.axllabs.in
All paths are relative to this base URL. Current API version: v2.
Agents
Agents are AI voice personas. The v2 API exposes only safe, public fields — system prompts and provider config are never returned.
/v2/agentsList all active agents in your workspace.
/v2/agents/:idGet a specific agent by ID. Returns language, greeting, status, and timing config.
Agent object
{
"id": "agent_abc123",
"name": "Support Agent",
"language": "en-IN",
"greeting": "Hi! How can I help you today?",
"status": "active",
"max_duration_seconds": 600,
"inactivity_timeout_seconds": 30,
"created_at": "2025-01-15T10:00:00Z"
}Calls
Create outbound calls, retrieve history, end active calls, and get voice session tokens for browser-based calls.
/v2/callsList calls with cursor-based pagination.
/v2/calls/:idGet full call details including transcript, sentiment, and duration.
/v2/callsInitiate an outbound voice call.
/v2/calls/:id/endEnd an active call gracefully.
/v2/calls/webGet a voice session for browser-based calling.
Create call — request body
{
"agent_id": "agent_abc123", // Required
"to": "+919876543210", // Required: destination phone number
"from": "+918001234567", // Optional: your verified number
"channel": "voice", // Optional; voice is the only supported value
"metadata": {
"task": "Confirm appointment for tomorrow 2pm",
"customer_id": "cust_456"
}
}Always include a task
metadata.task field tells the agent the purpose of the outbound call. Requests without it are rejected before dialing. Example: "task": "Follow up on support ticket #1234"Web call — response
{
"call_id": "call_xyz789",
"token": "eyJhbGciOiJIUzI1NiJ9...", // Short-lived session token
"server_url": "wss://voice.converse.axllabs.in"
}Call object
{
"id": "call_xyz789",
"agent_id": "agent_abc123",
"channel": "voice",
"direction": "outbound",
"from_number": "+918001234567",
"to_number": "+919876543210",
"status": "completed",
"duration_ms": 125000,
"sentiment_score": 0.78,
"transcript": [
{ "role": "assistant", "content": "Hello! I'm calling to confirm..." },
{ "role": "user", "content": "Yes, that works for me." }
],
"metadata": {
"task": "Confirm appointment",
"outcome": "confirmed"
},
"created_at": "2025-01-15T14:30:00Z",
"ended_at": "2025-01-15T14:32:05Z"
}Knowledge
List the knowledge bases configured for your workspace.
/v2/knowledgeList all knowledge bases in your workspace.
Tools
/v2/toolsList tools available to agents in your workspace. Returns schema only — no URLs or credentials.
Webhooks
Register HTTPS endpoints to receive real-time event notifications. Each endpoint gets a unique signing secret for verification.
/v2/webhooksList all registered webhook endpoints.
/v2/webhooksRegister a new webhook endpoint. Returns signing_secret once — store it immediately.
/v2/webhooks/:idRemove a webhook endpoint.
Create webhook — request body
{
"url": "https://your-server.com/webhooks/converse",
"events": [
"call.completed",
"call.escalated",
"transcript.ready"
]
}Create webhook — response (signing_secret shown once)
{
"id": "wh_abc123",
"url": "https://your-server.com/webhooks/converse",
"events": ["call.completed", "call.escalated", "transcript.ready"],
"enabled": true,
"signing_secret": "whsec_a1b2c3...", // Store this — never shown again
"created_at": "2025-01-15T10:00:00Z",
"warning": "Store signing_secret securely. It will not be shown again."
}Chat
Create durable chat sessions and exchange messages with the same agent and flow runtime used by voice.
/v2/chat/sessionsCreate a new chat session.
/v2/chat/sessionsList chat sessions.
/v2/chat/sessions/:idGet session details.
/v2/chat/sessions/:id/messagesGet messages in a session.
/v2/chat/sessions/:id/messagesQueue a message for the agent.
/v2/chat/sessions/:id/messages/:request_idPoll processing state and receive the reply.
/v2/chat/sessions/:id/closeClose a chat session.
Tokens
Generate short-lived tokens for client SDKs. Use these instead of exposing your API key in frontend code.
/v2/tokens/voiceGenerate a voice session token for client SDK.
Voice token response
{
"token": "eyJhbGciOiJIUzI1NiJ9...",
"server_url": "wss://voice.converse.axllabs.in",
"call_id": "call_xyz789"
}Pagination
List endpoints use cursor-based pagination. Pass the cursor from the previous response to fetch the next page.
// Response shape for list endpoints
{
"data": [...],
"has_more": true,
"cursor": "2025-01-10T09:00:00Z" // Pass as cursor param in next request
}Rate Limiting
Publishable session and chat requests are durably rate-limited. A limited request returns 429 Too Many Requests with aRetry-After header; honor it before retrying.
Error Responses
All errors return JSON with a detail field describing the problem.
{ "detail": "Agent not found or not active" }