curl --request POST \
  --url https://api.talkpilot.io/v1/agents/{agentId}/tools \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "lookup_customer",
  "display_name": "Kunden-Lookup",
  "description": "Looks up customer information by phone number",
  "tool_type": "http_request",
  "config": {
    "url": "https://crm.example.com/api/customers",
    "method": "GET",
    "headers": [
      {
        "name": "Authorization",
        "value": "Bearer {{API_KEY}}"
      }
    ],
    "timeout": "5000",
    "speak_during_execution": true,
    "speak_after_execution": true
  },
  "priority": 1,
  "is_enabled": true
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "display_name": "<string>",
  "description": "<string>",
  "tool_type": "http_request",
  "config": {},
  "is_enabled": true,
  "priority": 123,
  "employee_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Tools

Create a tool

Add a new tool to an agent. The tool_type determines which fields are required in the config object.

Tool types and their config:

http_request — Make HTTP requests to external APIs

{ "url": "https://...", "method": "GET", "headers": [{"name":"...", "value":"..."}], "query_params": [{"name":"...", "value":"..."}], "timeout": "5000", "speak_during_execution": true, "speak_after_execution": true }

timeout is a string in milliseconds; header/query entries use the key name. "timeout": 30 or {"key": ...} are rejected with 400, because the voice agent silently drops such entries.

transfer_call — Cold/warm call transfer

{ "phone_number": "+49...", "transfer_mode": "cold", "play_hold_music": false }

monitored_transfer — SIP INVITE transfer with monitoring

{ "phone_number": "+49...", "timeout_seconds": 20 }

end_call — End the call

{ "goodbye_message": "Auf Wiedersehen!" }

extract_variable — Extract structured data from conversation

{ "variable_name": "email", "variable_type": "email", "prompt_text": "...", "example_format": "user@example.com", "confirmation_enabled": true }

play_tone — Play DTMF tones

{ "tone_type": "dtmf", "dtmf_digit": "1", "duration": 500, "volume": 0.8 }

knowledge_base — Search agent knowledge base

{ "top_k": 5, "similarity_threshold": 0.7, "bridging_sentence": "Einen Moment..." }

set_call_result — Let the agent record a call outcome (outbound campaigns); no config, send {}

switch_agent — Hand the live call over to another agent of your organization

{ "target_agent_id": "<agent uuid>", "ring_count": 1, "intro_instructions": "optional" }

identify_caller — Identify the caller against your system via a case-number + postcode handshake through your own webhooks (lookup_url, fetch_case_url, optional verify_plz_url, digit settings for aktenzeichen and plz). Set this up together with TalkPilot support.

verify_value — Deterministic check of a dictated value; every outcome referenced in rules, default_outcome and unresolved_outcome must be a key of outcomes

{ "value": { "name": "plz", "type": "digits" }, "rules": [{ "match": "in", "values": ["10115"], "outcome": "ok" }], "default_outcome": "nein", "unresolved_outcome": "nein", "outcomes": { "ok": { "say": "Passt." }, "nein": { "say": "Leider nicht." } } }

list_available_slots / book_appointment — appointment booking on the organization’s connected calendar; both tools share the same config

{ "business_hours": { "mon": [["09:00", "12:00"], ["13:00", "17:00"]] }, "duration_minutes": 60, "lead_time_hours": 24, "search_window_days": 14, "contact_mode": "email", "email_variable": "email" }

resolve_contact — clears the contact channel before a booking in contact_mode: phone; all sentences are yours, {mitarbeiter} is the only placeholder

{ "employee_name": "Herr Seiler", "confirm_calling_number": "...", "ask_mobile": "...", "ask_mobile_anonymous": "...", "ask_other_number": "...", "ask_email": "...", "no_contact": "..." }

Each type’s required fields and ranges are checked on create and update (400 VALIDATION_ERROR with details[].field = "config").

POST

agents

{agentId}

tools

curl --request POST \
  --url https://api.talkpilot.io/v1/agents/{agentId}/tools \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "lookup_customer",
  "display_name": "Kunden-Lookup",
  "description": "Looks up customer information by phone number",
  "tool_type": "http_request",
  "config": {
    "url": "https://crm.example.com/api/customers",
    "method": "GET",
    "headers": [
      {
        "name": "Authorization",
        "value": "Bearer {{API_KEY}}"
      }
    ],
    "timeout": "5000",
    "speak_during_execution": true,
    "speak_after_execution": true
  },
  "priority": 1,
  "is_enabled": true
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "display_name": "<string>",
  "description": "<string>",
  "tool_type": "http_request",
  "config": {},
  "is_enabled": true,
  "priority": 123,
  "employee_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

X-API-Key

string

header

required

API key for external access. Format: tp_live_<32-hex-chars>. Create keys in the TalkPilot Dashboard under Settings > API.

Path Parameters

agentId

string<uuid>

required

Agent UUID

Body

application/json

name

string

required

Internal tool name (lowercase, underscores)

Required string length: 1 - 100

description

string

required

Required string length: 1 - 2000

tool_type

enum<string>

required

Tool types accepted by the API:

http_request — Make HTTP requests to external APIs
transfer_call — Blind or warm call transfer
monitored_transfer — SIP INVITE transfer with monitoring
end_call — End the call with optional goodbye message
extract_variable — Extract structured data (email, phone, etc.)
play_tone — Play DTMF tones
knowledge_base — Search the agent's knowledge base
set_call_result — Record a call outcome (no config)
identify_caller — Caller identification handshake via your webhooks
switch_agent — Hand the call over to another agent
verify_value — Deterministic check of a dictated value against rules
resolve_contact — Establish how to reach the caller before booking (phone mode)
list_available_slots — Offer free appointment slots from the connected calendar
book_appointment — Book the chosen slot (same config as list_available_slots)

Available options:

http_request,

transfer_call,

monitored_transfer,

end_call,

extract_variable,

play_tone,

knowledge_base,

set_call_result,

identify_caller,

switch_agent,

verify_value,

resolve_contact,

list_available_slots,

book_appointment

config

object

required

display_name

string | null

Maximum string length: 255

is_enabled

boolean

default:true

priority

integer | null

employee_id

string<uuid> | null

Link this transfer tool to an employee. config.phone_number is then derived from the employee and must not be sent with a different value — doing so returns 409 CONFLICT. The employee must belong to the same agent and must have a phone number, otherwise 400 VALIDATION_ERROR.

Response

Tool created

string<uuid>

agent_id

string<uuid>

name

string

Internal tool name (used in LLM function calling)

display_name

string | null

Human-readable display name

description

string

Tool description (shown to the LLM to decide when to use it)

tool_type

enum<string>

Tool types accepted by the API:

http_request — Make HTTP requests to external APIs
transfer_call — Blind or warm call transfer
monitored_transfer — SIP INVITE transfer with monitoring
end_call — End the call with optional goodbye message
extract_variable — Extract structured data (email, phone, etc.)
play_tone — Play DTMF tones
knowledge_base — Search the agent's knowledge base
set_call_result — Record a call outcome (no config)
identify_caller — Caller identification handshake via your webhooks
switch_agent — Hand the call over to another agent
verify_value — Deterministic check of a dictated value against rules
resolve_contact — Establish how to reach the caller before booking (phone mode)
list_available_slots — Offer free appointment slots from the connected calendar
book_appointment — Book the chosen slot (same config as list_available_slots)

Available options:

http_request,

transfer_call,

monitored_transfer,

end_call,

extract_variable,

play_tone,

knowledge_base,

set_call_result,

identify_caller,

switch_agent,

verify_value,

resolve_contact,

list_available_slots,

book_appointment

config

object

Tool-specific configuration (schema depends on tool_type)

is_enabled

boolean | null

priority

integer | null

Execution priority (lower number = higher priority)

employee_id

string<uuid> | null

Optional link to an employee, for transfer tools only (transfer_call, monitored_transfer). When set, config.phone_number is derived from employees.phone_number and kept in sync automatically — changing the employee's number changes the transfer target. null means the number is managed on the tool itself.

created_at

string<date-time>

updated_at

string<date-time>

API Resources

Endpoint Reference

Guides

Code Examples

Create a tool

Authorizations

Path Parameters

Body

Response