Agents
Update Agent
Updates an existing agent
PUT
Path Parameters
string
required
The unique identifier of the agent (UUID format)
Request Body
All fields are optional. Only include the fields you want to update.string
Optional organization guard (UUID). When provided, the request is rejected with
404 unless the target agent already belongs to this organization. It does not move the agent between organizations — it only scopes the update so you cannot accidentally modify an agent in a sibling organization under the same account. Omit it to keep the default account-scoped behavior.Basic Information
string
Display name of the agent (1-255 characters)
string
Description of what the agent does
string
Initial message the agent says when call starts
string
Greeting spoken when this agent places an outbound call (see Outbound Calls)
string
System prompt defining agent behavior and personality
string
Type of agent configuration.Supported values:
simple, advanced, custom, appointment_scheduler, receptionist, message_takerstring
Agent activation status.Supported values:
active- Agent is available to receive callsinactive- Agent is temporarily disabledcancelled- Agent is permanently disabledpending- Agent is pending activation
active and inactive on their own, use Update Agent Status — it takes just this field, so there is no risk of overwriting other configuration.AI/Voice Model Configuration
string
AI model used for the agent. See List LLM Models for the full list with descriptions.Supported values:
gpt-4.1 (recommended), gpt-4.1-mini, gpt-4o-mini, grok-3-fast, moonshotai/Kimi-K2.6, claude-sonnet-4-6string
Voice model for real-time speech
string
Speech-to-text model.Supported values:
deepgramstring
Text-to-speech model.Supported values:
cartesia, minimaxobject
Voice configuration settings. Structure varies based on Cartesia voices also accept two optional fields:For MiniMax:Advanced Voice Timing (optional, applies to all TTS models):
ttsModel:For Cartesia:Most English Cartesia voices do not accept
model or language overrides. Non-English voices (e.g. Spanish) require both:Example with advanced timing:
Call Features
boolean
Whether SIP call transfer is enabled. Supports:
- SIP extensions:
sip:extension@hostname - US phone numbers: Automatically formatted to
tel:+1XXXXXXXXXX
boolean
Whether the agent can send emails during or after calls
string
Instructions for the agent on how and when to use the email tool
boolean
Whether to enable answering machine / voicemail detection
boolean
Whether to enable echo detection during calls
boolean
Enable call recording. Recordings are saved to cloud storage and accessible via the Call Logs API.
boolean
Include a link to the call recording in the post-call summary notification. This is a sub-option of call recording — it requires recording to be enabled (
enableRecording: true in this request, or already enabled on the agent). Sending true while recording is not enabled returns a 400. Note: the link is delivered via the call-summary email, so it is only actually sent when the agent also has an email recipient configured and a recording was produced; otherwise the flag is stored but has no effect.string
Rules and conditions for call transfers. Describes when and where the agent should transfer calls.Example:
"Transfer to +15551234567 if the caller asks for billing support. Transfer to +15559876543 for technical issues."array
Array of email addresses used for notifications and the email tool.Example:
["[email protected]", "[email protected]"]string | null
UUID of the email server to use for this agent. Must belong to the same account. Pass
null to revert to the account’s default email server.Use the List Email Servers endpoint to retrieve available IDs.Localization
string
Agent language for speech recognition and responses.Supported values:
en-US- English (US)es-US- Spanish (US)multi- Multilingual (English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, Dutch)
string
Agent timezone in IANA format. Used for date/time operations and calendar scheduling.Example:
"America/New_York", "Europe/London", "Asia/Tokyo"Knowledge Base
array
Array of URLs the agent can reference for knowledge. The content at these URLs is ingested and made available to the agent during conversations.Example:
["https://example.com/faq", "https://example.com/pricing"]RAG Knowledge Base
boolean
Enable live vector search during calls. The account and the agent’s organization must both have Knowledge Base (RAG) enabled, otherwise the API returns
403 forbidden.string | null
Organization-level knowledge base ID for the agent to search. The knowledge base must belong to the same organization as the agent. Set to
null to remove the assignment.Use List Knowledge Bases to retrieve available IDs.object
RAG retrieval configuration. Unknown keys are rejected.
Business (Google Place)
string | null
Google Place ID linking the agent to a Google Business Profile listing. The platform fetches the listing’s details (hours, location, phone, website, services, ratings) and the agent uses them as verified facts when answering callers.
- Set to a Place ID to link (or relink) the agent’s business.
- Set to
nullor""to unlink. - Changing or clearing the id also clears the cached listing data (
google_place_data,google_place_context,google_place_fetched_at), so details from the previously linked business are never served while the new listing is fetched. Re-sending the already-stored id is a no-op and keeps the cache.
"ChIJVS6XxJPFU4gRoE8c8ql2lCQ"Warm Transfer
boolean
Enable warm transfer routing for this agent.
string
Plain-language rules for when and where to warm transfer. Example:
"If the caller asks for billing, confirm first and warm transfer to pbx:1234."string
Public URL of the hold-music file played during warm transfer. The easiest way to set this is Upload Hold Music, which saves the URL for you. Leave empty for built-in hold music.
boolean
Whether the original caller’s number is passed to the transfer destination. Defaults to
true.Pronunciations
array
Custom pronunciation rules for specific words and names in IPA format. Replaces the entire pronunciations list for the agent.Each entry is an object with:
Custom pronunciations are only supported on Cartesia voices using the
sonic-3 or sonic-3.5 model. A non-empty pronunciations array is rejected with 400 unless the agent’s effective voice is ttsModel: cartesia with voiceSettings.model: sonic-3 or sonic-3.5 (taking either the values in this request or the agent’s existing settings). Send an empty array [] to clear rules on any voice.word— The word or name (1–100 characters)phonetic(optional) — A plain-English respelling of how the word should sound (e.g.,jay-kob-sen). Used by the dashboard’s “Apply” helper to generate the IPAphonemes; not used directly by the agent.phonemes— The IPA phoneme string
[] to clear all pronunciation rules.Example:Advanced Configuration
object
General configuration object.Common properties:
object
Extensions configuration for webhooks and MCP servers.Webhook structure:MCP server objects (
mcp_servers):Same request validation as Create Agent — MCP request body: name and url are both required on each entry; transport_type, auth_headers (array of {key, value}), and initialization_options (object) are optional. The platform transforms each entry on write (name → connection_name, url → mcp_endpoint_url) so the stored shape differs from the request shape — see Get Agent — Stored MCP Connection Shape.Webhook conditions:before_call- Execute before the agent answersduring_call- Execute while call is activeafter_call- Execute after call ends
Integrations
object
Third-party integration configurations. Supported provider keys: Provider fields (required when creating a new provider entry; partial updates only need to leave the stored object valid):
modmed, googleCalendar, outlookCalendar, twilio, netsapiens. Unknown provider keys are stored as-is.Update semantics — unlike extensions (which is a full replace), integrations uses a field-level merge per provider:- Only the fields you send change; omitted fields and omitted providers are preserved.
- Set a field to
nullto clear that field. - Set a whole provider to
nullto remove the provider.
fromNumber, clears its testToNumber, and removes the ModMed integration — everything else is untouched:Behavior notes:
- Configs are stored as-is — credentials are not validated against the provider. ModMed/NetSapiens entries written without valid tokens will not function at runtime until tokens are supplied or the integration is connected via the Dashboard.
- Unlike the Dashboard flow, writing
twiliohere does not auto-create thesend_sms_via_twiliotool inextensions— add the tool yourself if you want the agent to send SMS. - Secret fields (passwords,
authToken,client_secret, access/refresh tokens) are write-only: they are accepted on PUT but never returned by any agent endpoint. The merge semantics make this safe — a GET → modify → PUT round-trip won’t wipe stored secrets.
MCP can be set in the Dashboard or via
extensions.mcp_servers here (see Create Agent — MCP request body); persisted shape on read is documented under Get Agent.MCP servers are auto-tested on save. Each entry in
extensions.mcp_servers is tested when you update the agent: reachable servers are stored with a fingerprint and discovered tools (green Connected badge in the Portal); unreachable servers are still stored but without a fingerprint (yellow Not tested badge), and the response includes a non-fatal warnings array ([{ "connection_name": "...", "message": "..." }]). Re-testing on update means an MCP server you keep in the payload retains its verified status instead of being reset.To validate a configuration before assigning it, use Test MCP Connection.Secrets are never returned. Responses from this and every other agent endpoint omit secret fields: integration passwords,
twilio.authToken, netsapiens.client_secret, calendar access/refresh tokens, and the SIP password inside sip_registration_data. Non-secret metadata (provider keys, usernames, accountSid, connected_at, calendar names) is still returned so you can see what’s configured.Update Behavior
- Only provided fields are updated; omitted fields retain their current values
- The
updated_attimestamp is automatically set to the current time - The
providerfield cannot be changed after creation
Feature Administration gating
When Feature Administration is enabled, updates are validated against the feature gates of the agent’s organization — including locks inherited from its reseller or partner. The API returns403 forbidden when the request:
-
configures an integration under
integrations(e.g.googleCalendar,twilio) that is locked for the organization — clearing one (setting it tonull) is always allowed; -
sets
ragEnabled: truewhile Knowledge Base (RAG) is locked; -
sets
warmTransferEnabled: truewhile Warm Transfer is locked; -
newly selects a cloned voice in
voiceSettings.voice_idwhile Custom Voices is locked — an agent already using a clone keeps it, and you can still switch away from it; -
sets a different
googlePlaceIdwhile Business Listing (Google Places) is locked. Re-sending the agent’s current Place ID is not blocked, so reading an agent and writing the whole object back keeps working for a locked organization. -
adds the
ns_send_smsorns_check_sms_repliestool toextensions.toolswhile SMS Messaging is locked. Only the addition is gated: re-sending tools the agent already has is not blocked, and removing an SMS tool always succeeds — a lock can never strand an SMS tool on an agent.
googlePlaceId: null, ragEnabled: false, warmTransferEnabled: false or integrations.<name>: null always succeeds — so a lock can never leave an agent with configuration you cannot remove, nor stop you editing an agent’s other fields.
The /v1/knowledge-bases endpoints apply the same gate and return 403 forbidden when Knowledge Base is locked for the organization. POST /v1/custom-voices returns 403 when Custom Voices is locked, and GET /v1/places/search returns 403 when Business Listing is locked for the account.