> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truedy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Partial Update Agent

> Partial update of an agent.



## OpenAPI

````yaml /api-reference/openapi.json patch /agents/{agent_id}
openapi: 3.1.0
info:
  title: Truedy API
  description: >-
    Truedy Public API. Authenticate with **Authorization: Bearer
    <your-api-key>** only. Get your API key from the [Truedy
    Dashboard](https://app.truedy.ai). Base URL:
    https://api.truedy.ai/api/public/v1
  version: 1.0.0
servers:
  - url: https://api.truedy.ai/api/public/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: Create, configure, test, retrieve, and delete voice agents.
  - name: Calls
    description: >-
      Create and manage outbound calls, recordings, transcripts, and call
      metadata.
  - name: Tools
    description: Create and manage agent tools.
  - name: Knowledge Bases
    description: Legacy Ultravox-backed knowledge bases and sources.
  - name: Knowledge Spaces
    description: >-
      Truedy-native RAG knowledge spaces, sources, ingestion jobs, and
      retrieval.
  - name: Voices
    description: Browse, import, clone, synchronize, preview, and delete voices.
  - name: Telephony
    description: Search, purchase, import, assign, unassign, and release phone numbers.
  - name: Batch Calls
    description: Create and manage outbound batch calling campaigns and their contacts.
  - name: Contacts
    description: Manage contact folders, contacts, imports, and exports.
  - name: Calls
    description: Start browser-based Web Calls with an active agent.
  - name: Widgets
    description: Manage New Frontend widget configurations and embed sessions.
  - name: Agent Templates
    description: Read active agent templates available to the organization.
  - name: Call Explainability
    description: Retrieve redacted structured evidence for a call.
  - name: Webhooks
    description: Manage organization webhook endpoints and delivery history.
  - name: Analytics
    description: Read organization dashboard and conversation intelligence analytics.
  - name: Exports
    description: Export organization calls and campaigns as CSV.
  - name: Workspaces
    description: Create and manage workspaces with an account-scoped master API key.
paths:
  /agents/{agent_id}:
    patch:
      tags:
        - Agents
      summary: Partial Update Agent
      description: Partial update of an agent.
      operationId: partial_update_agent_api_public_v1_agents__agent_id__patch
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            title: Agent Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAgentSingleResponse'
        '401':
          $ref: '#/components/responses/PublicUnauthorized'
        '403':
          $ref: '#/components/responses/PublicForbidden'
        '422':
          $ref: '#/components/responses/PublicValidationError'
        '429':
          $ref: '#/components/responses/PublicRateLimitExceeded'
        '500':
          $ref: '#/components/responses/PublicInternalError'
      security:
        - bearerAuth: []
components:
  schemas:
    AgentUpdate:
      properties:
        publish:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Publish
          default: true
        name:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: 'null'
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        voice_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice Id
        system_prompt:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: System Prompt
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
        tools:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tools
        knowledge_bases:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Knowledge Bases
        knowledge:
          anyOf:
            - $ref: '#/components/schemas/KnowledgeReference'
            - type: 'null'
          description: Explicit legacy or RAG Knowledge Base reference
        call_template_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Call Template Name
        greeting_settings:
          anyOf:
            - $ref: '#/components/schemas/GreetingSettings'
            - type: 'null'
        inactivity_messages:
          anyOf:
            - items:
                $ref: '#/components/schemas/InactivityMessage'
              type: array
            - type: 'null'
          title: Inactivity Messages
        temperature:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Temperature
        language_hint:
          anyOf:
            - type: string
            - type: 'null'
          title: Language Hint
        time_exceeded_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Time Exceeded Message
        recording_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Recording Enabled
        join_timeout:
          anyOf:
            - type: string
            - type: 'null'
          title: Join Timeout
        max_duration:
          anyOf:
            - type: string
            - type: 'null'
          title: Max Duration
        initial_output_medium:
          anyOf:
            - $ref: '#/components/schemas/MessageMedium'
            - type: 'null'
        vad_settings:
          anyOf:
            - $ref: '#/components/schemas/VADSettings'
            - type: 'null'
        built_in_config:
          anyOf:
            - $ref: '#/components/schemas/BuiltInConfig'
            - type: 'null'
        success_criteria:
          anyOf:
            - type: string
            - type: 'null'
          title: Success Criteria
        extraction_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Extraction Schema
        crm_webhook_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Crm Webhook Url
        crm_webhook_secret:
          anyOf:
            - type: string
            - type: 'null'
          title: Crm Webhook Secret
      type: object
      title: AgentUpdate
    PublicAgentSingleResponse:
      properties:
        data:
          $ref: '#/components/schemas/PublicAgentResponse'
          description: Agent object
        meta:
          $ref: '#/components/schemas/ResponseMeta'
          description: Request metadata
      type: object
      required:
        - data
        - meta
      title: PublicAgentSingleResponse
    KnowledgeReference:
      properties:
        kind:
          type: string
          enum:
            - legacy_ultravox
            - rag_v2
          title: Kind
        id:
          type: string
          maxLength: 200
          minLength: 1
          title: Id
      type: object
      required:
        - kind
        - id
      title: KnowledgeReference
    GreetingSettings:
      properties:
        first_speaker:
          $ref: '#/components/schemas/FirstSpeaker'
          description: 'Who speaks first: agent or user'
          default: agent
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          description: First message text (if agent speaks first)
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt
          description: Prompt for generating first message
        delay:
          anyOf:
            - type: string
            - type: 'null'
          title: Delay
          description: Delay before first message (e.g., '2s')
        uninterruptible:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Uninterruptible
          description: Whether first message is uninterruptible
          default: false
        fallback_delay:
          anyOf:
            - type: string
            - type: 'null'
          title: Fallback Delay
          description: Fallback delay if user doesn't speak
        fallback_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Fallback Text
          description: Fallback text if user doesn't speak
        fallback_prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Fallback Prompt
          description: Fallback prompt if user doesn't speak
      type: object
      title: GreetingSettings
    InactivityMessage:
      properties:
        duration:
          anyOf:
            - type: string
            - type: 'null'
          title: Duration
          description: Duration in string format (e.g., '30s')
        timeout_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Timeout Seconds
          description: Legacy dashboard timeout in seconds
        timeout:
          anyOf:
            - type: number
            - type: 'null'
          title: Timeout
          description: Compatibility alias for timeout_seconds
        message:
          type: string
          title: Message
          description: Message to play when inactive
        endBehavior:
          anyOf:
            - $ref: '#/components/schemas/EndBehavior'
            - type: 'null'
          description: Behavior when message finishes
          default: END_BEHAVIOR_UNSPECIFIED
      type: object
      required:
        - message
      title: InactivityMessage
    MessageMedium:
      type: string
      enum:
        - MESSAGE_MEDIUM_VOICE
        - MESSAGE_MEDIUM_TEXT
        - MESSAGE_MEDIUM_UNSPECIFIED
      title: MessageMedium
    VADSettings:
      properties:
        turn_endpoint_delay:
          anyOf:
            - type: string
            - type: 'null'
          title: Turn Endpoint Delay
          description: Turn endpoint delay (e.g., '500ms')
        minimum_turn_duration:
          anyOf:
            - type: string
            - type: 'null'
          title: Minimum Turn Duration
          description: Minimum turn duration (e.g., '200ms')
        minimum_interruption_duration:
          anyOf:
            - type: string
            - type: 'null'
          title: Minimum Interruption Duration
          description: Minimum interruption duration (e.g., '100ms')
        frame_activation_threshold:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Frame Activation Threshold
          description: Frame activation threshold (0-1)
      type: object
      title: VADSettings
    BuiltInConfig:
      properties:
        transfer:
          anyOf:
            - $ref: '#/components/schemas/CallTransferConfig'
            - type: 'null'
        hang_up:
          anyOf:
            - $ref: '#/components/schemas/HangUpConfig'
            - type: 'null'
        leave_voicemail:
          anyOf:
            - $ref: '#/components/schemas/VoicemailConfig'
            - type: 'null'
      type: object
      title: BuiltInConfig
    PublicAgentResponse:
      properties:
        id:
          type: string
          title: Id
          description: Unique agent identifier
        name:
          type: string
          title: Name
          description: Display name of the agent
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Optional description of the agent's purpose
        voice_id:
          type: string
          title: Voice Id
          description: ID of the voice used for this agent
        voice_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice Name
          description: Resolved voice display name
        system_prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: System Prompt
          description: System prompt / instructions for the agent
        model:
          type: string
          title: Model
          description: AI model identifier (e.g. ultravox-v0.7)
        tools:
          items:
            type: string
          type: array
          title: Tools
          description: List of tool IDs attached to the agent
        knowledge_bases:
          items:
            type: string
          type: array
          title: Knowledge Bases
          description: List of knowledge base IDs attached to the agent
        status:
          type: string
          title: Status
          description: 'Agent status: active, draft'
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the agent was created
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: When the agent was last updated
        greeting_settings:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Greeting Settings
          description: Greeting and first-speaker configuration
        inactivity_messages:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Inactivity Messages
          description: Messages played when the user is inactive
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
          description: LLM temperature (0-1)
        language_hint:
          anyOf:
            - type: string
            - type: 'null'
          title: Language Hint
          description: BCP47 language code
        time_exceeded_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Time Exceeded Message
          description: Message when max duration is exceeded
        recording_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Recording Enabled
          description: Whether call recording is enabled
        join_timeout:
          anyOf:
            - type: string
            - type: 'null'
          title: Join Timeout
          description: Timeout for the callee to join (e.g. 30s)
        max_duration:
          anyOf:
            - type: string
            - type: 'null'
          title: Max Duration
          description: Maximum call duration (e.g. 3600s)
        built_in_config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Built In Config
          description: Transfer, hang-up, and voicemail behavior configuration
        inbound_phone_numbers:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Inbound Phone Numbers
          description: Phone numbers assigned for inbound calls
        outbound_phone_numbers:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Outbound Phone Numbers
          description: Phone numbers assigned for outbound calls
      type: object
      required:
        - id
        - name
        - voice_id
        - model
        - status
        - created_at
        - updated_at
      title: PublicAgentResponse
      description: Agent resource as returned by the public API (no internal provider IDs).
    ResponseMeta:
      properties:
        request_id:
          type: string
          title: Request Id
          description: Unique request identifier for support and debugging
        ts:
          type: string
          format: date-time
          title: Ts
          description: Server timestamp when the response was generated
      type: object
      required:
        - request_id
        - ts
      title: ResponseMeta
      description: Metadata included in every API response.
    PublicApiErrorResponse:
      type: object
      required:
        - error
        - meta
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
            message:
              type: string
              description: Human-readable explanation.
            details:
              description: >-
                Structured, endpoint-specific details. Never rely on
                undocumented provider fields.
              type:
                - object
                - array
                - 'null'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
          description: Request correlation metadata.
      example:
        error:
          code: validation_error
          message: 'Missing required field: name'
          details:
            errors: []
        meta:
          request_id: req_01JEXAMPLE
          ts: '2026-08-21T00:00:00Z'
    FirstSpeaker:
      type: string
      enum:
        - agent
        - user
      title: FirstSpeaker
    EndBehavior:
      type: string
      enum:
        - END_BEHAVIOR_UNSPECIFIED
        - END_BEHAVIOR_HANG_UP_SOFT
        - END_BEHAVIOR_HANG_UP_STRICT
      title: EndBehavior
    CallTransferConfig:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: false
        type:
          type: string
          title: Type
          description: coldTransfer or warmTransfer
          default: coldTransfer
        phone_number:
          type: string
          title: Phone Number
          description: Destination phone number or SIP URI
          default: ''
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Name
          description: Display name for the tool
          default: transfer_to_human
        extraHeaders:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Extraheaders
        sipVerb:
          anyOf:
            - type: string
            - type: 'null'
          title: Sipverb
        from:
          anyOf:
            - type: string
            - type: 'null'
          title: From
        username:
          anyOf:
            - type: string
            - type: 'null'
          title: Username
        password:
          anyOf:
            - type: string
            - type: 'null'
          title: Password
        holdMusicUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Holdmusicurl
        inviteHeaders:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Inviteheaders
        referHeaders:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Referheaders
        transferSystemPromptTemplate:
          anyOf:
            - type: string
            - type: 'null'
          title: Transfersystemprompttemplate
        transferType:
          anyOf:
            - type: string
            - type: 'null'
          title: Transfertype
        context:
          anyOf:
            - type: string
            - type: 'null'
          title: Context
      type: object
      title: CallTransferConfig
    HangUpConfig:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: false
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
        strict:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Strict
      type: object
      title: HangUpConfig
    VoicemailConfig:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: false
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
        strict:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Strict
        result:
          anyOf:
            - type: string
            - type: 'null'
          title: Result
      type: object
      title: VoicemailConfig
  responses:
    PublicUnauthorized:
      description: Missing, malformed, expired, inactive, or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
    PublicForbidden:
      description: >-
        The API key is valid but the request is not permitted by its
        organization, IP allowlist, or scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
    PublicValidationError:
      description: The request is syntactically valid but fails endpoint validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
    PublicRateLimitExceeded:
      description: >-
        The API key or organization exceeded a configured request limit. Retry
        after the response headers/window indicate.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
          description: Seconds until retry is permitted, when available.
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Configured request limit.
        X-RateLimit-Remaining:
          schema:
            type: integer
            minimum: 0
          description: Remaining requests in the current window.
        X-RateLimit-Reset:
          schema:
            type: string
            format: date-time
          description: UTC time at which the current window resets.
    PublicInternalError:
      description: Unexpected server failure. Use meta.request_id when contacting support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Your API key. Send in the Authorization header as: Bearer <your-api-key>'

````