Agents

Agents represent AI personas (e.g., Support Bot, Sales Agent) that can have phone numbers attached to them. Each agent can be configured with a voice mode, system prompt, greeting message, and voice selection.

Voice modes

Agents support two voice modes for handling calls:

• webhook (default) — Forwards call transcripts to your configured webhook URL. You process the transcript with your own AI backend and return a response.
• hosted — Uses a built-in LLM with the agent’s systemPrompt. No webhook is needed for voice conversations; the platform handles the AI interaction directly.

Create agent

Create a new agent.

POST /v1/agents

Request body

Example

$
curl -X POST "https://api.agentphone.ai/v1/agents" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "Support Bot",
>
    "description": "Handles customer support inquiries",
>
    "voiceMode": "hosted",
>
    "systemPrompt": "You are a helpful customer support agent for Acme Corp.",
>
    "beginMessage": "Hello! Thanks for calling Acme Corp. How can I help you today?",
>
    "voice": "Polly.Amy"
>
  }'

1
{
2
  "id": "agt_abc123",
3
  "name": "Support Bot",
4
  "description": "Handles customer support inquiries",
5
  "voiceMode": "hosted",
6
  "systemPrompt": "You are a helpful customer support agent for Acme Corp.",
7
  "beginMessage": "Hello! Thanks for calling Acme Corp. How can I help you today?",
8
  "voice": "Polly.Amy",
9
  "createdAt": "2025-01-15T10:30:00Z",
10
  "numbers": []
11
}

List agents

List all agents for this project.

GET /v1/agents

Query parameters

Example

$
curl -X GET "https://api.agentphone.ai/v1/agents?limit=10&offset=0" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Get agent

Get a single agent with its attached numbers.

GET /v1/agents/{agent_id}

Example

$
curl -X GET "https://api.agentphone.ai/v1/agents/agt_abc123" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Update agent

Update an agent’s configuration. Use this to change voice mode, system prompt, greeting, or voice.

PATCH /v1/agents/{agent_id}

All fields are optional. Only include the fields you want to update.

Example

$
curl -X PATCH "https://api.agentphone.ai/v1/agents/agt_abc123" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "systemPrompt": "You are a friendly sales assistant for Acme Corp.",
>
    "voiceMode": "hosted"
>
  }'

Delete agent

Delete an agent. Phone numbers, conversations, and calls associated with the agent will have their agent reference cleared but will not be deleted.

DELETE /v1/agents/{agent_id}

Example

$
curl -X DELETE "https://api.agentphone.ai/v1/agents/agt_abc123" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Attach number to agent

Attach an existing phone number to an agent. The number must belong to the same project and must not be released.

POST /v1/agents/{agent_id}/numbers

Request body

Example

$
curl -X POST "https://api.agentphone.ai/v1/agents/agt_abc123/numbers" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"numberId": "num_xyz789"}'

List agent conversations

List all conversations for a specific agent.

GET /v1/agents/{agent_id}/conversations

Example

$
curl -X GET "https://api.agentphone.ai/v1/agents/agt_abc123/conversations?limit=10" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

List agent calls

List all calls for a specific agent.

GET /v1/agents/{agent_id}/calls

Example

$
curl -X GET "https://api.agentphone.ai/v1/agents/agt_abc123/calls?limit=5" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

List available voices

List all available TTS voices that can be used with the voice field when creating or updating agents.

GET /v1/agents/voices

Example

$
curl -X GET "https://api.agentphone.ai/v1/agents/voices" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Use the returned voice identifiers (e.g., "Polly.Amy", "Polly.Joanna") in the voice field when creating agents, updating agents, or making outbound calls.