Skip to main content
Agents define how your AI handles phone conversations. Each agent has a system prompt, voice configuration, and optional function tools.

​
Endpoints

MethodEndpointDescription
GET/v1/orgs/:org_id/agentsList agents
POST/v1/orgs/:org_id/agentsCreate agent
GET/v1/orgs/:org_id/agents/:idGet agent
PATCH/v1/orgs/:org_id/agents/:idUpdate agent
DELETE/v1/orgs/:org_id/agents/:idDelete agent
POST/v1/orgs/:org_id/agents/:id/duplicateDuplicate agent

​
Agent Object

{
  "id": 12,
  "name": "Customer Support",
  "prompt": "You are a helpful customer support agent...",
  "voice": "en-US-Standard-Journey-D",
  "product": "spark",
  "background_track": null,
  "tools": [],
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}
FieldTypeDescription
idintegerUnique identifier
namestringDisplay name for the agent
promptstringSystem prompt that defines agent behavior
voicestringVoice ID for text-to-speech
productstringspark, bolt, or zap
background_trackstring | nullnull or "CALL_CENTER"
toolsarrayFunction tools the agent can call
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp

​
Product Options

ProductDescription
sparkFastest response times, optimized for speed
boltBalanced performance and quality
zapHighest quality responses

​
Create an Agent

curl -X POST https://api.thunderphone.com/v1/orgs/{org_id}/agents \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Scheduler",
    "prompt": "You are a friendly appointment scheduling assistant for Dr. Smith'\''s office. Help callers book, reschedule, or cancel appointments. Always confirm the date and time before finalizing.",
    "voice": "en-US-Standard-Journey-D",
    "product": "spark"
  }'

​
Create Agent with Function Tools

Agents can call external APIs during conversations using function tools. 
curl -X POST https://api.thunderphone.com/v1/orgs/{org_id}/agents \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Scheduler",
    "prompt": "You are a scheduling assistant. Use the search_appointments tool to find available times.",
    "voice": "en-US-Standard-Journey-D",
    "product": "spark",
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "search_appointments",
          "description": "Find available appointment slots",
          "parameters": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string",
                "description": "Date in YYYY-MM-DD format"
              },
              "service": {
                "type": "string",
                "description": "Type of service requested"
              }
            },
            "required": ["date"]
          }
        },
        "endpoint": {
          "url": "https://api.example.com/appointments/search",
          "method": "POST",
          "headers": {
            "X-Api-Key": "your-api-key"
          }
        }
      }
    ]
  }'
See Function Tools for complete documentation on tool configuration.

​
List Agents

curl https://api.thunderphone.com/v1/orgs/{org_id}/agents \
  -H "Authorization: Token YOUR_API_TOKEN"

​
Update an Agent

curl -X PATCH https://api.thunderphone.com/v1/orgs/{org_id}/agents/12 \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Updated system prompt...",
    "voice": "en-US-Standard-Journey-F"
  }'

​
Duplicate an Agent

Create a copy of an existing agent with all its settings. 
curl -X POST https://api.thunderphone.com/v1/orgs/{org_id}/agents/12/duplicate \
  -H "Authorization: Token YOUR_API_TOKEN"
The response contains the new duplicated agent with a new ID.

​
Delete an Agent

Deleting an agent is permanent. Make sure no phone numbers are using this agent.
curl -X DELETE https://api.thunderphone.com/v1/orgs/{org_id}/agents/12 \
  -H "Authorization: Token YOUR_API_TOKEN"
Response: 204 No Content