> ## Documentation Index > Fetch the complete documentation index at: https://docs.support.onclarity.com/llms.txt > Use this file to discover all available pages before exploring further. # Update an agent > Changes the fields you send and leaves every other field as it is. Configuration changes are saved to the agent's draft: live calls keep using the published version until you publish the draft (`POST .../agents/{id}/publish`). The agent's `name` and demo page settings are the exception and apply immediately. `agent_model_config` and other object-valued fields are replaced as a whole, not merged. Send `null` to clear a field that accepts it. The agent's type cannot change between Voice Assist and a voice type. Needs the publish permission, which organization API keys carry. ## OpenAPI ````yaml /api-reference/voice-openapi.json patch /v1/projects/{projectId}/agents/{id} openapi: 3.0.3 info: title: Clarity Voice API version: '1.0' description: Voice agents, outbound calls, conversations, campaigns, and evals. servers: - url: https://voice-api.onclarity.com security: - organizationApiKey: [] tags: - name: Projects description: >- The projects your organization owns. Every other resource lives in a project. - name: Agents description: Create, configure, version and publish voice agents. - name: Outbound calls description: Have a published agent phone a number now. - name: Conversations description: >- One record per call session, with its calls, recordings, transcripts and artifacts. - name: Calls description: The calls of a project, with their status, direction, timing and outcome. - name: Campaigns description: Outbound calling campaigns that phone a list of numbers on a schedule. - name: Eval suites description: >- Reusable sets of eval scenarios and test cases to measure an agent against. - name: Eval judges description: The LLM judges that score eval calls against your test cases. - name: Eval scenarios description: The simulated-caller scenarios of your eval suites. - name: Eval test cases description: The checks a judge applies to each eval call. - name: Eval submissions description: Run an eval suite against an agent and read the verdicts. paths: /v1/projects/{projectId}/agents/{id}: parameters: - $ref: '#/components/parameters/ProjectIdPath' - $ref: '#/components/parameters/AgentId' patch: tags: - Agents summary: Update an agent description: >- Changes the fields you send and leaves every other field as it is. Configuration changes are saved to the agent's draft: live calls keep using the published version until you publish the draft (`POST .../agents/{id}/publish`). The agent's `name` and demo page settings are the exception and apply immediately. `agent_model_config` and other object-valued fields are replaced as a whole, not merged. Send `null` to clear a field that accepts it. The agent's type cannot change between Voice Assist and a voice type. Needs the publish permission, which organization API keys carry. operationId: updateAgent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAgentRequest' example: greeting_message: Hello! You've reached Acme billing. What can I do for you today? max_call_duration_sec: 600 responses: '200': description: >- The agent after the change, in the same shape as `GET .../agents/{id}` (the draft, if one now exists). content: application/json: schema: $ref: '#/components/schemas/Agent' example: id: 3f0c6a52-8d7e-4b8a-9a43-0f2b5c1e9d11 name: Billing assistant project_id: 7b1d2e44-51c0-4f3a-8e5b-2a9c0d6f1e33 created_at: 1760000000000 updated_at: 1760090000000 agent_type: chained preferred_language: English (US) greeting_message: >- Hello! You've reached Acme billing. What can I do for you today? max_call_duration_sec: 600 demo: null '400': description: Another agent in the project already has this name. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: An agent with this name already exists in this project '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Your credential lacks the publish permission (`code: PUBLISH_CAPABILITY_REQUIRED`), or the agent is a Voice Assist agent and your organization does not have Voice Assist (`code: VOICE_ASSISTANT_REQUIRED`). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: The project or the agent does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- `agent_type` would switch between Voice Assist and a voice type (`code: AGENT_TYPE_BOUNDARY`) — create a new agent instead — or the demo page domain is already used by another agent. content: application/json: schema: $ref: '#/components/schemas/Error' '422': $ref: '#/components/responses/ValidationFailed' components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id AgentId: name: id in: path required: true schema: type: string description: Agent id schemas: UpdateAgentRequest: type: object description: >- Any subset of the agent's fields. Fields you omit keep their value; object-valued fields you send are replaced as a whole. Unknown fields are ignored. See `GET /v1/agents/config-schema` for the full format. properties: name: type: string minLength: 1 description: >- The agent's name, unique in the project. Applies immediately, without publishing. agent_type: type: string enum: - chained - realtime - assist description: >- `chained` (default): speech recognition, a language model and a voice in sequence. `realtime`: a speech-to-speech model. `assist`: a Voice Assist agent, which listens to a call handled by a person and suggests answers to them; it never speaks and needs the Voice Assist product. The type cannot change between `assist` and a voice type after creation. preferred_language: type: string nullable: true description: >- The conversation language, as a label from `GET .../agents/chained-options` (for example "English (US)", "Arabic (Najdi)"). It decides which speech providers and voices are available. For a bilingual agent it names the primary language. allow_language_switch: type: boolean description: Let the agent switch language when the caller does. greeting_message: type: string description: What the agent says when the call connects. goodbye_message: type: string nullable: true maxLength: 500 description: What the agent says before it hangs up. Empty means "Goodbye." silence_goodbye_message: type: string nullable: true maxLength: 500 description: >- What the agent says when it hangs up because the caller went silent. Empty means `goodbye_message`. tts_director_prompt: type: string nullable: true maxLength: 4000 description: 'Delivery notes for the voice: tone, pace, accent.' dialect_notes: type: string nullable: true maxLength: 4000 description: >- Vocabulary and register guidance for the agent's dialect, added to its instructions. dialect_notes_ref: type: string nullable: true description: >- The organization dialect-notes template the notes follow while unedited; `null` means the notes are the agent's own text. prompt_template_selections: type: array items: additionalProperties: true type: object description: >- Organization prompt templates appended to the instructions, in order. dynamic_prompt: type: boolean task_prompt_json: type: object nullable: true additionalProperties: true description: The agent's instructions (rich-text document). language_controls_enabled: type: boolean tools_instructions: type: object nullable: true additionalProperties: true description: Extra instructions on when to use the attached tools. vad_config: type: object nullable: true additionalProperties: true description: >- Voice activity detection tuning. See `GET /v1/agents/config-schema` for the full format. enable_engagement_checks: type: boolean description: Check in with the caller after a long silence. engagement_check_countdown_ms: type: integer nullable: true max_engagement_checks: type: integer nullable: true agent_model_config: type: object nullable: true additionalProperties: true description: >- Speech recognition, language model and voice settings (`asr_*`, `llm_*`, `tts_*` keys and turn-taking settings). Replaced as a whole on update. Omitted on create: the platform defaults. See `GET /v1/agents/config-schema` for the full format. Available providers, models and voices: `GET /v1/projects/{projectId}/agents/chained-options`. sidekick_reminders: type: array nullable: true items: {} post_tool_reminder: type: string nullable: true greeting_vad_config: type: object nullable: true additionalProperties: true description: Voice activity detection tuning while the greeting plays. greeting_interruptible: type: boolean description: Whether the caller can interrupt the greeting. noise_reduction_enabled: type: boolean description: Filter background noise from the caller's audio. memory: type: boolean description: >- Give the agent a digest of the caller's recent support tickets at the start of the call. memory_days: type: integer nullable: true description: >- How far back (days, 1–365) to look for the caller's tickets; `0` uses the caller's name and attributes only. memory_max_tickets: type: integer nullable: true description: At most this many recent tickets (1–10). summary_enabled: type: boolean description: Write a summary of each call when it ends. realtime_warnings: type: object additionalProperties: true nullable: true description: >- In-call warnings raised to supervisors while a call is in progress. See `GET /v1/agents/config-schema` for the full format. caller_sentiment: type: object additionalProperties: true nullable: true description: >- Live caller-sentiment tracking. See `GET /v1/agents/config-schema` for the full format. background_audio: type: object additionalProperties: true nullable: true description: >- Background ambience and typing sounds while the agent thinks. See `GET /v1/agents/config-schema` for the full format. start_tools: type: object additionalProperties: true nullable: true description: >- Tools run when the call starts, before the greeting. See `GET /v1/agents/config-schema` for the full format. language_switching: type: object additionalProperties: true nullable: true description: >- Language-switching policy and custom instruction texts. `null` means platform defaults. speech_normalization: type: object additionalProperties: true nullable: true description: >- How the agent speaks numbers, dates, amounts, links and acronyms. `{"enabled": true}` uses the defaults; `null` turns it off. ivr_navigation_enabled: type: boolean description: >- On outbound calls, navigate phone menus with keypad tones. Requires `amd_enabled`. amd_enabled: type: boolean description: >- On outbound calls, detect an answering machine and end the call without the script. livekit_region: type: string nullable: true description: >- Pin calls to a media region: `me`, `eu` or `us`. `null` picks the region nearest the caller. max_call_duration_sec: type: integer nullable: true minimum: 30 maximum: 3600 description: Hard limit on a call's length, in seconds (30–3600, default 3600). max_llm_tokens_per_call: type: integer nullable: true description: >- End the call once the conversation model has used this many tokens (1,000–5,000,000). `null` means no limit. task_groups: type: array nullable: true items: $ref: '#/components/schemas/TaskGroup' description: Structured tasks (workflows) the agent can run. builtin_tools: type: array items: type: string description: Built-in tools to enable, for example `lk_endCall` (hang up). silence_recovery_config: type: object additionalProperties: true nullable: true description: >- What to do when the caller goes silent: `max_nudges` (0–10), `timeout_s` (0.5–60) and the nudge `note`. multi_language: type: object additionalProperties: true nullable: true description: >- A second conversation language and the speech settings for it. `null` means a single-language agent. callbacks: type: object additionalProperties: true nullable: true description: >- Webhooks called by the platform. `on_finish` posts the call record to your URL when a call ends: `url`, `method` (`POST`, `PUT`, `PATCH`), `authentication` (`none`, `bearer` with `token`, `api_key` with `key` and `header`), `headers`, `timeout_ms`, `extra_fields`. demo: type: object additionalProperties: true nullable: true description: >- A public demo page for the agent: `domain` (lowercase letters, digits, hyphens), `user`, `password` (required the first time), `company_name`, `agent_role`, `logo_url`, `colors` (`background`, `primary`). `null` turns it off. The password is never returned. sheet_refs: type: object additionalProperties: type: string description: >- Google Sheet ids shared with every code tool of the agent, by argument name (for example `BOOKINGS_SHEET_ID`). Send `{}` to clear. prompt_field_whitelist: type: object additionalProperties: true nullable: true description: >- The call-context fields (caller number, custom fields passed when a call starts) the instructions may reference. `null` allows any. output_schema: type: object additionalProperties: true nullable: true description: >- Fields to extract from the conversation when the call ends, by name, each with `type`, `description`, `required`, `enum_values`. `null` turns extraction off. workflow_config: type: object additionalProperties: true nullable: true description: Rules the agent may apply at any point in the call (`global_rules`). assist_config: allOf: - $ref: '#/components/schemas/AssistConfig' nullable: true description: >- Voice Assist settings. Only for `agent_type: assist`; ignored for other types. Agent: type: object required: - id - name - project_id - created_at description: >- An agent and its configuration. Fields not listed here may also be present. See `GET /v1/agents/config-schema` for the full format. properties: id: type: string name: type: string project_id: type: string created_at: type: integer format: int64 description: Creation time, epoch milliseconds. updated_at: type: integer format: int64 nullable: true description: Last edit or publish, epoch milliseconds. agent_engine: type: string description: Always `livekit` for current agents. published_version_id: type: string nullable: true description: The live version's id. Present on list items. published_version_number: type: integer nullable: true description: The live version's number. Present on list items. has_draft: type: boolean description: An unpublished draft exists. Present on list items. draft_catalog_sync_only: type: boolean description: >- The draft exists only because a shared tool, dictionary or hold-phrase set used by this agent was edited elsewhere, not because the agent itself was edited. Present on list items. llm_refs: type: array description: >- The language models the agent runs on (live version, else the draft), with fallbacks. Present on list items. items: properties: model: type: string place: enum: - voice - voice_assist type: string provider: type: string tier: enum: - primary - fallback_1 - fallback_2 type: string required: - provider - model - tier type: object agent_type: type: string description: >- `chained` (default): speech recognition, a language model and a voice in sequence. `realtime`: a speech-to-speech model. `assist`: a Voice Assist agent, which listens to a call handled by a person and suggests answers to them; it never speaks and needs the Voice Assist product. The type cannot change between `assist` and a voice type after creation. preferred_language: type: string nullable: true description: >- The conversation language, as a label from `GET .../agents/chained-options` (for example "English (US)", "Arabic (Najdi)"). It decides which speech providers and voices are available. For a bilingual agent it names the primary language. allow_language_switch: type: boolean description: Let the agent switch language when the caller does. greeting_message: type: string description: What the agent says when the call connects. goodbye_message: type: string nullable: true maxLength: 500 description: What the agent says before it hangs up. Empty means "Goodbye." silence_goodbye_message: type: string nullable: true description: >- What the agent says when it hangs up because the caller went silent. Empty means `goodbye_message`. tts_director_prompt: type: string nullable: true maxLength: 4000 description: 'Delivery notes for the voice: tone, pace, accent.' dialect_notes: type: string nullable: true description: >- Vocabulary and register guidance for the agent's dialect, added to its instructions. dialect_notes_ref: type: string nullable: true description: >- The organization dialect-notes template the notes follow while unedited; `null` means the notes are the agent's own text. prompt_template_selections: type: array items: additionalProperties: true type: object description: >- Organization prompt templates appended to the instructions, in order. dynamic_prompt: type: boolean task_prompt_json: type: object nullable: true additionalProperties: true description: The agent's instructions (rich-text document). language_controls_enabled: type: boolean tools_instructions: type: object nullable: true additionalProperties: true description: Extra instructions on when to use the attached tools. vad_config: type: object nullable: true additionalProperties: true description: >- Voice activity detection tuning. See `GET /v1/agents/config-schema` for the full format. enable_engagement_checks: type: boolean description: Check in with the caller after a long silence. engagement_check_countdown_ms: type: integer nullable: true max_engagement_checks: type: integer nullable: true agent_model_config: type: object nullable: true additionalProperties: true description: >- Speech recognition, language model and voice settings (`asr_*`, `llm_*`, `tts_*` keys and turn-taking settings). Replaced as a whole on update. Omitted on create: the platform defaults. See `GET /v1/agents/config-schema` for the full format. Available providers, models and voices: `GET /v1/projects/{projectId}/agents/chained-options`. sidekick_reminders: type: array nullable: true items: {} post_tool_reminder: type: string nullable: true greeting_vad_config: type: object nullable: true additionalProperties: true description: Voice activity detection tuning while the greeting plays. greeting_interruptible: type: boolean description: Whether the caller can interrupt the greeting. noise_reduction_enabled: type: boolean description: Filter background noise from the caller's audio. memory: type: boolean description: >- Give the agent a digest of the caller's recent support tickets at the start of the call. memory_days: type: integer nullable: true description: >- How far back (days, 1–365) to look for the caller's tickets; `0` uses the caller's name and attributes only. memory_max_tickets: type: integer nullable: true description: At most this many recent tickets (1–10). summary_enabled: type: boolean description: Write a summary of each call when it ends. realtime_warnings: type: object additionalProperties: true nullable: true description: >- In-call warnings raised to supervisors while a call is in progress. See `GET /v1/agents/config-schema` for the full format. caller_sentiment: type: object additionalProperties: true nullable: true description: >- Live caller-sentiment tracking. See `GET /v1/agents/config-schema` for the full format. background_audio: allOf: - $ref: '#/components/schemas/BackgroundAudioConfig' nullable: true description: >- Background ambience and typing sounds while the agent thinks. See `GET /v1/agents/config-schema` for the full format. start_tools: allOf: - $ref: '#/components/schemas/StartToolsConfig' nullable: true description: >- Tools run when the call starts, before the greeting. See `GET /v1/agents/config-schema` for the full format. language_switching: type: object additionalProperties: true nullable: true description: >- Language-switching policy and custom instruction texts. `null` means platform defaults. speech_normalization: type: object additionalProperties: true nullable: true description: >- How the agent speaks numbers, dates, amounts, links and acronyms. `{"enabled": true}` uses the defaults; `null` turns it off. ivr_navigation_enabled: type: boolean description: >- On outbound calls, navigate phone menus with keypad tones. Requires `amd_enabled`. amd_enabled: type: boolean description: >- On outbound calls, detect an answering machine and end the call without the script. livekit_region: type: string nullable: true description: >- Pin calls to a media region: `me`, `eu` or `us`. `null` picks the region nearest the caller. max_call_duration_sec: type: integer nullable: true description: Hard limit on a call's length, in seconds (30–3600, default 3600). max_llm_tokens_per_call: type: integer nullable: true description: >- End the call once the conversation model has used this many tokens (1,000–5,000,000). `null` means no limit. task_groups: type: array nullable: true items: $ref: '#/components/schemas/TaskGroup' description: Structured tasks (workflows) the agent can run. builtin_tools: type: array items: type: string description: Built-in tools to enable, for example `lk_endCall` (hang up). silence_recovery_config: type: object additionalProperties: true nullable: true description: >- What to do when the caller goes silent: `max_nudges` (0–10), `timeout_s` (0.5–60) and the nudge `note`. multi_language: type: object additionalProperties: true nullable: true description: >- A second conversation language and the speech settings for it. `null` means a single-language agent. demo: type: object additionalProperties: true nullable: true description: The demo page settings, without the password. `null` when off. sheet_refs: type: object additionalProperties: type: string description: >- Google Sheet ids shared with every code tool of the agent, by argument name (for example `BOOKINGS_SHEET_ID`). Send `{}` to clear. prompt_field_whitelist: type: object additionalProperties: true nullable: true description: >- The call-context fields (caller number, custom fields passed when a call starts) the instructions may reference. `null` allows any. output_schema: type: object additionalProperties: true nullable: true description: >- Fields to extract from the conversation when the call ends, by name, each with `type`, `description`, `required`, `enum_values`. `null` turns extraction off. workflow_config: type: object additionalProperties: true nullable: true description: Rules the agent may apply at any point in the call (`global_rules`). assist_config: allOf: - $ref: '#/components/schemas/AssistConfig' nullable: true description: >- Voice Assist settings. Only for `agent_type: assist`; ignored for other types. Error: type: object required: - error additionalProperties: true properties: error: type: string description: Error message code: type: string description: >- A stable machine-readable reason, present on the refusals a client may branch on. Among them: `PUBLISH_CAPABILITY_REQUIRED` (403, the credential may not change what is live), `AGENT_NOT_PUBLISHED` (409, the agent has no published version yet), `AGENT_TYPE_NOT_DISPATCHABLE` (422, a Voice Assist agent named where an agent must place or take a call; the body carries `agent_type` and `agent_id`), `NOT_APPLICABLE_TO_AGENT_TYPE` (422, a voice-only setting written on a Voice Assist agent), `AGENT_TYPE_BOUNDARY` (409), `AGENT_TYPE_NOT_SUPPORTED` (400), `VOICE_ASSISTANT_REQUIRED` (403, the organization is not licensed for Voice Assist), `ORGANIZATION_UNAVAILABLE` (503) and `REGION_PROFILE_CONFLICT` (503). TaskGroup: type: object required: - task - description - fields - steps properties: task: type: string description: Task name (e.g. ticket_creation_workflow) description: type: string fields: additionalProperties: true type: object steps: type: array items: {} completion_message: type: string task_instruction: type: string description: >- When to run this task; used to derive workflow_instructions at runtime AssistConfig: type: object description: >- The assist block of an agent of type `assist`. Versioned with the agent: it is snapshotted into every version, replaced WHOLESALE on PATCH (an omitted key takes its default, never the stored value), and copied by clone / export / import. Null on every other agent type; a block sent for a voice agent is dropped. `kb_collection_id` and `kb_organization_id` are RESOLVED from the project's organization on every write — a client value is ignored. properties: company_context: type: string nullable: true default: null kb_enabled: type: boolean default: false kb_scope: $ref: '#/components/schemas/AssistKbScope' kb_collection_id: type: string nullable: true readOnly: true description: >- The organization's knowledge-base collection, resolved when the agent is saved with the knowledge base on; null when the organization has no articles yet or `kb_enabled` is false. kb_organization_id: type: integer nullable: true readOnly: true description: The organization the collection was resolved for. retrieval_query_chars: type: integer minimum: 200 maximum: 8000 default: 1500 retrieval_limit: type: integer minimum: 1 maximum: 20 default: 5 max_retries: type: integer minimum: 0 maximum: 5 default: 2 max_prompt_tokens: type: integer minimum: 512 nullable: true default: null description: >- Caps assist BELOW the provider's own window; the effective limit is the minimum of the two. BackgroundAudioConfig: type: object description: >- Office ambience looped under the call and an optional typing sound while the agent is thinking. Voice agents (chained and realtime) only: dropped from an assist agent's body. `null`, or both switches off, means none; the runtime config then carries no `background_audio` key. additionalProperties: false required: - ambient_enabled - ambient_sound - ambient_volume - thinking_enabled - thinking_volume properties: ambient_enabled: type: boolean ambient_sound: type: string enum: - office_ambience - crowded_room - city_ambience ambient_volume: type: number minimum: 0 maximum: 1 example: 0.3 thinking_enabled: type: boolean thinking_volume: type: number minimum: 0 maximum: 1 example: 0.5 StartToolsConfig: type: object description: >- Up to three http lookup tools the agent runs as soon as the call starts, before the first model turn. The greeting may speak the visible values they store as `{{ data["session."] }}`; it then waits up to `budget_ms` and speaks the fallback when any value is missing. `null`, or no tools, means none. Voice agents only: dropped from an assist agent's body. additionalProperties: false required: - tools properties: tools: type: array minItems: 1 maxItems: 3 items: type: object additionalProperties: false required: - name properties: name: type: string description: Name of an attached http tool with no required parameters. confirmed_read_only: type: boolean description: Required true for a tool whose method is not GET or HEAD. budget_ms: type: integer minimum: 500 maximum: 4000 default: 1500 fallback_greeting: type: string description: >- Required when the greeting uses start-tool values. Must not use them itself. fallback_greetings: type: object additionalProperties: type: string description: >- Per `multi_language.languages[].label`, for each language greeting that uses start-tool values. ValidationError: type: object description: >- A validation failure. `error` is a human-readable summary; `issues` (request validation) or `details` (agent configuration validation) locate each problem. properties: error: type: string message: type: string issues: type: array items: type: object properties: path: type: string description: Dotted path of the offending field code: type: string message: type: string details: type: array items: {} AssistKbScope: nullable: true description: >- Which articles retrieval may use. Only meaningful with `kb_enabled: true` (refused otherwise, 422). A scope naming collections outside the project's organization is refused at write time (Principle I). oneOf: - type: object required: - all_articles properties: all_articles: type: boolean enum: - true - type: object required: - article_ids properties: article_ids: type: array minItems: 1 items: minimum: 1 type: integer - type: object required: - collection_ids properties: collection_ids: type: array minItems: 1 items: type: string responses: Unauthorized: description: No credential was sent, or the API key is invalid or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid or revoked token ValidationFailed: description: >- The request body or query string failed validation. `error` lists each problem prefixed with the field it concerns; `issues` carries the same information per field. content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: error: 'name: String must contain at least 1 character(s)' issues: - path: name code: too_small message: String must contain at least 1 character(s) minimum: 1 securitySchemes: organizationApiKey: type: http scheme: bearer description: >- Your organization API key (it starts with `anek_org_`). The same key works on the Voice API and the Support API. See [Authentication](/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.