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

# Upsert agent

> Creates or updates an agent (current behavior).

## Notes

* Create a new agent or update existing one
* Auto-generates ID if not provided
* Returns operation type ("created" or "updated") in response


## OpenAPI

````yaml put /api/agents/upsert
openapi: 3.0.3
info:
  title: Zudu API
  description: >-
    Comprehensive REST API for LiveKit Backend - Call Management, Agent
    Configuration, and Real-time Communication Services
  version: 1.0.0
  contact:
    name: Zudu AI Team
    url: https://zudu.ai
    email: support@zudu.ai
  license:
    name: Proprietary
    url: https://zudu.ai/license
servers:
  - url: https://api.zudu.ai
    description: Production (Customer-facing)
security:
  - apiKey: []
    apiSecret: []
tags:
  - name: Agent Management
    description: Create and manage AI agents
  - name: Call Data Management
    description: Call records and history
  - name: Customer API Keys
    description: Manage API keys
  - name: Post-Call Webhooks
    description: Webhook configuration
  - name: phone-number-controller
    description: Phone numbers
  - name: batch-call-controller
    description: Batch calls
  - name: MCP Server Management
    description: MCP servers
  - name: Knowledge Base Management
    description: Knowledge bases
  - name: Call Analysis
    description: Call analysis
paths:
  /api/agents/upsert:
    put:
      tags:
        - Agent Management
      summary: Upsert agent
      description: >-
        Creates an agent if agent_id is missing or new; updates existing agent
        if agent_id is provided. Only agent_name is required; all other request
        body fields are optional. organization_id is taken from orgId header.
      operationId: upsertAgent
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  required:
                    - agent_name
                - $ref: '#/components/schemas/AgentData'
            example:
              agent_name: My Agent
        required: true
      responses:
        '200':
          description: Agent created or updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
                  error:
                    type: string
                    nullable: true
                  data:
                    type: object
                    properties:
                      operation:
                        type: string
                      agent_id:
                        type: string
                      organization_id:
                        type: string
                      agent:
                        $ref: '#/components/schemas/AgentData'
              example:
                message: Agent created successfully
                status: success
                error: null
                data:
                  operation: created
                  agent_id: agent_12345678-1234-1234-1234-123456789012
                  organization_id: org_xyz789
                  agent:
                    agent_id: agent_12345678-1234-1234-1234-123456789012
                    organization_id: org_xyz789
                    agent_name: My Agent
                    begin_message: Hello! How can I help you?
                    created_at: '2025-01-15T10:30:00'
                    updated_at: '2025-01-15T10:30:00'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
                  error:
                    type: string
                    nullable: true
                  data:
                    type: string
                    nullable: true
              example:
                message: Validation error
                status: error
                error: Agent name is required
                data: null
        '500':
          description: Failed to upsert agent
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
                  error:
                    type: string
                    nullable: true
                  data:
                    type: string
                    nullable: true
              example:
                message: Failed to upsert agent
                status: error
                error: Database connection failed
                data: null
components:
  schemas:
    AgentData:
      type: object
      properties:
        agent_id:
          type: string
        organization_id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        agent_name:
          type: string
        begin_message:
          type: string
        begin_message_variables:
          type: array
          items:
            type: string
        begin_message_delay_ms:
          type: integer
          format: int32
        test_variables:
          type: object
          additionalProperties:
            type: string
        webhook_url:
          type: string
        post_call_webhook_id:
          type: string
        end_call_after_silence_ms:
          type: integer
          format: int32
        max_call_duration_ms:
          type: integer
          format: int32
        take_turn_after_silence_seconds:
          type: number
          format: double
        timezone:
          type: string
        knowledge_base_ids:
          type: array
          items:
            type: string
        mcp_server_ids:
          type: array
          items:
            type: string
        rag_config:
          $ref: '#/components/schemas/RAGConfig'
        llm_config:
          $ref: '#/components/schemas/LLMConfig'
        stt_config:
          $ref: '#/components/schemas/STTConfig'
        tts_config:
          $ref: '#/components/schemas/TTSConfig'
        post_call_analysis_data:
          type: array
          items:
            $ref: '#/components/schemas/PostCallAnalysisData'
        post_call_analysis_model:
          type: string
        post_call_evaluation_criteria:
          type: array
          items:
            $ref: '#/components/schemas/PostCallEvaluationCriteria'
        widget_config:
          $ref: '#/components/schemas/WidgetConfig'
        access_info:
          type: object
          additionalProperties:
            type: object
        fetch_webhook_data:
          type: boolean
        use_rag:
          type: boolean
        integrations:
          type: array
          items:
            type: string
        text_only:
          type: boolean
        additional_languages:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalLanguageConfig'
    RAGConfig:
      type: object
      properties:
        chunks_to_retrieve:
          type: integer
          format: int32
        similarity_threshold:
          type: number
    LLMConfig:
      type: object
      properties:
        model:
          type: string
        provider:
          type: string
        system_message:
          type: string
        temperature:
          type: number
          format: double
        max_tokens:
          type: integer
          format: int32
        tools:
          type: array
          items:
            type: object
        system_message_variables:
          type: array
          items:
            type: string
    STTConfig:
      type: object
      properties:
        provider:
          type: string
        model:
          type: string
        language:
          type: string
        language_name:
          type: string
        use_realtime:
          type: boolean
    TTSConfig:
      type: object
      properties:
        provider:
          type: string
        model:
          type: string
        voice_id:
          type: string
        voice_speed:
          type: number
          format: double
        language:
          type: string
        language_name:
          type: string
        pronunciation_dictionary_ids:
          type: array
          items:
            type: string
        custom_api_url:
          type: string
        custom_api_key:
          type: string
        custom_secret_key:
          type: string
        custom_timeout:
          type: number
          format: double
        custom_streaming:
          type: boolean
        custom_sample_rate:
          type: integer
          format: int32
    PostCallAnalysisData:
      type: object
      properties:
        type:
          type: string
        name:
          type: string
        description:
          type: string
        examples:
          type: array
          items:
            type: string
    PostCallEvaluationCriteria:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    WidgetConfig:
      type: object
      properties:
        embed_code:
          type: string
        variant:
          type: string
        placement:
          type: string
        expandable:
          type: string
        avatar:
          $ref: '#/components/schemas/Avatar'
        feedback_mode:
          type: string
        bg_color:
          type: string
        text_color:
          type: string
        btn_color:
          type: string
        btn_text_color:
          type: string
        border_color:
          type: string
        focus_color:
          type: string
        border_radius:
          type: integer
          format: int32
        btn_radius:
          type: integer
          format: int32
        action_text:
          type: string
        start_call_text:
          type: string
        end_call_text:
          type: string
        expand_text:
          type: string
        listening_text:
          type: string
        speaking_text:
          type: string
        shareable_page_text:
          type: string
        shareable_page_show_terms:
          type: boolean
        terms_text:
          type: string
        terms_html:
          type: string
        terms_key:
          type: string
        show_avatar_when_collapsed:
          type: boolean
        disable_banner:
          type: boolean
        override_link:
          type: string
        mic_muting_enabled:
          type: boolean
        transcript_enabled:
          type: boolean
        text_input_enabled:
          type: boolean
        language_dropdown:
          type: boolean
        text_contents:
          $ref: '#/components/schemas/TextContents'
        styles:
          $ref: '#/components/schemas/Styles'
        language:
          type: string
        supported_language_overrides:
          type: array
          items:
            type: string
        language_presets:
          type: object
          additionalProperties:
            type: object
        text_only:
          type: boolean
        supports_text_only:
          type: boolean
        first_message:
          type: string
        show_default_powered_by:
          type: boolean
        custom_powered_by_text:
          maxLength: 255
          minLength: 0
          type: string
    AdditionalLanguageConfig:
      type: object
      properties:
        tts:
          $ref: '#/components/schemas/TTSLanguageConfig'
        stt:
          $ref: '#/components/schemas/STTLanguageConfig'
    Avatar:
      type: object
      properties:
        type:
          type: string
        color_1:
          type: string
        color_2:
          type: string
        custom_url:
          type: string
        url:
          type: string
    TextContents:
      type: object
      properties:
        main_label:
          type: string
        start_call:
          type: string
        new_call:
          type: string
        end_call:
          type: string
        mute_microphone:
          type: string
        change_language:
          type: string
        collapse:
          type: string
        expand:
          type: string
        copied:
          type: string
        accept_terms:
          type: string
        dismiss_terms:
          type: string
        listening_status:
          type: string
        speaking_status:
          type: string
        connecting_status:
          type: string
        input_label:
          type: string
        input_placeholder:
          type: string
        user_ended_conversation:
          type: string
        agent_ended_conversation:
          type: string
        conversation_id:
          type: string
        error_occurred:
          type: string
        copy_id:
          type: string
    Styles:
      type: object
      properties:
        base:
          type: string
        base_hover:
          type: string
        base_active:
          type: string
        base_border:
          type: string
        base_subtle:
          type: string
        base_primary:
          type: string
        base_error:
          type: string
        accent:
          type: string
        accent_hover:
          type: string
        accent_active:
          type: string
        accent_border:
          type: string
        accent_subtle:
          type: string
        accent_primary:
          type: string
        overlay_padding:
          type: integer
          format: int32
        button_radius:
          type: integer
          format: int32
        input_radius:
          type: integer
          format: int32
        bubble_radius:
          type: integer
          format: int32
        sheet_radius:
          type: string
        compact_sheet_radius:
          type: string
        dropdown_sheet_radius:
          type: string
    TTSLanguageConfig:
      type: object
      properties:
        provider:
          type: string
        model:
          type: string
        voice_id:
          type: string
        voice_speed:
          type: number
          format: double
        language:
          type: string
        language_name:
          type: string
        custom_api_url:
          type: string
        custom_api_key:
          type: string
        custom_secret_key:
          type: string
        custom_timeout:
          type: number
          format: double
        custom_streaming:
          type: boolean
        custom_sample_rate:
          type: integer
          format: int32
    STTLanguageConfig:
      type: object
      properties:
        provider:
          type: string
        model:
          type: string
        language:
          type: string
        language_name:
          type: string
        use_realtime:
          type: boolean
  securitySchemes:
    apiKey:
      type: apiKey
      description: API Key for MCP server and external service authentication
      name: X-API-KEY
      in: header
    apiSecret:
      type: apiKey
      description: API Secret for MCP server and external service authentication
      name: X-API-SECRET
      in: header

````