Skip to main content
PATCH
Update an agent

Authorizations

​
Authorization
string
header
required

Use a Bearer token to access these API endpoints. Example: "Bearer {your-token}"

Path Parameters

​
uuid
string<uuid>
required

Body

application/json

Full agent configuration. Fields fall into three groups: (1) identity (name, company, role) — what the agent IS; (2) behavior prompts (objective, tone, behavior_guidelines, custom_prompt, negative_response) — HOW the runtime AI thinks and talks; (3) capabilities (settings.voice, settings.text, guidelines, notes, procedures, training, appointments, routing_rules, guard_rules) — WHAT the agent can do. For an agent to actually behave well at runtime, populate at least: name, role, objective, tone, behavior_guidelines, language, plus the relevant settings.voice OR settings.text block. Skipping prompt fields produces hollow agents that respond generically.

​
name
string
required

Required. Internal label for this agent — used in dashboards, logs, and as the default inbound_first_message 'this is X' name. Customers should recognize the brand from the name.

Example:

"Volvo Cagliari Service Agent"

​
description
string | null

Internal one-paragraph description of what this agent does. Helps your team understand the agent's purpose at a glance — not used by the runtime AI, but useful when AI-builder agents (via MCP) decide which existing agent to update vs create new.

Example:

"Inbound voice agent for Volvo Cagliari service appointments. Books service slots, qualifies vehicle issues, escalates warranty cases."

​
company_name
string | null

Brand the agent represents. The runtime AI references this when introducing itself.

Example:

"Volvo Cagliari"

​
role
string | null

Strong recommendation. Concrete one-sentence role definition the runtime AI reads as system prompt context. Specific roles produce focused agents — 'Inbound service scheduler for a Volvo dealership' beats 'sales agent'. Without this set, the agent has no identity and answers everything generically.

Example:

"Inbound service appointment scheduler for a Volvo dealership in Cagliari."

​
objective
string | null

Strong recommendation. The single primary outcome the agent should drive every conversation toward. Should be measurable. Without an objective the agent talks but doesn't close.

Example:

"Book a service appointment for the customer's vehicle. Capture: VIN or license plate, preferred date, type of service."

​
tone
string | null

Strong recommendation. Voice and style guide. Determines word choice, formality, and rapport tactics.

Example:

"Warm, professional, slightly formal. Use the customer's name. Avoid jargon — explain technical terms in plain language."

​
behavior_guidelines
string | null

Critical. Free-form instructions that shape how the runtime AI handles edge cases, escalations, and brand-sensitive moments. Treat this as the agent's SOP. Empty = the agent has no rules.

Example:

"Always confirm vehicle details before booking. Never quote prices for warranty repairs — escalate to a human. If the customer is upset about a previous service, acknowledge the frustration first, then offer to connect them with a manager."

​
company_service
string | null

What the company actually sells/offers. Helps the agent stay on-topic and recognize off-domain questions.

Example:

"Volvo vehicle service: maintenance, repairs, warranty work, accessories, pickup/delivery."

​
topic
string | null

The narrow conversational topic the agent should stay within. Anything off-topic should trigger handover or polite redirect.

Example:

"Service appointment booking and vehicle maintenance questions."

​
length_detail
string | null

How long replies should be. Voice agents need short crisp turns; text agents can be longer.

Example:

"Keep replies under 25 words for voice; under 200 characters for text. One question at a time."

​
interest_of_product
string | null

Product-marketing context the agent can use to answer questions about the offering. Useful for sales-oriented agents.

​
negative_response
string | null

What the agent does when the conversation goes negative. Without this set, the agent may apologize excessively or escalate inappropriately.

Example:

"If the customer becomes hostile or uses profanity, stay calm, do not escalate emotionally, and offer to transfer to a human supervisor."

​
status
enum<string> | null

Lifecycle state. ready = agent is live and reachable; paused = agent exists but won't accept new conversations.

Available options:
pending,
ready,
in_progress,
paused,
completed
​
custom_prompt
string | null

Advanced. Raw additional system-prompt text appended to whatever the runtime AI assembles from the structured fields above. Use only when the structured fields can't express what you need — most cases are better served by tightening behavior_guidelines or adding procedures.

​
language
string | null

ISO 639-1 code for the agent's primary language. Affects both voice (TTS/STT) and text (LLM language). Match settings.voice.voice_profile.language.

Example:

"en"

​
speed
enum<string> | null

Voice playback speed. Use fast for repeat customers who know the flow; default normal.

Available options:
normal,
fast
​
timezone
string | null

IANA timezone. Used for working hours, appointment booking, and follow-up scheduling.

Example:

"America/New_York"

​
appointment_scheduling_enabled
boolean | null

Master switch for appointment booking. When false, all schedule_assignments are inert.

​
appointment_scheduling_randomly
boolean | null

When multiple primary schedule_assignments match, pick randomly instead of by priority. Use for load balancing across human staff.

​
custom_llm_url
string | null

Optional override pointing at a custom LLM endpoint instead of the default. Advanced — reach out before using.

​
settings
object

Channel-specific behavior. Populate voice for phone agents, text for messaging agents — most agents need only one. See AgentVoiceSettings / AgentTextSettings for full field details.

​
guidelines
object[]

Ordered list of short do's and don'ts the runtime AI follows on every turn. Use for short, atomic rules. For complex multi-step workflows use procedures instead.

​
notes
object[]

Free-form context the runtime AI keeps available throughout conversations — product facts, business rules, edge cases. Use for reference knowledge that doesn't fit a guideline or procedure.

​
procedures
object[]

Multi-step workflows the agent can execute end-to-end (e.g. 'book a service appointment', 'process a refund'). Each procedure has ordered steps. The runtime AI walks the steps when the relevant intent is detected.

​
training
object[]

Few-shot Q&A pairs. The runtime AI uses these as examples of correct responses to common questions. Add 5-15 high-impact pairs covering frequent customer questions.

​
appointments
object
​
routing_rules
object[]

IVR-style transfer rules. The agent uses these to forward calls to extensions, phones, or other agents based on detected intent.

​
guard_rules
object[]

Compliance / safety / escalation triggers. Force the agent to forward or end the conversation when defined situations arise.

Response

Agent updated successfully

​
success
boolean

Indicates whether the request completed successfully. True for successful responses; false for documented error responses.

​
message
string

Human-readable response message. Safe to display in logs or simple client notifications; use structured fields for program logic.

​
data
object