Skip to main content
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_taker
string
Agent activation status.Supported values:
  • active - Agent is available to receive calls
  • inactive - Agent is temporarily disabled
  • cancelled - Agent is permanently disabled
  • pending - Agent is pending activation
To switch between 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-6
string
Voice model for real-time speech
string
Speech-to-text model.Supported values: deepgram
string
Text-to-speech model.Supported values: cartesia, minimax
object
Voice configuration settings. Structure varies based on ttsModel:For Cartesia:
Cartesia voices also accept two optional fields:
A custom (cloned) voice_id requires model sonic-3 or sonic-3.5; set voiceSettings.model to one of these or the request is rejected with 400.
Most English Cartesia voices do not accept model or language overrides. Non-English voices (e.g. Spanish) require both:
For MiniMax:
Advanced Voice Timing (optional, applies to all TTS models):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.
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 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 null or "" 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.
Example: "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.
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.
Each entry is an object with:
  • 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 IPA phonemes; not used directly by the agent.
  • phonemes — The IPA phoneme string
Pass an empty array [] 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 (nameconnection_name, urlmcp_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 answers
  • during_call - Execute while call is active
  • after_call - Execute after call ends
See Webhooks documentation for complete details and examples.

Integrations

object
Third-party integration configurations. Supported provider keys: 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 null to clear that field.
  • Set a whole provider to null to remove the provider.
This example updates only Twilio’s fromNumber, clears its testToNumber, and removes the ModMed integration — everything else is untouched:
Provider fields (required when creating a new provider entry; partial updates only need to leave the stored object valid):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 twilio here does not auto-create the send_sms_via_twilio tool in extensions — 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_at timestamp is automatically set to the current time
  • The provider field 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 returns 403 forbidden when the request:
  • configures an integration under integrations (e.g. googleCalendar, twilio) that is locked for the organization — clearing one (setting it to null) is always allowed;
  • sets ragEnabled: true while Knowledge Base (RAG) is locked;
  • sets warmTransferEnabled: true while Warm Transfer is locked;
  • newly selects a cloned voice in voiceSettings.voice_id while Custom Voices is locked — an agent already using a clone keeps it, and you can still switch away from it;
  • sets a different googlePlaceId while 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_sms or ns_check_sms_replies tool to extensions.tools while 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.
    Re-sending an agent’s existing tools is not blocked by the lock, but do not build that request by echoing a GET response back verbatim. tools[].type accepts only the values in its enum (webhook, tool, notification, function, transfer_agent, end_of_call_action), which exclude the internal type a GET returns for UCaaS tools such as these. Such a request is rejected with 400 by schema validation before any gate runs — a pre-existing limitation of this endpoint, unrelated to Feature Administration. Send only the fields you intend to change.
Only a genuine change is gated. Clearing a value is never blocked — sending 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.