Converse Logo
API
Developers

API Reference

Manage your Converse workspace programmatically — create agents, upload knowledge, trigger campaigns, and query call history.

Authentication

All API requests require a Bearer token from your API key:

bash
Authorization: Bearer YOUR_API_KEY

Generate API keys in Settings → API Keys. Keys are shown once at creation — store them securely.

Test mode

Append ?mode=test to any request to use mock data without affecting live resources or incurring usage charges. Useful during development.

Base URL

text
https://api.converse.axllabs.in/api/v1

All endpoints below are relative to this base URL.

Agents

GET
/agents

List all agents in your workspace.

POST
/agents

Create a new agent.

GET
/agents/{id}

Get a specific agent by ID.

PUT
/agents/{id}

Update an agent.

DELETE
/agents/{id}

Delete an agent.

Create agent — request body

json
{
  "name": "Support Bot",
  "system_prompt": "You are a helpful support agent...",
  "llm_model": "gemini-2.5-flash",
  "language": "en-IN",
  "greeting": "Hello! How can I help you today?"
}

Flows

GET
/flows

List all flows.

POST
/flows

Create a new flow with nodes and edges.

GET
/flows/{id}

Get a flow by ID including its full node graph.

PUT
/flows/{id}

Update flow name, nodes, or edges.

DELETE
/flows/{id}

Delete a flow.

Knowledge Base

GET
/knowledge

List documents in your knowledge base.

POST
/knowledge/upload

Upload a file (PDF, DOCX, TXT, CSV). Multipart/form-data.

POST
/knowledge/ingest-url

Scrape and index a URL. Body: { url, name }

POST
/knowledge/ingest-text

Index pasted text. Body: { name, content }

POST
/knowledge/query

Semantic search. Body: { query, top_k, voice_mode }

POST
/knowledge/{id}/reindex

Re-embed a document.

DELETE
/knowledge/{id}

Delete a document and its embeddings.

GET
/knowledge/{id}/chunks

List all indexed chunks of a document.

POST
/knowledge/agent/{agent_id}/assign/{doc_id}

Assign a document to a specific agent.

DELETE
/knowledge/agent/{agent_id}/assign/{doc_id}

Remove a document assignment from an agent.

GET
/knowledge/agent/{agent_id}

List an agent's assigned knowledge documents.

Custom Tools

GET
/tools

List custom tools.

POST
/tools

Create a tool (HTTP, webhook, code).

PUT
/tools/{id}

Update a tool.

DELETE
/tools/{id}

Delete a tool.

POST
/tools/{id}/test

Execute a tool with test inputs.

POST
/tools/agent/{agent_id}/assign/{tool_id}

Assign a tool to an agent.

DELETE
/tools/agent/{agent_id}/assign/{tool_id}

Remove a tool assignment.

GET
/tools/mcp/servers

List MCP servers.

POST
/tools/mcp/servers

Register an MCP server.

POST
/tools/mcp/servers/{id}/connect

Test connection and discover tools.

Campaigns

GET
/campaigns

List campaigns.

POST
/campaigns

Create a campaign.

GET
/campaigns/{id}

Get campaign with live stats.

PUT
/campaigns/{id}

Update campaign settings.

DELETE
/campaigns/{id}

Delete a campaign and all its contacts.

POST
/campaigns/{id}/start

Start dialing.

POST
/campaigns/{id}/pause

Pause after the current call.

POST
/campaigns/{id}/resume

Resume a paused campaign.

POST
/campaigns/{id}/cancel

Cancel immediately.

GET
/campaigns/{id}/contacts

List contacts with status/outcome filters.

POST
/campaigns/{id}/contacts

Add a single contact.

POST
/campaigns/{id}/contacts/bulk

Add up to 10,000 contacts.

POST
/campaigns/{id}/contacts/upload-csv

Upload a CSV file of contacts.

GET
/campaigns/{id}/results

Full outcome breakdown and interested contacts.

GET
/campaigns/{id}/results/export

Download results as CSV.

Calls (History)

GET
/calls

List call history with filters (status, direction, date range).

GET
/calls/{id}

Get a specific call with full transcript.

Channels

GET
/channels

List all channels.

POST
/channels

Create a channel.

PUT
/channels/{id}

Update a channel.

DELETE
/channels/{id}

Delete a channel.

POST
/channels/providers/verify

Verify credentials and fetch phone numbers.

POST
/channels/web/{id}/session

Get a WebSocket session URL for a web channel.

POST
/channels/web/{id}/public-session

Get WebSocket URL (no auth — for website embedding).

Live Space

GET
/live-space/live-calls

List all active calls for your org.

GET
/live-space/live-calls/{id}

Get live call details and transcript.

POST
/live-space/live-calls/{id}/whisper

Send a hidden message to the AI agent.

POST
/live-space/live-calls/{id}/barge

Force the AI to speak a message.

POST
/live-space/live-calls/{id}/takeover

Pause/resume AI control.

POST
/live-space/live-calls/{id}/end

End a call.

POST
/live-space/live-calls/{id}/supervisor/join

Get a WebRTC join token for a call.

Error responses

All error responses follow a consistent format:

json
{
  "detail": "Human-readable error message"
}