Skip to main content
Agents are the central entity in TalkPilot — AI voice bots that handle phone calls. Every other resource (tools, employees, forwarding slots, knowledge base, calls) is scoped to an agent.

​
Key concepts

  • Each agent has a phone number and belongs to one organization
  • Agents are configured with an LLM (language model), voice, and system prompt
  • Agents can have a schedule (business hours) and vacation mode
  • A backup agent handles calls when the primary agent is unavailable

​
Data model

FieldTypeDescription
iduuidUnique agent identifier
namestringAgent display name
phone_numberstringAssigned phone number (read-only)
is_activebooleanWhether the agent accepts calls
languagestringLanguage code: de, en, fr, es
formalitystringformal (Sie) or informal (Du)
llm_providerstringazure, openai, gemini, gemini_live, gemini_live_cascade, openai_realtime, openai_realtime_cascade
llm_modelstringModel identifier (e.g., gpt-4o, gemini-2.5-flash)
llm_temperaturenumberCreativity (0 = deterministic, 2 = creative)
tts_providerstringcartesia, elevenlabs, gemini_live, openai_realtime
voice_idstringVoice identifier for TTS
realtime_voicestringVoice for native realtime providers
speaking_ratenumberSpeech speed (0.5 - 2.0)
stt_providerstringdeepgram, elevenlabs, mistral (null for realtime)
promptstringSystem prompt (max 50,000 chars)
greetingstringInitial greeting message (max 2,000 chars)
post_call_webhook_urlstringWebhook URL called after each call
scheduleobjectBusiness hours configuration
backup_agent_iduuidFallback agent when unavailable
vacation_modebooleanWhether vacation mode is active
vacation_enddatetimeWhen vacation mode auto-disables
vacation_notdienstbooleanEmergency service during vacation
allow_greeting_interruptionbooleanAllow callers to interrupt greeting
short_calls_auto_editbooleanAuto-mark very short calls as done
track_caller_namebooleanAsk for and track caller’s name
transfer_timeout_secondsnumberTransfer timeout (10-120 seconds)
created_atdatetimeCreation timestamp
updated_atdatetimeLast update timestamp

​
Schedule object

{
  "timezone": "Europe/Berlin",
  "rules": [
    {
      "days": [1, 2, 3, 4, 5],
      "start_time": "08:00",
      "end_time": "18:00"
    },
    {
      "days": [6],
      "start_time": "09:00",
      "end_time": "14:00"
    }
  ]
}
Days: 0 = Sunday, 1 = Monday, …, 6 = Saturday.

​
Endpoints

​
List agents

GET /v1/agents
Permission: agents:read | Pagination: yes Returns all agents accessible to the API key. If the key has allowed_agent_ids set, only those agents are returned. 
curl -H "X-API-Key: $TP_KEY" "$TP_BASE/agents"

​
Get agent details

GET /v1/agents/{agentId}
Permission: agents:read Returns the full configuration of a single agent. 
curl -H "X-API-Key: $TP_KEY" "$TP_BASE/agents/550e8400-e29b-41d4-a716-446655440000"

​
Get agent status (lightweight)

GET /v1/agents/{agentId}/status
Permission: agents:read Returns only the agent’s active status, schedule, and vacation state. Includes a computed is_within_schedule field. Use this for monitoring dashboards where you don’t need the full config. 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Rezeption Bot",
  "is_active": true,
  "vacation_mode": false,
  "vacation_end": null,
  "vacation_notdienst": false,
  "schedule": {
    "timezone": "Europe/Berlin",
    "rules": [{ "days": [1,2,3,4,5], "start_time": "08:00", "end_time": "18:00" }]
  },
  "is_within_schedule": true
}

​
Update agent

PATCH /v1/agents/{agentId}
Permission: agents:write Partial update — only include fields you want to change. Omitted fields remain unchanged. Read-only fields (cannot be changed via API): phone_number, organization_id, created_by 
# Update prompt and greeting
curl -X PATCH -H "X-API-Key: $TP_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "Du bist ein freundlicher Kundenservice-Agent.", "greeting": "Hallo, wie kann ich helfen?"}' \
  "$TP_BASE/agents/550e8400-e29b-41d4-a716-446655440000"

​
Common patterns

​
Vacation mode workflow

# Enable vacation with end date and emergency service
curl -X PATCH -H "X-API-Key: $TP_KEY" -H "Content-Type: application/json" \
  -d '{"vacation_mode": true, "vacation_end": "2026-04-01T00:00:00Z", "vacation_notdienst": true}' \
  "$TP_BASE/agents/{agentId}"

# Disable vacation
curl -X PATCH -H "X-API-Key: $TP_KEY" -H "Content-Type: application/json" \
  -d '{"vacation_mode": false}' \
  "$TP_BASE/agents/{agentId}"

​
Set business hours with backup

# Set Mon-Fri 9-17, Sat 9-14, with backup agent
curl -X PATCH -H "X-API-Key: $TP_KEY" -H "Content-Type: application/json" \
  -d '{
    "schedule": {
      "timezone": "Europe/Berlin",
      "rules": [
        {"days": [1,2,3,4,5], "start_time": "09:00", "end_time": "17:00"},
        {"days": [6], "start_time": "09:00", "end_time": "14:00"}
      ]
    },
    "backup_agent_id": "backup-agent-uuid"
  }' \
  "$TP_BASE/agents/{agentId}"