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

# Update agent

> Patch metadata fields (name, description, categories, avatarUrl). Use null to clear nullable fields. Status transitions are NOT done via PATCH — use publish.



## OpenAPI

````yaml /api-reference/openapi.json patch /public/api/v1/agents/{agentPublicId}
openapi: 3.1.0
info:
  contact:
    email: support@gennia.ai
    name: Gennia Support
    url: https://gennia.ai
  description: >-
    Workspace-scoped API authenticated via workspace API key (header `X-Api-Key:
    gsk_...` or `Authorization: Bearer gsk_...`).
  title: Gennia Public API
  version: v1
servers:
  - description: Production
    url: https://api.gennia.ai
security:
  - workspaceApiKey: []
tags:
  - description: Slash commands available inside the agent chat.
    name: Agent Commands
  - description: Link skills to an agent.
    name: Agent Skills
  - description: Read/rename/delete workspace knowledge sources.
    name: Knowledge Sources
  - description: Link knowledge sources to an agent.
    name: Agent Knowledge Sources
  - description: Workspace CRUD for HTTP/DB/Custom tools.
    name: HTTP Tools
  - description: Read/write the agent's model selection + capabilities.
    name: Agent Model
  - description: Discover trigger types available for Native MCP toolkits.
    name: Native MCP Triggers
  - description: Discover and toggle capability features.
    name: Agent Features
  - description: Hub access settings.
    name: Hub Access
  - description: Read conversation history and delete conversations.
    name: Conversations
  - description: Send messages to a published agent.
    name: Messages
  - description: Workspace CRUD for External MCP servers.
    name: External MCPs
  - description: Hub billing — plans, coupons, credit packages.
    name: Billing
  - description: External links shown in the hub menu.
    name: Hub External Links
  - description: Link Native MCP (Composio) instances to an agent.
    name: Agent Native MCPs
  - description: Manage AI agents in the workspace bound to the API key.
    name: Agents
  - description: Read published version snapshots and restore.
    name: Agent Versions
  - description: Read/rename/delete workspace skills.
    name: Skills
  - description: Manage hub end-customers (client workspaces).
    name: Clients
  - description: Hub domain (subdomain) management.
    name: Hub Domain
  - description: Read/write the agent's prompt context.
    name: Agent Prompt
  - description: Scheduled / trigger-based runs of an agent.
    name: Agent Automations
  - description: Link HTTP/DB/Custom tools to an agent.
    name: Agent HTTP Tools
  - description: Hub identity, branding, logos and overall configuration.
    name: Hub
  - description: Discover AI models available to this workspace.
    name: AI Models
  - description: Discover channel types and their config schemas.
    name: Channel Types
  - description: Connect agents to messaging surfaces.
    name: Agent Channels
  - description: Link workspace-registered External MCP servers to an agent.
    name: Agent External MCPs
  - description: Workspace-scoped public API (API key authentication)
    name: Public API
  - description: Dynamic-prompt variable definitions.
    name: Agent Variables
  - description: Link sub-agents as delegation targets.
    name: Agent Sub-agents
paths:
  /public/api/v1/agents/{agentPublicId}:
    patch:
      tags:
        - Agents
      summary: Update agent
      description: >-
        Patch metadata fields (name, description, categories, avatarUrl). Use
        null to clear nullable fields. Status transitions are NOT done via PATCH
        — use publish.
      operationId: updateAgent
      parameters:
        - in: path
          name: agentPublicId
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePublicAgentDTO'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAgentDTO'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAgentDTO'
          description: Validation failed / unknown field
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAgentDTO'
          description: Missing or invalid API key
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAgentDTO'
          description: Agent not found in this workspace
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAgentDTO'
          description: Agent name already taken in this workspace
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAgentDTO'
          description: Avatar fetch failed
      security:
        - workspaceApiKey: []
components:
  schemas:
    UpdatePublicAgentDTO:
      description: >-
        Body for updating an agent. All fields are independently optional;
        JsonNullable fields are tri-state (omit, set, or clear with null).
        Unknown fields are rejected with 400.
      properties:
        aiModelPublicId:
          $ref: '#/components/schemas/JsonNullableUUID'
          description: Public ID of the AI model to use.
          example: 9c3a4d22-1a8d-4b3f-9b1e-7a0f0c4f3e21
        audioListeningEnabled:
          $ref: '#/components/schemas/JsonNullableBoolean'
          description: Enable audio listening (speech-to-text).
          example: false
        audioResponseEnabled:
          $ref: '#/components/schemas/JsonNullableBoolean'
          description: Enable audio responses (text-to-speech).
          example: false
        avatarUrl:
          $ref: '#/components/schemas/JsonNullableString'
          description: New avatar URL (http or https).
          example: https://cdn.example.com/avatars/support-bot.png
        categories:
          description: >-
            Up to 10 free-form category tags. Each tag must not exceed 100
            characters.
          example:
            - support
            - billing
          items:
            maxLength: 100
            minLength: 0
            type: string
          maxItems: 10
          minItems: 0
          type: array
        description:
          $ref: '#/components/schemas/JsonNullableString'
          description: New short description shown in the agent catalogue.
          example: Answers questions about billing, refunds and account access.
        dynamicPromptEnabled:
          $ref: '#/components/schemas/JsonNullableBoolean'
          description: Enable dynamic prompt variables for this agent.
          example: true
        followUpAfterHours:
          $ref: '#/components/schemas/JsonNullableInteger'
          description: Hours of inactivity before the first follow-up is sent (0..720).
          example: 24
        followUpBusinessHoursEnd:
          $ref: '#/components/schemas/JsonNullableLocalTime'
          description: End of the business-hours window for follow-ups.
          example: '18:00:00'
        followUpBusinessHoursStart:
          $ref: '#/components/schemas/JsonNullableLocalTime'
          description: Start of the business-hours window for follow-ups.
          example: '09:00:00'
        followUpEnabled:
          $ref: '#/components/schemas/JsonNullableBoolean'
          description: Enable proactive follow-up messages after inactivity.
          example: false
        followUpInactivityMinutes:
          $ref: '#/components/schemas/JsonNullableInteger'
          description: Minutes of inactivity considered idle for follow-up logic (1..1440).
          example: 30
        followUpIntervalMinutes:
          $ref: '#/components/schemas/JsonNullableInteger'
          description: Minutes between follow-up attempts (1..10080).
          example: 60
        followUpMaxAttempts:
          $ref: '#/components/schemas/JsonNullableInteger'
          description: Maximum number of follow-up attempts per conversation (1..10).
          example: 3
        followUpPrompt:
          $ref: '#/components/schemas/JsonNullableString'
          description: Prompt used to generate follow-up messages.
          example: Politely check whether the customer still needs help.
        genuiEnabled:
          $ref: '#/components/schemas/JsonNullableBoolean'
          description: Enable generative UI responses.
          example: false
        longTermMemoryEnabled:
          $ref: '#/components/schemas/JsonNullableBoolean'
          description: Enable persistent long-term memory across conversations.
          example: false
        memoryCustomInstructions:
          $ref: '#/components/schemas/JsonNullableString'
          description: Custom instructions guiding what the agent should remember.
          example: Remember customer preferences and prior issues.
        messageDelayEnabled:
          $ref: '#/components/schemas/JsonNullableBoolean'
          description: Insert artificial delay between messages to feel more natural.
          example: false
        messageDelayType:
          $ref: '#/components/schemas/JsonNullableMessageDelayType'
          description: Strategy used to compute the inter-message delay.
        messageSplittingEnabled:
          $ref: '#/components/schemas/JsonNullableBoolean'
          description: Split long responses into multiple messages.
          example: true
        name:
          description: New display name of the agent.
          example: Support Bot
          maxLength: 150
          minLength: 1
          type: string
        sandboxEnabled:
          $ref: '#/components/schemas/JsonNullableBoolean'
          description: Enable the sandbox (computer) tool for this agent.
          example: false
        systemPrompt:
          $ref: '#/components/schemas/JsonNullableString'
          description: New system prompt content.
          example: You are a friendly support agent for Acme Corp.
        temperature:
          $ref: '#/components/schemas/JsonNullableFloat'
          description: Sampling temperature between 0.0 and 2.0.
          example: 0.7
        thinkingEffort:
          $ref: '#/components/schemas/JsonNullableString'
          description: Reasoning effort level when thinking is enabled.
          enum:
            - low
            - medium
            - high
          example: medium
        thinkingEnabled:
          $ref: '#/components/schemas/JsonNullableBoolean'
          description: Enable extended thinking for reasoning-capable models.
          example: true
        ttsVoice:
          $ref: '#/components/schemas/JsonNullableString'
          description: TTS voice identifier used when audio responses are enabled.
          example: alloy
        webSearchEnabled:
          $ref: '#/components/schemas/JsonNullableBoolean'
          description: Enable the web-search tool for this agent.
          example: true
      type: object
    PublicAgentDTO:
      description: Agent metadata + editable-state configuration.
      properties:
        aiModelName:
          description: Selected AI model display name; null when not yet configured.
          type: string
        aiModelPublicId:
          description: Selected AI model public ID; null when not yet configured.
          format: uuid
          type: string
        audioListeningEnabled:
          type: boolean
        audioResponseEnabled:
          type: boolean
        avatarUrl:
          type: string
        categories:
          items:
            type: string
          type: array
        createdAt:
          format: date-time
          type: string
        description:
          type: string
        draftVersionNumber:
          format: int32
          type: integer
        dynamicPromptEnabled:
          type: boolean
        followUpAfterHours:
          format: int32
          type: integer
        followUpBusinessHoursEnd:
          example: '14:30:00'
          type: string
        followUpBusinessHoursStart:
          example: '14:30:00'
          type: string
        followUpEnabled:
          type: boolean
        followUpInactivityMinutes:
          format: int32
          type: integer
        followUpIntervalMinutes:
          format: int32
          type: integer
        followUpMaxAttempts:
          format: int32
          type: integer
        followUpPrompt:
          type: string
        genuiEnabled:
          type: boolean
        hasExternalChannel:
          type: boolean
        hasUnpublishedChanges:
          description: True if the editable state differs from the published snapshot.
          type: boolean
        longTermMemoryEnabled:
          type: boolean
        memoryCustomInstructions:
          type: string
        messageDelayEnabled:
          type: boolean
        messageDelayType:
          description: Delay tier when messageDelayEnabled=true.
          enum:
            - LOW
            - MEDIUM
            - HIGH
            - RANDOM
          type: string
        messageSplittingEnabled:
          type: boolean
        name:
          type: string
        publicId:
          format: uuid
          type: string
        publishedVersionNumber:
          format: int32
          type: integer
        sandboxEnabled:
          type: boolean
        status:
          enum:
            - draft
            - active
            - inactive
            - archived
          type: string
        systemPrompt:
          type: string
        temperature:
          format: float
          type: number
        thinkingEffort:
          description: Thinking effort tier.
          enum:
            - low
            - medium
            - high
          type: string
        thinkingEnabled:
          type: boolean
        ttsVoice:
          type: string
        updatedAt:
          format: date-time
          type: string
        webSearchEnabled:
          type: boolean
      type: object
    JsonNullableUUID:
      properties:
        present:
          type: boolean
      type: object
    JsonNullableBoolean:
      properties:
        present:
          type: boolean
      type: object
    JsonNullableString:
      properties:
        present:
          type: boolean
      type: object
    JsonNullableInteger:
      properties:
        present:
          type: boolean
      type: object
    JsonNullableLocalTime:
      properties:
        present:
          type: boolean
      type: object
    JsonNullableMessageDelayType:
      properties:
        present:
          type: boolean
      type: object
    JsonNullableFloat:
      properties:
        present:
          type: boolean
      type: object
  securitySchemes:
    workspaceApiKey:
      in: header
      name: X-Api-Key
      type: apiKey

````