# Update Agent

> Update an agent's name, workflow definition, or configuration

`PUT /api/v1/workflow/{workflow_id}`

All fields are optional — only include the fields you want to change. Updating `workflow_definition` creates a new versioned definition while preserving the history of previous versions.

## OpenAPI

````yaml api-reference/openapi.json put /api/v1/workflow/{workflow_id}
openapi: 3.1.0
info:
  title: Menace Voice API
  description: API for Menace Voice agents
  version: 1.0.0
servers:
  - url: https://voice.menaceui.com
    description: Production
  - url: http://localhost:8000
    description: Local development
paths:
  /api/v1/workflow/{workflow_id}:
    put:
      tags:
        - main
      summary: Update Workflow
      description: >-
        Update an existing workflow.


        Args:
            workflow_id: The ID of the workflow to update
            request: The update request containing the new name and workflow definition

        Returns:
            The updated workflow

        Raises:
            HTTPException: If the workflow is not found or if there's a database error
      operationId: update_workflow_api_v1_workflow__workflow_id__put
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: integer
            title: Workflow Id
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            title: Authorization
        - name: X-API-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWorkflowRequest"
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowResponse"
        "404":
          description: Not found
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
      x-sdk-method: update_workflow
      x-sdk-description: Update a workflow's name and/or definition. Saves as a new draft.
components:
  schemas:
    AmbientNoiseConfigurationDefaults:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: false
        volume:
          type: number
          title: Volume
          default: 0.3
      additionalProperties: true
      type: object
      title: AmbientNoiseConfigurationDefaults
    CallDispositionCodes:
      properties:
        disposition_codes:
          items:
            type: string
          type: array
          title: Disposition Codes
          default: []
      type: object
      title: CallDispositionCodes
    CallDispositionOption:
      properties:
        code:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[A-Za-z][A-Za-z0-9_-]*$
          title: Code
          description: Stable code recorded when this outcome is selected.
        description:
          type: string
          maxLength: 1000
          minLength: 1
          title: Description
          description: Business criteria for selecting this disposition.
      type: object
      required:
        - code
        - description
      title: CallDispositionOption
      description: One business outcome the terminal classifier may select.
    ExternalPBXFieldMapping:
      properties:
        context_path:
          type: string
          maxLength: 255
          minLength: 1
          title: Context Path
        destination_field:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]{0,63}$
          title: Destination Field
      type: object
      required:
        - context_path
        - destination_field
      title: ExternalPBXFieldMapping
      description: Map one gathered-context value to a provider-native field.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: "#/components/schemas/ValidationError"
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    OnboardingSetup:
      properties:
        agent_brief:
          type: string
          maxLength: 8000
          minLength: 1
          title: Agent Brief
        tone:
          type: string
          maxLength: 100
          minLength: 1
          title: Tone
        language:
          type: string
          maxLength: 100
          minLength: 1
          title: Language
        voice_provider:
          type: string
          maxLength: 100
          minLength: 1
          title: Voice Provider
        voice_name:
          type: string
          maxLength: 255
          minLength: 1
          title: Voice Name
        behavior_notes:
          anyOf:
            - type: string
              maxLength: 4000
            - type: "null"
          title: Behavior Notes
        workflow_stages:
          items:
            type: string
          type: array
          maxItems: 8
          title: Workflow Stages
          description: Optional template hints; the planner chooses the stages from the
            brief.
        agent_name:
          type: string
          maxLength: 255
          minLength: 1
          title: Agent Name
        use_case:
          type: string
          maxLength: 2000
          minLength: 1
          title: Use Case
        call_type:
          type: string
          enum:
            - inbound
            - outbound
          title: Call Type
      type: object
      required:
        - agent_brief
        - tone
        - language
        - voice_provider
        - voice_name
        - agent_name
        - use_case
        - call_type
      title: OnboardingSetup
    UpdateWorkflowRequest:
      properties:
        name:
          anyOf:
            - type: string
            - type: "null"
          title: Name
        workflow_definition:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Workflow Definition
        template_context_variables:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Template Context Variables
        workflow_configurations:
          anyOf:
            - $ref: "#/components/schemas/WorkflowConfigurationDefaults"
            - type: "null"
      type: object
      title: UpdateWorkflowRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    WorkflowConfigurationDefaults:
      properties:
        agent_setup:
          anyOf:
            - $ref: "#/components/schemas/OnboardingSetup"
            - type: "null"
        voice_clone_id:
          anyOf:
            - type: string
              maxLength: 36
              minLength: 1
            - type: "null"
          title: Voice Clone Id
        ambient_noise_configuration:
          $ref: "#/components/schemas/AmbientNoiseConfigurationDefaults"
        max_call_duration:
          type: integer
          maximum: 1200
          exclusiveMinimum: 0
          title: Max Call Duration
          default: 300
        max_user_idle_timeout:
          type: number
          title: Max User Idle Timeout
          default: 10
        smart_turn_stop_secs:
          type: number
          title: Smart Turn Stop Secs
          default: 2
        turn_start_strategy:
          type: string
          enum:
            - default
            - min_words
            - provisional_vad
          title: Turn Start Strategy
          default: default
        turn_start_min_words:
          type: integer
          title: Turn Start Min Words
          default: 3
        provisional_vad_pause_secs:
          type: number
          title: Provisional Vad Pause Secs
          default: 1.5
        turn_stop_strategy:
          type: string
          enum:
            - transcription
            - turn_analyzer
          title: Turn Stop Strategy
          default: transcription
        dictionary:
          type: string
          title: Dictionary
          default: ""
        context_compaction_enabled:
          type: boolean
          title: Context Compaction Enabled
          default: false
        call_dispositions:
          items:
            $ref: "#/components/schemas/CallDispositionOption"
          type: array
          maxItems: 50
          title: Call Dispositions
          description: Allowed business outcomes for terminal call classification. Each
            entry defines the exact stored code and the criteria for selecting
            it.
        text_chat_inactivity_timeout_seconds:
          type: integer
          maximum: 10500
          minimum: 60
          title: Text Chat Inactivity Timeout Seconds
          default: 1800
        external_pbx_field_mappings:
          items:
            $ref: "#/components/schemas/ExternalPBXFieldMapping"
          type: array
          maxItems: 100
          title: External Pbx Field Mappings
        external_pbx_lead_headers:
          items:
            type: string
            pattern: ^[A-Za-z][A-Za-z0-9_]{0,63}$
          type: array
          maxItems: 50
          title: External Pbx Lead Headers
      additionalProperties: true
      type: object
      title: WorkflowConfigurationDefaults
    WorkflowResponse:
      properties:
        id:
          type: integer
          title: Id
        name:
          type: string
          title: Name
        status:
          type: string
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        workflow_definition:
          additionalProperties: true
          type: object
          title: Workflow Definition
        current_definition_id:
          anyOf:
            - type: integer
            - type: "null"
          title: Current Definition Id
        template_context_variables:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Template Context Variables
        call_disposition_codes:
          anyOf:
            - $ref: "#/components/schemas/CallDispositionCodes"
            - type: "null"
        total_runs:
          anyOf:
            - type: integer
            - type: "null"
          title: Total Runs
        workflow_configurations:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Workflow Configurations
        version_number:
          anyOf:
            - type: integer
            - type: "null"
          title: Version Number
        version_status:
          anyOf:
            - type: string
            - type: "null"
          title: Version Status
        workflow_uuid:
          anyOf:
            - type: string
            - type: "null"
          title: Workflow Uuid
      type: object
      required:
        - id
        - name
        - status
        - created_at
        - workflow_definition
        - current_definition_id
      title: WorkflowResponse
````