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

# Save agent draft

> Save an agent configuration as a draft without affecting live calls.



## OpenAPI

````yaml api-reference/agents/openapi.json PUT /v1/agents/{agentId}/save
openapi: 3.0.3
info:
  title: Persistence Agents API
  version: '1.0'
  description: Create, save, and publish Persistence AI voice agents.
servers:
  - url: https://api.persistence.dev
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Agents
    description: Agent creation and versioning.
paths:
  /v1/agents/{agentId}/save:
    put:
      tags:
        - Agents
      summary: Save agent draft
      description: >-
        Save the agent configuration as a draft. The draft is not used for live
        calls until it is published.
      operationId: saveAgentDraft
      parameters:
        - name: agentId
          in: path
          required: true
          schema:
            type: string
          description: Agent public ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveAgentRequest'
        description: Agent draft configuration
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    SaveAgentRequest:
      type: object
      required:
        - ambienceId
        - pipelineType
        - systemPrompt
        - triggers
      properties:
        ambienceId:
          description: Ambience
          type: string
        ambienceVolume:
          type: number
          maximum: 2
          minimum: 0
        avatarUrl:
          type: string
          maxLength: 512
        description:
          type: string
          maxLength: 512
        digitPronunciation:
          type: boolean
        dynamicVariables:
          $ref: '#/components/schemas/DynamicVariablesConfig'
        endpointingPatience:
          type: number
        greetingConfig:
          description: Voice Pipeline Configs
          allOf:
            - $ref: '#/components/schemas/GreetingConfig'
        interruptionSensitivity:
          type: number
        knowledgeBaseIds:
          description: >-
            Knowledge base public IDs to attach (max enforced by
            knowledgebase.Link)
          type: array
          items:
            type: string
        languageCode:
          type: string
          maxLength: 10
        llmMaxTokens:
          type: integer
          minimum: 1
        llmModel:
          type: string
        llmProvider:
          description: LLM Settings
          type: string
          enum:
            - openai
            - anthropic
            - google
            - groq
            - together
            - azure
            - cerebras
        llmTemperature:
          type: number
          maximum: 2
          minimum: 0
        maxCallDurationSec:
          type: integer
          minimum: 1
        minConsecutiveSpeechDelay:
          type: number
          minimum: 0
        name:
          description: Agent-level fields
          type: string
          maxLength: 64
        noiseCancellationConfig:
          $ref: '#/components/schemas/NoiseCancellationConfig'
        piiAnonymisation:
          description: PII Settings (versioned)
          type: boolean
        piiCategories:
          type: array
          items:
            type: string
        piiRedaction:
          type: boolean
        pipelineType:
          $ref: '#/components/schemas/PipelineType'
        presenceDetectionConfig:
          $ref: '#/components/schemas/PresenceDetectionConfig'
        responseEagerness:
          type: number
        silenceTimeoutSec:
          description: Behavior Settings
          type: integer
          minimum: 1
        systemPrompt:
          description: Core Config
          type: string
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ToolRequest'
        triggers:
          description: Triggers
          type: array
          items:
            $ref: '#/components/schemas/TriggerRequest'
        ttsSpeed:
          type: number
          maximum: 2
          minimum: 0.5
        ttsVoiceModelId:
          description: TTS Settings
          type: integer
        vocabularySpecialization:
          $ref: '#/components/schemas/VocabularySpecialization'
        voiceVolume:
          type: number
          maximum: 2
          minimum: 0
    AgentResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Agent'
        success:
          type: boolean
    Error:
      type: object
      properties:
        code:
          type: string
        error:
          type: string
    DynamicVariablesConfig:
      type: object
      properties:
        variables:
          type: array
          items:
            $ref: '#/components/schemas/Variable'
    GreetingConfig:
      type: object
      properties:
        messageConfig:
          $ref: '#/components/schemas/MessageConfig'
        mode:
          $ref: '#/components/schemas/GreetingMode'
    NoiseCancellationConfig:
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/NoiseCancellationMode'
    PipelineType:
      type: string
      enum:
        - cascaded
        - realtime_native
      x-enum-varnames:
        - PipelineTypeCascaded
        - PipelineTypeRealtimeNative
    PresenceDetectionConfig:
      type: object
      properties:
        checkIntervalSec:
          type: integer
        maxAwayChecks:
          type: integer
    ToolRequest:
      type: object
      properties:
        config:
          type: object
          additionalProperties: {}
        description:
          type: string
        isActive:
          type: boolean
        kind:
          type: string
        name:
          type: string
        parametersSchema:
          type: object
          additionalProperties: {}
        toolName:
          type: string
    TriggerRequest:
      type: object
      properties:
        category:
          type: string
        executionOrder:
          type: integer
        isActive:
          type: boolean
        llmModel:
          type: string
        llmProvider:
          type: string
        maxTokens:
          type: integer
        name:
          type: string
        pattern:
          type: array
          items:
            $ref: '#/components/schemas/PatternField'
        prompt:
          type: string
        type:
          type: string
    VocabularySpecialization:
      type: string
      enum:
        - general
        - medical
      x-enum-varnames:
        - VocabularySpecializationGeneral
        - VocabularySpecializationMedical
    Agent:
      type: object
      properties:
        avatarUrl:
          type: string
        createdAt:
          description: Timestamps
          type: string
        description:
          type: string
        external:
          description: External Data (pre-hook execution results)
          type: array
          items:
            $ref: '#/components/schemas/HookResult'
        id:
          description: PublicID
          type: string
        name:
          description: Basic Info
          type: string
        promptType:
          $ref: '#/components/schemas/PromptType'
        spaceId:
          description: Space PublicID
          type: string
        status:
          description: Status
          type: string
        templateId:
          description: Template Origin
          type: string
        type:
          $ref: '#/components/schemas/AgentType'
        updatedAt:
          type: string
        version:
          $ref: '#/components/schemas/AgentVersion'
        versionHistory:
          type: array
          items:
            $ref: '#/components/schemas/AgentVersion'
    Variable:
      type: object
      properties:
        defaultValue:
          type: string
        key:
          type: string
    MessageConfig:
      type: object
      properties:
        delay:
          type: number
        message:
          type: string
        type:
          $ref: '#/components/schemas/MessageType'
    GreetingMode:
      type: string
      enum:
        - agent_first
        - user_first
      x-enum-varnames:
        - GreetingModeAgentFirst
        - GreetingModeUserFirst
    NoiseCancellationMode:
      type: string
      enum:
        - noise_only
        - noise_and_speech
        - none
      x-enum-varnames:
        - NoiseCancellationModeNoiseOnly
        - NoiseCancellationModeNoiseAndSpeech
        - NoiseCancellationModeNone
    PatternField:
      type: object
      properties:
        description:
          type: string
        isMultiple:
          type: boolean
        key:
          type: string
        type:
          description: '"string", "number", "boolean"'
          type: string
    HookResult:
      type: object
      properties:
        data:
          type: object
          additionalProperties: true
        name:
          type: string
    PromptType:
      type: string
      enum:
        - single_prompt
        - conversational_flow
      x-enum-varnames:
        - PromptTypeSinglePrompt
        - PromptTypeConversationalFlow
    AgentType:
      type: string
      enum:
        - voice
        - chat
      x-enum-varnames:
        - AgentTypeVoice
        - AgentTypeChat
    AgentVersion:
      type: object
      properties:
        ambienceId:
          description: Ambience
          type: string
        ambienceVolume:
          type: number
        amd:
          $ref: '#/components/schemas/AMDConfig'
        createdAt:
          description: Timestamps
          type: string
        digitPronunciation:
          type: boolean
        dynamicVariables:
          $ref: '#/components/schemas/DynamicVariablesConfig'
        endpointingConfig:
          $ref: '#/components/schemas/EndpointingConfig'
        endpointingPatience:
          type: number
        fallbackMessages:
          description: Fallback Messages
          type: array
          items:
            type: string
        greetingConfig:
          description: Voice Pipeline Configs
          allOf:
            - $ref: '#/components/schemas/GreetingConfig'
        id:
          description: Identity
          type: integer
        interruptionConfig:
          $ref: '#/components/schemas/InterruptionConfig'
        interruptionSensitivity:
          type: number
        knowledgeBaseIds:
          description: Knowledge Bases (public IDs, loaded from the attachment join table)
          type: array
          items:
            type: string
        languageCode:
          type: string
        llmMaxTokens:
          type: integer
        llmModel:
          type: string
        llmProvider:
          description: LLM Settings
          type: string
        llmTemperature:
          type: number
        maxCallDurationSec:
          type: integer
        minConsecutiveSpeechDelay:
          type: number
        noiseCancellationConfig:
          $ref: '#/components/schemas/NoiseCancellationConfig'
        piiAnonymisation:
          description: PII Settings (versioned - rollback affects these)
          type: boolean
        piiCategories:
          type: array
          items:
            type: string
        piiRedaction:
          type: boolean
        pipelineType:
          $ref: '#/components/schemas/PipelineType'
        preemptiveGenerationConfig:
          $ref: '#/components/schemas/PreemptiveGenerationConfig'
        presenceDetectionConfig:
          $ref: '#/components/schemas/PresenceDetectionConfig'
        responseEagerness:
          type: number
        silenceTimeoutSec:
          description: Behavior Settings
          type: integer
        status:
          description: Version Status
          type: string
        sttModel:
          type: string
        sttProvider:
          description: STT (Speech-to-Text) Settings
          type: string
        systemPrompt:
          description: Core Config
          type: string
        tools:
          description: Tools
          type: array
          items:
            $ref: '#/components/schemas/Tool'
        triggers:
          description: Triggers
          type: array
          items:
            $ref: '#/components/schemas/Trigger'
        ttsConfigs:
          $ref: '#/components/schemas/Voice'
        ttsSpeed:
          type: number
        ttsVoiceModelId:
          description: TTS (Text-to-Speech) Settings
          type: integer
        turnDetectionConfig:
          $ref: '#/components/schemas/TurnDetectionConfig'
        updatedAt:
          type: string
        version:
          type: integer
        vocabularySpecialization:
          $ref: '#/components/schemas/VocabularySpecialization'
        voiceVolume:
          type: number
    MessageType:
      type: string
      enum:
        - static
        - dynamic
      x-enum-varnames:
        - MessageTypeStatic
        - MessageTypeDynamic
    AMDConfig:
      type: object
      properties:
        detectionOptions:
          $ref: '#/components/schemas/DetectionOptions'
        enabled:
          type: boolean
        interruptOnMachine:
          type: boolean
        ivrHangUpEnabled:
          type: boolean
        ivrNavigationEnabled:
          type: boolean
        ivrNavigationInstructions:
          type: string
        llmModel:
          type: string
        sttModel:
          type: string
        voiceMailAction:
          type: string
        voiceMailMessage:
          type: string
    EndpointingConfig:
      type: object
      properties:
        maxDelay:
          type: number
        minDelay:
          type: number
        mode:
          $ref: '#/components/schemas/EndpointingMode'
    InterruptionConfig:
      type: object
      properties:
        discardAudioIfUninterruptible:
          type: boolean
        enabled:
          type: boolean
        falseInterruptionTimeout:
          type: number
        minDuration:
          type: number
        minWords:
          type: integer
        mode:
          $ref: '#/components/schemas/InterruptionMode'
        resumeFalseInterruption:
          type: boolean
    PreemptiveGenerationConfig:
      type: object
      properties:
        enabled:
          type: boolean
        maxRetries:
          type: integer
        maxSpeechDuration:
          type: number
        preemptiveTts:
          type: boolean
    Tool:
      type: object
      properties:
        config:
          type: object
          additionalProperties: {}
        description:
          type: string
        id:
          type: string
        isActive:
          type: boolean
        kind:
          type: string
        name:
          type: string
        parametersSchema:
          type: object
          additionalProperties: {}
        toolName:
          type: string
    Trigger:
      type: object
      properties:
        category:
          type: string
        createdAt:
          type: string
        executionOrder:
          type: integer
        id:
          description: PublicID
          type: string
        isActive:
          type: boolean
        llmModel:
          type: string
        llmProvider:
          type: string
        maxTokens:
          type: integer
        name:
          type: string
        pattern:
          type: array
          items:
            $ref: '#/components/schemas/PatternField'
        prompt:
          type: string
        type:
          type: string
        updatedAt:
          type: string
    Voice:
      type: object
      required:
        - name
        - provider
        - providerVoiceId
        - type
      properties:
        avatarUrl:
          description: Media assets
          type: string
        category:
          type: string
        createdAt:
          type: string
        id:
          description: Core identification
          type: integer
        isActive:
          description: State
          type: boolean
        languages:
          description: Related entities (populated via JOIN or separate query)
          type: array
          items:
            $ref: '#/components/schemas/VoiceModel'
        metadata:
          description: Provider-specific data (detail view only)
          type: array
          items:
            type: integer
        name:
          type: string
        provider:
          type: string
          enum:
            - elevenlabs
            - cartesia
            - deepgram
            - google
        providerVoiceId:
          type: string
        publicId:
          type: string
        rating:
          type: integer
        spaceId:
          type: integer
        status:
          description: Custom voice fields
          type: string
        tags:
          description: Voice-level attributes
          type: array
          items:
            type: string
        traits:
          type: string
        type:
          type: string
          enum:
            - preset
            - custom
        updatedAt:
          type: string
    TurnDetectionConfig:
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/TurnDetectionMode'
        modelType:
          $ref: '#/components/schemas/TurnDetectionModelType'
        unlikelyThreshold:
          type: number
    DetectionOptions:
      type: object
      properties:
        humanSilenceThreshold:
          type: number
        humanSpeechThreshold:
          type: number
        machineSilenceThreshold:
          type: number
        noSpeechThreshold:
          type: number
        prompt:
          type: string
        timeout:
          type: number
    EndpointingMode:
      type: string
      enum:
        - fixed
        - dynamic
      x-enum-varnames:
        - EndpointingModeFixed
        - EndpointingModeDynamic
    InterruptionMode:
      type: string
      enum:
        - adaptive
        - vad
      x-enum-varnames:
        - InterruptionModeAdaptive
        - InterruptionModeVAD
    VoiceModel:
      type: object
      required:
        - voiceId
      properties:
        accent:
          type: string
        age:
          type: string
        createdAt:
          description: Timestamps
          type: string
        displayName:
          type: string
        gender:
          description: Voice characteristics (per language)
          type: string
        id:
          type: integer
        languageId:
          type: string
        metadata:
          description: Language-specific capabilities
          type: array
          items:
            type: integer
        modelId:
          type: string
        previewUrl:
          type: string
        s2sSupported:
          type: array
          items:
            type: string
        sourceFilesUrl:
          description: Custom voice fields
          type: string
        sttSupported:
          type: array
          items:
            type: string
        style:
          type: array
          items:
            type: string
        updatedAt:
          type: string
        voiceId:
          type: integer
    TurnDetectionMode:
      type: string
      enum:
        - stt
        - vad
        - manual
        - model
      x-enum-varnames:
        - TurnDetectionModeSTT
        - TurnDetectionModeVAD
        - TurnDetectionModeManual
        - TurnDetectionModeModel
    TurnDetectionModelType:
      type: string
      enum:
        - multilingual
        - english
      x-enum-varnames:
        - TurnDetectionModelMultilingual
        - TurnDetectionModelEnglish
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key issued for your workspace.

````