Update agent settings

curl --request PATCH \
  --url https://api.talkpilot.io/v1/agents/{agentId} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "prompt": "Du bist ein professioneller Kundenservice-Agent...",
  "greeting": "Willkommen bei Firma X, wie kann ich helfen?"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "phone_number": "<string>",
  "is_active": true,
  "language": "<string>",
  "formality": "formal",
  "llm_provider": "azure",
  "llm_model": "<string>",
  "llm_temperature": 1,
  "tts_provider": "cartesia",
  "voice_id": "<string>",
  "realtime_voice": "<string>",
  "speaking_rate": 1.25,
  "stt_provider": "soniox",
  "stt_keywords": [
    "<string>"
  ],
  "prompt": "<string>",
  "greeting": "<string>",
  "greeting_variants": [
    {
      "greeting": "<string>",
      "tag": "<string>",
      "tags": [
        "<string>"
      ],
      "from": "<string>",
      "to": "<string>",
      "min_calls_today": 2
    }
  ],
  "post_call_webhook_url": "<string>",
  "schedule": {
    "timezone": "Europe/Berlin",
    "rules": [
      {
        "days": [
          1,
          2,
          3,
          4,
          5
        ],
        "start_time": "08:00",
        "end_time": "18:00"
      }
    ]
  },
  "backup_agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "allow_greeting_interruption": true,
  "short_calls_auto_edit": true,
  "track_caller_name": true,
  "transfer_timeout_seconds": 25,
  "bundesland": "DE",
  "background_audio_enabled": true,
  "background_audio_type": "office",
  "background_audio_volume": 0.5,
  "thinking_sound_enabled": true,
  "thinking_sound_volume": 0.5,
  "aic_enhancement_enabled": true,
  "retention_days": 123,
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

PATCH

agents

{agentId}

curl --request PATCH \
  --url https://api.talkpilot.io/v1/agents/{agentId} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "prompt": "Du bist ein professioneller Kundenservice-Agent...",
  "greeting": "Willkommen bei Firma X, wie kann ich helfen?"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "phone_number": "<string>",
  "is_active": true,
  "language": "<string>",
  "formality": "formal",
  "llm_provider": "azure",
  "llm_model": "<string>",
  "llm_temperature": 1,
  "tts_provider": "cartesia",
  "voice_id": "<string>",
  "realtime_voice": "<string>",
  "speaking_rate": 1.25,
  "stt_provider": "soniox",
  "stt_keywords": [
    "<string>"
  ],
  "prompt": "<string>",
  "greeting": "<string>",
  "greeting_variants": [
    {
      "greeting": "<string>",
      "tag": "<string>",
      "tags": [
        "<string>"
      ],
      "from": "<string>",
      "to": "<string>",
      "min_calls_today": 2
    }
  ],
  "post_call_webhook_url": "<string>",
  "schedule": {
    "timezone": "Europe/Berlin",
    "rules": [
      {
        "days": [
          1,
          2,
          3,
          4,
          5
        ],
        "start_time": "08:00",
        "end_time": "18:00"
      }
    ]
  },
  "backup_agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "allow_greeting_interruption": true,
  "short_calls_auto_edit": true,
  "track_caller_name": true,
  "transfer_timeout_seconds": 25,
  "bundesland": "DE",
  "background_audio_enabled": true,
  "background_audio_type": "office",
  "background_audio_volume": 0.5,
  "thinking_sound_enabled": true,
  "thinking_sound_volume": 0.5,
  "aic_enhancement_enabled": true,
  "retention_days": 123,
  "metadata": {},
  "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

Partial agent update. Only include fields you want to change.

name

string

Required string length: 1 - 255

is_active

boolean

language

string | null

formality

enum<string> | null

Available options:

formal,

informal

llm_provider

string | null

llm_model

string | null

llm_temperature

number | null

Required range: 0 <= x <= 2

tts_provider

string | null

voice_id

string | null

realtime_voice

string | null

speaking_rate

number | null

Required range: 0.5 <= x <= 2

stt_provider

enum<string> | null

Speech-to-text provider. soniox is the default for new agents; null for native realtime providers.

Available options:

soniox,

flux,

deepgram,

elevenlabs,

mistral,

groq,

assemblyai,

cartesia

stt_keywords

string[] | null

Maximum array length: 100

prompt

string

Maximum string length: 50000

greeting

string | null

Maximum string length: 2000

greeting_variants

object[] | null

Show child attributes

post_call_webhook_url

string<uri> | null

schedule

object | null

Agent business hours. When set, the agent only accepts calls during the specified time windows. Outside hours, calls go to the backup agent.

Show child attributes

backup_agent_id

string<uuid> | null

bundesland

enum<string>

German state for public-holiday handling; DE = nationwide holidays only

Available options:

DE,

BW,

BY,

BE,

BB,

HB,

HH,

HE,

MV,

NI,

NW,

NRW,

RP,

SL,

SN,

ST,

SH,

TH

allow_greeting_interruption

boolean | null

short_calls_auto_edit

boolean

track_caller_name

boolean

transfer_timeout_seconds

integer | null

Required range: 5 <= x <= 45

background_audio_enabled

boolean

background_audio_type

enum<string>

Available options:

office,

cafe,

home_office

background_audio_volume

number

Required range: 0 <= x <= 1

thinking_sound_enabled

boolean

thinking_sound_volume

number

Required range: 0 <= x <= 1

aic_enhancement_enabled

boolean

Response

Updated agent

string<uuid>

organization_id

string<uuid>

read-only

name

string

phone_number

string

is_active

boolean

language

string | null

Language code: de, en, fr, es

formality

enum<string> | null

formal = Sie, informal = Du

Available options:

formal,

informal

llm_provider

enum<string> | null

Available options:

azure,

openai,

gemini,

gemini_live,

gemini_live_cascade,

openai_realtime,

openai_realtime_cascade,

groq

llm_model

string | null

Model identifier, e.g. gpt-4.1, gemini-2.5-flash, meta-llama/llama-4-scout-17b-16e-instruct, llama-3.3-70b-versatile, llama-3.1-8b-instant

llm_temperature

number | null

Required range: 0 <= x <= 2

tts_provider

enum<string> | null

Available options:

cartesia,

elevenlabs,

gemini_live,

openai_realtime

voice_id

string | null

Voice identifier for TTS

realtime_voice

string | null

Voice for native realtime providers (OpenAI/Gemini)

speaking_rate

number | null

Required range: 0.5 <= x <= 2

stt_provider

enum<string> | null

Speech-to-text provider (null for native realtime). soniox is the default for new agents, flux is Deepgram Flux, deepgram is Deepgram Nova-3.

Available options:

soniox,

flux,

deepgram,

elevenlabs,

mistral,

groq,

assemblyai,

cartesia

stt_keywords

string[] | null

Words the speech recognizer should prefer (names, products); max 100

Maximum array length: 100

prompt

string

System prompt for the agent

Maximum string length: 50000

greeting

string | null

Initial greeting message when call starts

Maximum string length: 2000

greeting_variants

object[] | null

Personalised greetings. The first variant whose conditions all match the caller wins; otherwise greeting is spoken. A variant is only spoken when every placeholder in it has a value.

Show child attributes

post_call_webhook_url

string<uri> | null

Webhook URL called after each call completes

schedule

object | null

Agent business hours. When set, the agent only accepts calls during the specified time windows. Outside hours, calls go to the backup agent.

Show child attributes

backup_agent_id

string<uuid> | null

Fallback agent when outside the schedule

allow_greeting_interruption

boolean | null

Allow callers to interrupt the greeting

short_calls_auto_edit

boolean

Automatically mark very short calls as done

track_caller_name

boolean

Ask for and track the caller's name

transfer_timeout_seconds

integer | null

Timeout in seconds for call transfers (5-45)

Required range: 5 <= x <= 45

bundesland

enum<string>

German state for public-holiday handling; DE = nationwide holidays only

Available options:

DE,

BW,

BY,

BE,

BB,

HB,

HH,

HE,

MV,

NI,

NW,

NRW,

RP,

SL,

SN,

ST,

SH,

TH

background_audio_enabled

boolean

Play ambient background audio during the call

background_audio_type

enum<string>

Available options:

office,

cafe,

home_office

background_audio_volume

number

Required range: 0 <= x <= 1

thinking_sound_enabled

boolean

Play a subtle sound while the agent waits for the LLM

thinking_sound_volume

number

Required range: 0 <= x <= 1

aic_enhancement_enabled

boolean

On-device voice-focus enhancement (ai-coustics) before speech recognition

retention_days

integer | null

read-only

GDPR retention of call data in days (null = default 90). Managed in the Dashboard

metadata

object | null

read-only

Provider-specific tuning (e.g. Flux/EOU settings). Managed in the Dashboard

created_at

string<date-time>

updated_at

string<date-time>

API Resources

Endpoint Reference

Guides

Code Examples

Update agent settings

Authorizations

Path Parameters

Body

Response