Converse Logo
Developers
Developers

API Reference

Complete v2 REST API reference. Manage agents, calls, knowledge bases, and webhooks programmatically.

Authentication

All requests require a Bearer token in the Authorization header using your API key (sk_live_* or sk_test_*):

bash
curl https://api.converse.axllabs.in/v2/agents \
  -H "Authorization: Bearer sk_live_..."

Server-side only

API keys grant access to your workspace. Use them exclusively in server-side code — never in browser bundles or mobile apps. For browser voice calls, use the token endpoint pattern (see SDK docs).

Base URL

text
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.

GET
/v2/agents

List all active agents in your workspace.

GET
/v2/agents/:id

Get a specific agent by ID. Returns language, greeting, status, and timing config.

Agent object

json
{
  "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, stream events, and get voice session tokens for browser-based calls.

GET
/v2/calls

List calls with cursor-based pagination.

limitcursoragent_idstatusdirection
GET
/v2/calls/:id

Get full call details including transcript, sentiment, and duration.

POST
/v2/calls

Initiate an outbound call.

agent_id*to*from?channel?metadata?
POST
/v2/calls/:id/end

End an active call gracefully.

POST
/v2/calls/web

Get a voice session for browser-based calling.

agent_id*

Create call — request body

json
{
  "agent_id": "agent_abc123",   // Required
  "to": "+919876543210",        // Required: destination phone number
  "from": "+918001234567",      // Optional: your verified number
  "channel": "voice",           // Optional: "voice" | "whatsapp" | "sms"
  "metadata": {
    "task": "Confirm appointment for tomorrow 2pm",
    "customer_id": "cust_456"
  }
}

Always include a task

The metadata.task field tells the agent the purpose of the outbound call. Without it, the agent has no context and the call will be generic. Example: "task": "Follow up on support ticket #1234"

Web call — response

json
{
  "call_id": "call_xyz789",
  "token": "eyJhbGciOiJIUzI1NiJ9...",  // Short-lived session token
  "server_url": "wss://voice.converse.axllabs.in",
  "room_name": "sdk-a1b2c3d4e5f6"      // Internal session identifier
}

Call object

json
{
  "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 knowledge bases and perform semantic search for RAG (Retrieval-Augmented Generation) use cases.

GET
/v2/knowledge

List all knowledge bases in your workspace.

POST
/v2/knowledge/query

Semantic search across knowledge base documents.

query*kb_id?threshold?limit?
POST
/v2/knowledge/:id/query

Semantic search scoped to a specific knowledge base.

query*threshold?limit?

Knowledge query — request / response

json
// Request
{
  "query": "What is the refund policy?",
  "threshold": 0.7,   // Minimum similarity score (0–1)
  "limit": 5          // Max results to return
}

// Response
{
  "results": [
    {
      "content": "Refunds are processed within 5–7 business days...",
      "score": 0.92,
      "source": "refund-policy.pdf"
    }
  ]
}

Tools

GET
/v2/tools

List 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.

GET
/v2/webhooks

List all registered webhook endpoints.

POST
/v2/webhooks

Register a new webhook endpoint. Returns signing_secret once — store it immediately.

url*events*
DELETE
/v2/webhooks/:id

Remove a webhook endpoint.

Create webhook — request body

json
{
  "url": "https://your-server.com/webhooks/converse",
  "events": [
    "call.completed",
    "call.escalated",
    "transcript.final"
  ]
}

Create webhook — response (signing_secret shown once)

json
{
  "id": "wh_abc123",
  "url": "https://your-server.com/webhooks/converse",
  "events": ["call.completed", "call.escalated", "transcript.final"],
  "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 chat sessions and exchange messages with AI agents over HTTP or WebSocket.

POST
/v2/chat/sessions

Create a new chat session.

agent_id*metadata?
GET
/v2/chat/sessions

List chat sessions.

agent_id?status?cursor?limit?
GET
/v2/chat/sessions/:id

Get session details.

GET
/v2/chat/sessions/:id/messages

Get messages in a session.

cursor?limit?
POST
/v2/chat/sessions/:id/messages

Send a message and get the agent's reply.

content*metadata?
POST
/v2/chat/sessions/:id/close

Close a chat session.

Phone Numbers

Provision and manage phone numbers for inbound/outbound calling.

POST
/v2/phone-numbers

Provision a new phone number.

country*capabilities?area_code?
GET
/v2/phone-numbers

List all phone numbers.

GET
/v2/phone-numbers/:id

Get phone number details.

PATCH
/v2/phone-numbers/:id

Update routing (assign agent, webhook).

agent_id?webhook_url?
DELETE
/v2/phone-numbers/:id

Release a phone number.

Contacts

Manage contacts for your CRM — create, tag, and query.

POST
/v2/contacts

Create a contact.

name*phone?email?company?tags?
GET
/v2/contacts

List contacts with filters.

name?phone?email?tag?cursor?limit?
GET
/v2/contacts/:id

Get a contact.

PATCH
/v2/contacts/:id

Update a contact.

DELETE
/v2/contacts/:id

Delete a contact.

POST
/v2/contacts/:id/tags

Add a tag to a contact.

tag*

Tokens

Generate short-lived tokens for client SDKs. Use these instead of exposing your API key in frontend code.

POST
/v2/tokens/voice

Generate a voice session token for client SDK.

agent_id*metadata?expires_in?
POST
/v2/tokens/chat

Generate a chat session token for client SDK.

agent_id*metadata?expires_in?

Voice token response

json
{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "server_url": "wss://voice.converse.axllabs.in",
  "call_id": "call_xyz789"
}

Analytics

Usage data, call statistics, and cost breakdown.

GET
/v2/analytics/usage

Get usage summary for a date range.

from*to*
GET
/v2/analytics/calls

Get call statistics.

from*to*agent_id?
GET
/v2/analytics/sentiment/:call_id

Get sentiment analysis for a call.

GET
/v2/analytics/costs

Get cost breakdown.

from*to*

Pagination

List endpoints use cursor-based pagination. Pass the cursor from the previous response to fetch the next page.

json
// Response shape for list endpoints
{
  "data": [...],
  "has_more": true,
  "cursor": "2025-01-10T09:00:00Z"  // Pass as cursor param in next request
}

Rate Limiting

The API enforces per-key rate limits. When exceeded, requests return 429 Too Many Requests with aRetry-After header indicating seconds to wait.

GET endpoints300 req / min
POST /v2/calls60 req / min
POST /v2/calls/web30 req / min
POST /v2/knowledge/query60 req / min

Error Responses

All errors return JSON with a detail field describing the problem.

json
{ "detail": "Agent not found or not active" }
400Bad RequestMissing required field or invalid value
401UnauthorizedMissing or invalid API key
403ForbiddenKey doesn't have the required permission scope
404Not FoundResource not found
429Too Many RequestsRate limit exceeded — check Retry-After header
500Internal ErrorServer error — safe to retry with backoff
503Service UnavailableVoice service temporarily unavailable