---
title: "Update agent conversation copy"
method: PATCH
path: "/agents/{agent_id}"
tags: ["Agents"]
---

# Update agent conversation copy

`PATCH /agents/{agent_id}`

Update the conversation copy of a specific agent.

    Updatable fields (partial update — only the fields you send are changed):
    - `prompt_instructions`: the custom instructions driving the agent behaviour
    - `first_message`: the message the agent says when the conversation starts

    Sending an explicit `null` (or a blank string) clears the field, so the
    agent falls back to its default behaviour. Omitting a field leaves it
    untouched. An empty body is rejected with 400.

    Call-routing configuration (voice, AI provider, phone numbers, agent type)
    is intentionally NOT updatable from the External API: changing it can break
    live calls. Use the dashboard for those fields.

    Unknown fields are rejected with 400, so a typo (or an attempt to change a
    read-only field) never looks like a successful update.

    The agent must belong to your organization. Attempting to update an agent
    from another organization will return 404.

    Authentication:
    - API key with READ_WRITE permission, or
    - OAuth access token granted the `agents:write` scope

## Path parameters

- `agent_id` string, uuid, required

## Request body

- object — Partial update of an agent's conversation copy. Only the fields present in the request body are changed. Sending an explicit ``null`` clears the field (the agent falls back to its default behaviour); omitting the field leaves it untouched.
  - `prompt_instructions` string, nullable — Custom prompt instructions driving the agent's behaviour during a call. Send null to clear them and fall back to the default prompt.
  - `first_message` string, nullable — Initial message the agent says when the conversation starts. Send null to clear it (the agent opens the conversation on its own).

## Response `200`

Successfully updated the agent

- object
  - `ok` boolean, required
  - `data` object, nullable — Schema for agent response.
    - `id` string, uuid, required
    - `organization_id` string, uuid, required
    - `name` string, required
    - `agent_type` 'inbound' | 'outbound' | 'meta', required — Dynamically generated from the Agent model's AgentTypeEnum.
    - `is_active` boolean, required
    - `selected_voice` string, uuid, nullable, required
    - `verified_caller_id` string, uuid, nullable, required
    - `prompt_instructions` string, nullable, required
    - `first_message` string, nullable, required
    - `disable_first_message_interruptions` boolean, required
    - `first_message_delay_seconds` number, required
    - `max_call_duration_minutes` integer, required
    - `is_call_recording_enabled` boolean, required
    - `is_transcript_saving_enabled` boolean, required — Whether to save call transcripts for this agent
    - `include_past_calls_in_context` boolean — Whether to inject summaries of the caller's recent past calls into the AI context
    - `past_calls_count` integer — How many of the caller's most recent past calls to include in context (1-5)
    - `auto_hide_abusive_comments` boolean, required — Meta agents only: automatically hide clearly-abusive/spam comments instead of replying.
    - `comment_moderation_instructions` string, nullable — Meta agents only: business-specific rules describing which comments to hide vs keep.
    - `comment_reply_instructions` string, nullable — Meta agents only: custom prompt instructions for PUBLIC comment replies. Falls back to prompt_instructions (the DM prompt) when empty.
    - `dm_reply_mode` 'agent' | 'workflow' | 'off' — Meta agents only: who answers inbound DMs — 'agent' (always-on auto-reply), 'workflow' (a Meta DM workflow owns replies), or 'off' (no DM auto-reply).
    - `dm_debounce_seconds` integer — Meta agents only: seconds to wait after the customer's last DM before replying once to the whole burst (0-1800, 0 = instant per-message reply).
    - `user_silence_warning_seconds` integer, required
    - `user_silence_hangup_seconds` integer, required
    - `user_silence_prompt_message` string, required
    - `default_language` string, nullable, required
    - `supported_languages` string[], nullable, required
    - `ai_temperature` number, nullable — AI model temperature (0.0-2.0)
    - `ai_speed` number, nullable — AI speech speed multiplier (0.25-1.5)
    - `turn_detection_mode` string, nullable — Turn detection mode: 'semantic_vad' or 'server_vad'
    - `vad_eagerness` string, nullable — VAD eagerness level: 'auto', 'low', 'medium', 'high'
    - `vad_threshold` number, nullable — VAD activation threshold (0.0-1.0)
    - `vad_silence_duration_ms` integer, nullable — Duration of silence in ms to detect end of speech (100-2000)
    - `reasoning_effort` string, nullable — Reasoning effort: 'none' (fast) or 'high' (thinks before replying). Grok-only.
    - `call_summary_custom_prompt` string, nullable — The agent's post-call summary instructions; null keeps the standard default (call_summary_default_prompt)
    - `call_summary_language` string, nullable — ISO 639-1 language the post-call summary is written in (falls back to the agent's default language)
    - `call_summary_default_prompt` string — The standard post-call summary instructions, pre-filled into the editor; edit to customize, or leave as-is to keep using the live default. Read-only (same for every agent).
    - `gemini_backend` string, nullable — Gemini backend: 'vertex_ai' (stable) or 'google_ai_studio' (preview)
    - `ai_provider` string, nullable, required
    - `ai_provider_display_name` string, nullable, required
    - `agent_type_display_name` string, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `voice` object, nullable
      - `id` string, uuid, required
      - `custom_name` string, required
      - `description` string, required
      - `file` object, required — Response model for retrieving file details.
        - `file_name` string, required
        - `content_size` integer, required
        - `content_type` string, required
        - `url` string, nullable, required
      - `ai_provider` string, required
      - `language` string, nullable — ISO 639-1 language tag of the voice (e.g. 'it', 'ar'); null if multilingual
  - `meta` object, nullable
    - `limit` integer, required
    - `offset` integer, required
    - `total_items` integer, required
  - `error` object, nullable
    - `code` string, required
    - `message` string, required
    - `details` union
      - string
      - string[]
      - object

## Other responses

- `400` — Invalid request data
- `401` — Invalid or missing API key
- `403` — Insufficient permissions
- `404` — Resource not found
- `409` — The update conflicts with another agent
- `500` — The update could not be persisted

---

[API](https://skmtc.net/yourang/apis/yourang-ai-external-api-v1.md) · [All operations](https://skmtc.net/yourang/apis/yourang-ai-external-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yourang/yourang-ai-external-api-v1/versions/49680ee64400/schema)