Agents

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

Field	Type	Description
`id`	uuid	Unique agent identifier
`name`	string	Agent display name
`phone_number`	string	Assigned phone number (read-only)
`is_active`	boolean	Whether the agent accepts calls
`language`	string	Language code: `de`, `en`, `fr`, `es`
`formality`	string	`formal` (Sie) or `informal` (Du)
`llm_provider`	string	`azure`, `openai`, `gemini`, `gemini_live`, `gemini_live_cascade`, `openai_realtime`, `openai_realtime_cascade`
`llm_model`	string	Model identifier (e.g., `gpt-4o`, `gemini-2.5-flash`)
`llm_temperature`	number	Creativity (0 = deterministic, 2 = creative)
`tts_provider`	string	`cartesia`, `elevenlabs`, `gemini_live`, `openai_realtime`
`voice_id`	string	Voice identifier for TTS
`realtime_voice`	string	Voice for native realtime providers
`speaking_rate`	number	Speech speed (0.5 - 2.0)
`stt_provider`	string	`deepgram`, `elevenlabs`, `mistral` (null for realtime)
`prompt`	string	System prompt (max 50,000 chars)
`greeting`	string	Initial greeting message (max 2,000 chars)
`post_call_webhook_url`	string	Webhook URL called after each call
`schedule`	object	Business hours configuration
`backup_agent_id`	uuid	Fallback agent when unavailable
`vacation_mode`	boolean	Whether vacation mode is active
`vacation_end`	datetime	When vacation mode auto-disables
`vacation_notdienst`	boolean	Emergency service during vacation
`allow_greeting_interruption`	boolean	Allow callers to interrupt greeting
`short_calls_auto_edit`	boolean	Auto-mark very short calls as done
`track_caller_name`	boolean	Ask for and track caller’s name
`transfer_timeout_seconds`	number	Transfer timeout (10-120 seconds)
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last 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}"

Tools — Functions the agent can invoke during calls
Employees — Human staff linked to the agent
Forwarding Slots — Call routing rules
Knowledge Base — Documents the agent can reference
Calls — Call records for this agent

API Resources

Guides

Code Examples

Key concepts

Data model

Schedule object

Endpoints

List agents

Get agent details

Get agent status (lightweight)

Update agent

Common patterns

Vacation mode workflow

Set business hours with backup

​Key concepts

​Data model

​Schedule object

​Endpoints

​List agents

​Get agent details

​Get agent status (lightweight)

​Update agent

​Common patterns

​Vacation mode workflow

​Set business hours with backup

​Related resources

Key concepts

Data model

Schedule object

Endpoints

List agents

Get agent details

Get agent status (lightweight)

Update agent

Common patterns

Vacation mode workflow

Set business hours with backup

Related resources