Update an agent

Change any part of an agent’s configuration. Only the fields you send are modified.

PATCH/v1/agents/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

API token issued from the dashboard (Settings → API Tokens). Sent as Authorization: Bearer <token>.

In: header

Path Parameters

id*string

Match

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Agent display name.

Length1 <= length <= 200

description?|

Free-text agent description.

status?string

Value in"draft" | "active" | "archived"

model?

LLM configuration.

voice?

Voice (text-to-speech) configuration.

backgroundSound?

Ambient background audio played under the agent’s voice.

transcriber?

Speech-to-text configuration.

timeouts?

Call-length and silence timeouts.

voicemail?

Voicemail detection and drop behavior for outbound calls.

transfer?

Call transfer (warm/blind handoff) configuration. Supplying any of name/description/destinations/messageMode/customMessage/notifyOnTransfer replaces the whole stored config.

knowledge?

Retrieval-augmented generation (RAG) and knowledge-base access.

memory?

Cross-call contact memory configuration.

calendar?

Calendar availability + booking configuration.

structuredOutput?

Post-call structured data extraction.

server?

Outbound webhook, live event routing, and call-flow messaging.

compliance?

Recording, logging, and compliance settings.

turnTaking?

Turn-taking, interruption, and endpointing tuning.

providerTuning?

Provider-specific tuning knobs. Each sub-object only applies when the matching provider is selected in model/voice/transcriber.

toolIds?array<>

Tool ids to attach. Must belong to your organization (or be a shared built-in tool); replaces the full set.

Itemsitems <= 50

Response Body

`application/json`

cURL

curl -X PATCH "https://example.com/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{
  "success": true,
  "agent": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "description": "string",
    "status": "draft",
    "model": {
      "provider": "openai",
      "name": "gpt-4o-mini-cluster",
      "systemPrompt": "string",
      "firstMessage": "string",
      "firstMessageMode": "agent_speaks_first",
      "maxTokens": -9007199254740991,
      "temperature": 0,
      "openaiServiceTier": "auto"
    },
    "voice": {
      "provider": "11labs",
      "voiceId": "string",
      "model": "string",
      "stability": 0,
      "similarity": 0,
      "speed": 0,
      "volume": 0,
      "styleExaggeration": 0,
      "speakerBoost": true,
      "autoMode": true,
      "optimizeStreamingLatency": 0
    },
    "backgroundSound": {
      "sound": "office",
      "url": "string",
      "volume": 0
    },
    "transcriber": {
      "provider": "deepgram",
      "model": "string",
      "language": "string",
      "backgroundDenoising": true,
      "confidenceThreshold": 0,
      "useNumerals": true,
      "keywords": "string"
    },
    "timeouts": {
      "silenceSeconds": -9007199254740991,
      "maximumDurationSeconds": -9007199254740991,
      "maxDurationSeconds": -9007199254740991
    },
    "voicemail": {
      "detectionEnabled": true,
      "provider": "off",
      "mode": "tts",
      "message": "string",
      "audioUrl": "string"
    },
    "transfer": {
      "enabled": true,
      "enableEndCall": true,
      "enableDialKeypad": true,
      "legacyForwardingNumber": "string",
      "name": "string",
      "description": "string",
      "destinations": [
        {
          "id": "string",
          "type": "number",
          "name": "string",
          "number": "string",
          "extension": "string",
          "sipUri": "string",
          "description": "string",
          "callerId": "string",
          "transferMode": "blind-transfer",
          "message": "string",
          "sipHeaders": {
            "property1": "string",
            "property2": "string"
          }
        }
      ],
      "messageMode": "default",
      "customMessage": "string",
      "notifyOnTransfer": {
        "enabled": true,
        "summaryPromptOverride": "string",
        "sms": {
          "enabled": true,
          "phoneNumber": "string"
        },
        "email": {
          "enabled": true,
          "address": "string"
        }
      }
    },
    "knowledge": {
      "enabled": true,
      "instructions": "string",
      "knowledgeBaseIds": [
        "feff8316-75ff-4581-ba78-f3795ee6b8e7"
      ],
      "sourceIds": [
        "1142aa4e-ac22-46dd-ac6a-fc70d264bc91"
      ],
      "config": {
        "chunkStrategy": "small",
        "retrievalK": -9007199254740991,
        "similarityThreshold": 0,
        "maxContextTokens": -9007199254740991,
        "enableHybridSearch": true,
        "hybridSearchWeight": 0,
        "includeSources": true
      }
    },
    "memory": {
      "enabled": true,
      "config": {
        "searchLimit": -9007199254740991,
        "searchThreshold": 0,
        "includeUserMemories": true,
        "includeAgentMemories": true,
        "includeSessionMemories": true,
        "maxContextTokens": -9007199254740991,
        "storeMemories": true
      }
    },
    "calendar": {
      "enabled": true,
      "eventTypeIds": [
        "ccf9387d-41d9-48c7-898d-4cc55e596943"
      ],
      "instructions": "string",
      "config": {
        "timezoneStrategy": "ask",
        "fixedTimezone": "string",
        "daysAhead": -9007199254740991,
        "requireEmail": true,
        "requirePhone": true,
        "autoConfirm": true,
        "eventTypeInstructions": {
          "property1": "string",
          "property2": "string"
        }
      }
    },
    "structuredOutput": {
      "prompt": "string",
      "schema": {
        "property1": null,
        "property2": null
      },
      "timeoutSeconds": -9007199254740991
    },
    "server": {
      "url": "string",
      "timeoutSeconds": -9007199254740991,
      "messages": [
        "string"
      ],
      "clientMessages": [
        "string"
      ],
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "endCallMessage": "string",
      "idleMessages": "string",
      "maxIdleMessages": -9007199254740991,
      "idleTimeoutSeconds": 0,
      "toolMessages": {
        "property1": {
          "messages": [
            {
              "id": "string",
              "type": "request-start",
              "content": "string",
              "mode": "default",
              "waitForSpeech": true,
              "endCallAfterMessage": true,
              "timing": 0
            }
          ]
        },
        "property2": {
          "messages": [
            {
              "id": "string",
              "type": "request-start",
              "content": "string",
              "mode": "default",
              "waitForSpeech": true,
              "endCallAfterMessage": true,
              "timing": 0
            }
          ]
        }
      }
    },
    "compliance": {
      "hipaa": true,
      "audioRecording": true,
      "logging": true,
      "transcriptEnabled": true,
      "audioFormat": "wav",
      "operatorControlEnabled": true
    },
    "turnTaking": {
      "responsiveness": 0,
      "interruptionSensitivity": 0,
      "smartEndpointing": "off",
      "waitSeconds": 0,
      "onPunctuationSeconds": 0,
      "onNoPunctuationSeconds": 0,
      "onNumberSeconds": 0,
      "stopSpeakingWords": -9007199254740991,
      "stopSpeakingVoiceSeconds": 0,
      "stopSpeakingBackoffSeconds": 0,
      "keypadInput": {
        "enabled": true,
        "timeoutSeconds": -9007199254740991,
        "delimiter": "string"
      }
    },
    "providerTuning": {
      "fish": {
        "latency": "normal",
        "normalize": true,
        "expressiveTags": true,
        "temperature": 0,
        "topP": 0
      },
      "hume": {
        "description": "string",
        "trailingSilenceSeconds": 0
      },
      "soniox": {
        "languageHints": "string",
        "languageHintsStrict": true,
        "languageIdentification": true,
        "diarization": true,
        "turnDetection": "vad",
        "endpointSensitivity": 0,
        "maxEndpointDelayMs": -9007199254740991,
        "endpointLatencyLevel": -9007199254740991
      },
      "speechmatics": {
        "operatingPoint": "standard",
        "turnDetection": "external",
        "maxDelayMs": -9007199254740991,
        "endOfUtteranceSilenceMs": -9007199254740991,
        "diarization": true
      },
      "deepgramFlux": {
        "eotThreshold": 0,
        "eotTimeoutMs": -9007199254740991,
        "eagerEotThreshold": 0,
        "keyterms": [
          "string"
        ]
      },
      "geminiVad": {
        "searchGrounding": true,
        "affectiveDialog": true,
        "proactiveAudio": true,
        "startSensitivity": "SENSITIVITY_LOW",
        "endSensitivity": "SENSITIVITY_LOW",
        "silenceDurationMs": -9007199254740991,
        "prefixPaddingMs": -9007199254740991
      }
    },
    "toolIds": [
      "95659032-40b7-428d-bf46-562a2c5d3aa2"
    ],
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

{
  "error": "validation_failed",
  "message": "string",
  "issues": null
}

{
  "error": "unauthorized"
}

{
  "success": false,
  "error": "API key lacks write permission"
}

{
  "error": "validation_failed",
  "message": "string",
  "issues": null
}

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`