API Reference

The Call2Me API allows you to create voice AI agents that can make and receive phone calls. Build intelligent conversational AI with support for multiple LLM, TTS, and STT providers.

Base URL

                        https://api.call2me.app
                    

Supported Providers

LLM	OpenAI (GPT-4.1, GPT-5), Google Gemini
TTS	OpenAI, ElevenLabs, Cartesia, MiniMax
STT	OpenAI Whisper, Deepgram, Groq

Authentication

All API requests require a Bearer token in the Authorization header. Get your API key from the Dashboard.

                        Authorization: Bearer YOUR_API_KEY
                    

Errors

Call2Me uses conventional HTTP response codes to indicate success or failure.

`200`	Success
`201`	Created
`204`	No Content (successful delete)
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid API key
`404`	Not Found - Resource doesn't exist
`422`	Validation Error
`429`	Rate Limited
`500`	Server Error

GET /health

Health Check

Check API health and dependency status. Returns database and cache connection states.

Response Fields

status string	"healthy" or "degraded"
service string	Service name ("call2me-api")
version string	API version
checks object	database, cache status ("up"/"down")

POST /v1/agents

Create Agent

Create a new voice agent with custom voice, personality, and LLM configuration.

Request Body

agent_name* string	Human-readable name (max 100 chars)
voice_id* string	Voice ID (e.g., "openai-nova", "elevenlabs-rachel")
response_engine* object	LLM config: type ("call2me-llm" or "custom-llm"), system_prompt, llm_provider, llm_model
language string	BCP-47 code (default: "tr-TR")
begin_message string	First message when call starts
knowledge_base_ids array	Knowledge base IDs for RAG
webhook_url string	URL for call events

Response

agent_id string	Unique agent identifier
created_at datetime	Creation timestamp
updated_at datetime	Last update timestamp

GET /v1/agents

List Agents

Retrieve all agents. Results are paginated and ordered by creation date (newest first).

Query Parameters

limit integer	Max results (default: 100, max: 1000)
offset integer	Skip N results (default: 0)

GET /v1/agents/{agent_id}

Get Agent

Retrieve a specific agent by ID. Returns full agent configuration including response engine settings.

Path Parameters

agent_id*

string

Agent ID

PATCH /v1/agents/{agent_id}

Update Agent

Update an existing agent. Only provided fields will be updated. Omit fields to keep existing values.

Path Parameters

agent_id*

string

Agent ID

Request Body

agent_name string	New name
voice_id string	New voice ID
response_engine object	New LLM config
language string	New language
begin_message string	New greeting

DEL /v1/agents/{agent_id}

Delete Agent

Permanently delete an agent. This action is irreversible. Active calls using this agent will fail.

Path Parameters

agent_id*

string

Agent ID

POST /v1/calls

Create Call

Initiate an outbound phone call using a configured agent. The call will be placed asynchronously.

Request Body

agent_id* string	Agent to use for the call
to_number* string	Phone number to call (E.164 format)
from_number string	Caller ID number
metadata object	Custom metadata for the call

Response

call_id string	Unique call identifier
call_status string	"pending", "ringing", "ongoing", "ended"
direction string	"inbound" or "outbound"

GET /v1/calls

List Calls

Retrieve call history with optional filters. Results are ordered by creation date (newest first).

Query Parameters

agent_id string	Filter by agent
status string	Filter by status (pending, ringing, ongoing, ended)
direction string	Filter by direction (inbound, outbound)
limit integer	Max results (default: 100, max: 1000)
offset integer	Skip N results (default: 0)

GET /v1/calls/{call_id}

Get Call

Get call details including transcript (if available), recording URL, and analysis results.

Path Parameters

call_id*

string

Call ID

POST /v1/calls/{call_id}/end

End Call

Forcefully end an active call. The call will be marked as ended with disconnection_reason='agent_hangup'.

Path Parameters

call_id*

string

Call ID

GET /v1/voices

List Voices

Browse available voices from all providers. Multilingual voices match any language filter.

Query Parameters

provider string	openai, elevenlabs, cartesia, minimax, azure
language string	Filter by language (e.g., "tr-TR", "en")
gender string	male, female, neutral

Response (Array)

voice_id string	Voice identifier
name string	Human-readable name
provider string	Provider name
language string	Language code or "multilingual"
gender string	Voice gender
description string	Voice description

GET /v1/voices/{voice_id}

Get Voice

Get details for a specific voice including provider and language support.

Path Parameters

voice_id*

string

Voice ID

POST /v1/knowledge-base

Create Knowledge Base

Create a knowledge base with text and URL sources for RAG. Status will be 'in_progress' while processing.

Request Body

knowledge_base_name* string	Name (max 40 chars)
knowledge_base_texts array	[{title, text}] - Text sources
knowledge_base_urls array	URLs to scrape
enable_auto_refresh boolean	Auto-refresh URLs every 12h (default: false)

Response

knowledge_base_id string	Unique KB identifier
knowledge_base_name string	KB name
status string	"in_progress", "complete", "error"
knowledge_base_sources array	List of sources with IDs

GET /v1/knowledge-base

List Knowledge Bases

Retrieve all knowledge bases.

GET /v1/knowledge-base/{knowledge_base_id}

Get Knowledge Base

Get knowledge base details including all sources.

Path Parameters

knowledge_base_id*

string

Knowledge Base ID

POST /v1/knowledge-base/{knowledge_base_id}/add-sources

Add Sources

Add new text or URL sources to an existing knowledge base.

Path Parameters

knowledge_base_id*

string

Knowledge Base ID

Request Body

knowledge_base_texts array	[{title, text}] - Text sources to add
knowledge_base_urls array	URLs to add

POST /v1/knowledge-base/{knowledge_base_id}/query

Query Knowledge Base

Semantic search to find relevant content using vector similarity.

Path Parameters

knowledge_base_id*

string

Knowledge Base ID

Request Body

query* string	Search query
top_k integer	Results count (default: 5)
threshold float	Min similarity 0-1 (default: 0.7)

Response

results array	Matching chunks with similarity scores
context_text string	Combined text for LLM context

DEL /v1/knowledge-base/{knowledge_base_id}/source/{source_id}

Delete Source

Delete a specific source from a knowledge base.

Path Parameters

knowledge_base_id* string	Knowledge Base ID
source_id* string	Source ID to delete

DEL /v1/knowledge-base/{knowledge_base_id}

Delete Knowledge Base

Delete a knowledge base and all its sources. This action is irreversible.

Path Parameters

knowledge_base_id*

string

Knowledge Base ID

WS /v1/llm-websocket/{call_id}

Custom LLM WebSocket

WebSocket endpoint for custom LLM integration. Connect when a call starts with a custom-llm agent.

Query Parameters

agent_id*

string

Agent ID for this call

Connection URL

                        wss://api.call2me.app/v1/llm-websocket/{call_id}?agent_id={agent_id}
                    

Platform → Your Server

`ping_pong`	Keepalive ping
`call_details`	Call information at start
`update_only`	Transcript update, no response needed
`response_required`	User finished speaking, response needed
`reminder_required`	User silent, reminder needed

Your Server → Platform

`config`	Configuration options
`ping_pong`	Keepalive pong
`response`	Response content (can be streamed)
`agent_interrupt`	Interrupt to speak immediately

Request

# Create an agent
curl -X POST https://api.call2me.app/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Customer Support",
    "voice_id": "openai-nova",
    "response_engine": {
      "type": "call2me-llm",
      "system_prompt": "Sen yardimci bir asistansin...",
      "llm_provider": "openai",
      "llm_model": "gpt-4.1-nano"
    },
    "language": "tr-TR",
    "begin_message": "Merhaba, size nasil yardimci olabilirim?"
  }'

Response

201 Created

{
  "agent_id": "agent_a1b2c3d4e5f6",
  "agent_name": "Customer Support",
  "voice_id": "openai-nova",
  "response_engine": {
    "type": "call2me-llm",
    "llm_provider": "openai",
    "llm_model": "gpt-4.1-nano"
  },
  "language": "tr-TR",
  "created_at": "2026-02-20T12:00:00Z",
  "updated_at": "2026-02-20T12:00:00Z"
}