> ## Documentation Index > Fetch the complete documentation index at: https://support.callin.io/llms.txt > Use this file to discover all available pages before exploring further. # Update agent > Partially updates an agent. Only fields included in the request body are changed; omitted fields remain unchanged. Returns the full updated agent on success. ## OpenAPI ````yaml /openapi.json patch /public/v1/agents/{agentId} openapi: 3.0.3 info: title: Callin Public API version: 1.0.0 description: >- The Callin public API lets you programmatically build and manage AI voice agents, control their knowledge bases, and retrieve call logs and transcripts. All endpoints are versioned under /public/v1. servers: - url: https://api.callin.io/api description: API Endpoint security: [] tags: - name: Health description: Service availability check. No authentication required. - name: Identity description: Verify which account is associated with the current API key. - name: Agents description: Create, retrieve, and update AI voice agents. - name: Conversations description: List and inspect call logs, transcripts, and conversation details. - name: Knowledge Base description: Manage documents and groups that agents use during calls. paths: /public/v1/agents/{agentId}: patch: tags: - Agents summary: Update agent description: >- Partially updates an agent. Only fields included in the request body are changed; omitted fields remain unchanged. Returns the full updated agent on success. parameters: - name: agentId in: path required: true schema: type: string description: The unique identifier of the agent to update. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAgentRequest' example: {} responses: '200': description: Agent updated successfully. Returns the full updated agent. content: application/json: schema: $ref: '#/components/schemas/SuccessAgentDetailsResponse' '404': description: No agent found with the given agentId. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Request body failed validation. Check the error field for details. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - ApiKeyHeader: [] - BearerAuth: [] components: schemas: UpdateAgentRequest: type: object description: >- Partial update payload for an agent. All fields are optional — include only the fields you want to change. Omitted fields remain unchanged. properties: name: type: string description: Display name for the agent. direction: type: string enum: - outbound - inbound - both description: Supported call direction. tags: type: array items: type: string description: Tags for organizing agents. conversationConfig: $ref: '#/components/schemas/UpdateAgentConversationConfiguration' platformSettings: $ref: '#/components/schemas/PatchAgentPlatformSettings' example: {} SuccessAgentDetailsResponse: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/AgentDetails' description: >- Full single-agent record including conversation and platform configuration. ErrorResponse: type: object description: >- Returned for most client and validation errors. Read `error.message` and optional `error.fields` for details. properties: success: type: boolean example: false description: Always `false` for this shape. error: type: object description: Structured error payload from the API. properties: code: type: string description: Stable machine-oriented error code when provided. message: type: string description: Human-readable explanation suitable to show or log. status: type: integer description: HTTP status code echoed for convenience. fields: type: array description: >- Optional per-field validation issues (shape is endpoint-specific). items: type: object UpdateAgentConversationConfiguration: type: object properties: asr: type: object properties: userInputAudioFormat: type: string enum: - pcm_8000 - pcm_16000 - pcm_22050 - pcm_24000 - pcm_44100 - pcm_48000 - ulaw_8000 description: The format of the audio to be transcribed keywords: type: array items: type: string description: Keywords to boost prediction probability for description: Configuration for conversational transcription turn: type: object properties: turnTimeout: type: number description: >- Maximum wait time for the user’s reply before re-engaging the user silenceEndCallTimeout: type: number description: >- Maximum wait time since the user last spoke before terminating the call turnEagerness: type: string enum: - patient - normal - eager description: >- Controls how eager the agent is to respond. Low = less eager (waits longer), Standard = default eagerness, High = more eager (responds sooner) spellingPatience: type: string enum: - auto - 'off' description: >- Controls if the agent should be more patient when user is spelling numbers and named entities. Auto = model based, Off = never wait extra description: Configuration for turn detection tts: type: object properties: voiceId: type: string description: The voice ID to use for TTS supportedVoices: type: array items: type: object required: - label - voiceId properties: label: type: string voiceId: type: string language: type: string stability: type: number minimum: 0 maximum: 1 speed: type: number minimum: 0.7 maximum: 1.2 similarityBoost: type: number minimum: 0 maximum: 1 description: Additional supported voices for the agent expressiveMode: type: boolean description: When enabled, applies expressive audio tags prompt. suggestedAudioTags: type: array items: type: object required: - tag properties: tag: type: string minLength: 1 maxLength: 30 description: type: string maxLength: 200 description: >- Suggested audio tags to boost expressive speech. The agent can still use other tags not listed here. agentOutputAudioFormat: type: string enum: - pcm_8000 - pcm_16000 - pcm_22050 - pcm_24000 - pcm_44100 - pcm_48000 - ulaw_8000 description: The audio format to use for TTS optimizeStreamingLatency: type: integer enum: - 0 - 1 - 2 - 3 - 4 description: Streaming latency optimization level (0–4). stability: type: number minimum: 0 maximum: 1 description: Controls the stability of the generated speech speed: type: number minimum: 0.7 maximum: 1.2 description: Controls the speed of the generated speech similarityBoost: type: number minimum: 0 maximum: 1 description: The similarity boost for generated speech description: Configuration for conversational text to speech conversation: type: object properties: maxDurationSeconds: type: number description: The maximum duration of the conversation in seconds description: Configuration for the conversation languagePresets: type: object additionalProperties: $ref: '#/components/schemas/PatchLanguagePreset' description: Per-locale preset overrides (record keyed by locale code). agent: type: object properties: greetingMessage: type: string description: >- If non-empty, the first message the agent will say. If empty, the agent waits for the user to start the discussion. primaryLanguage: type: string description: The primary language of the agent - used for ASR and TTS. hinglishMode: type: boolean description: >- When enabled, optimizes behavior for Hindi–English (Hinglish) conversations. dynamicVariables: type: object additionalProperties: type: string description: Dynamic variable placeholders (string keys and string values). disableFirstMessageInterruptions: type: boolean description: >- If true, the user will not be able to interrupt the agent while the first message is being delivered. prompt: type: object properties: prompt: type: string description: The prompt for the agent llm: type: string enum: - gpt-oss-120b - glm-45-air-fp8 - neuron-1.0 - gpt-4.1-nano - gpt-5-nano - gemini-2.5-flash-lite - gemini-2.5-flash description: >- The LLM to query with the prompt and the chat history. If using data residency, the LLM must be supported in the data residency environment temperature: type: number minimum: 0 maximum: 1 description: The temperature for the LLM toolIds: type: array items: type: string description: A list of IDs of tools used by the agent builtInTools: $ref: '#/components/schemas/PatchBuiltInTools' knowledgeBase: type: array items: type: string description: A list of IDs of knowledge bases used by the agent ignoreDefaultPersonality: type: boolean description: >- Whether to remove the default personality lines from the system prompt timezone: type: string description: >- Timezone for displaying current time in system prompt. If set, the current time will be included in the system prompt using this timezone. Must be a valid timezone name (e.g., ‘America/New_York’, ‘Europe/London’, ‘UTC’). description: The prompt for the agent description: Agent specific configuration PatchAgentPlatformSettings: type: object properties: callActions: type: object properties: smartOptOut: type: boolean description: Whether to enable smart opt-out issueTracking: type: boolean description: Whether to enable issue tracking postCallWebhook: type: string description: The URL to send the post-call webhook to postCallEmail: type: object properties: enabled: type: boolean emailConfiguration: type: object additionalProperties: type: string description: Configuration for the post-call email scheduleOnCalendar: type: object properties: enabled: type: boolean provider: type: string enum: - google - calcom eventsIds: type: array items: type: string description: Configuration for the schedule on calendar description: Call actions settings widget: type: object additionalProperties: type: string description: Widget configuration as string key/value pairs. dataCollection: type: object properties: entities: type: object additionalProperties: $ref: '#/components/schemas/PatchDataCollectionEntity' description: Named entities to extract (entity name → schema). storeData: type: boolean description: Data collection settings callRetry: type: object properties: retryCount: type: integer description: The number of times to retry the call retryDelay: type: integer description: The delay in seconds between retries description: Call retry settings summaryLanguage: type: string description: >- Language for all conversation analysis outputs (summaries, titles, evaluation rationales, data collection rationales). If not set, the language will be inferred from the conversation. Must be one of the supported conversation languages. privacy: type: object properties: recordVoice: type: boolean description: Whether to record the voice of the caller description: Privacy settings for the agent telephony: type: object properties: numberRotationEnabled: type: boolean description: Whether to enable number rotation rotationNumbers: type: array items: type: string description: The numbers to rotate through callsPerNumber: type: integer description: The number of calls to make per number stateRestrictionEnabled: type: boolean description: Whether to enable state restriction stateRestrictedNumbers: type: array items: type: string description: The numbers to restrict the agent to description: Telephony settings for the agent description: >- Platform settings fields to update. Only include fields you want to change. AgentDetails: type: object properties: agentId: type: string description: The ID of the agent name: type: string description: The name of the agent direction: type: string description: The direction of the agent enum: - outbound - inbound - both example: outbound tags: type: array items: type: string description: The tags of the agent conversationConfig: $ref: '#/components/schemas/AgentConversationConfiguration' type: object description: The conversation configuration of the agent platformSettings: $ref: '#/components/schemas/AgentPlatformSettings' type: object description: The platform settings of the agent phoneNumbers: type: array items: type: object properties: provider: type: string number: type: string label: type: string description: The phone numbers of the agent workflow: type: object properties: edges: type: object nodes: type: object preventSubagentLoops: type: boolean default: false description: The workflow of the agent metadata: type: object properties: createdAt: type: string updatedAt: type: string createdBy: $ref: '#/components/schemas/MetaCreatedBy' description: The metadata of the agent PatchLanguagePreset: type: object description: Per-locale overrides for turn, TTS, conversation, and agent fields. properties: overrides: type: object properties: turn: type: object properties: softTimeoutConfig: type: object properties: message: type: string tts: type: object properties: voiceId: type: string stability: type: number minimum: 0 maximum: 1 speed: type: number minimum: 0.7 maximum: 1.2 similarityBoost: type: number minimum: 0 maximum: 1 conversation: type: object properties: textOnly: type: boolean agent: type: object properties: firstMessage: type: string language: type: string prompt: type: object properties: prompt: type: string llm: type: string PatchBuiltInTools: type: object description: Built-in system tools (PromptSchema.builtInTools). properties: endCall: $ref: '#/components/schemas/PatchBuiltInToolCommon' languageDetection: $ref: '#/components/schemas/PatchBuiltInToolCommon' skipTurn: $ref: '#/components/schemas/PatchBuiltInToolCommon' transferToAgent: allOf: - $ref: '#/components/schemas/PatchBuiltInToolCommon' - type: object properties: transfers: type: array items: $ref: '#/components/schemas/PatchAgentTransfer' transferToNumber: allOf: - $ref: '#/components/schemas/PatchBuiltInToolCommon' - type: object properties: transferRuleIds: type: array items: type: string transfers: type: array items: $ref: '#/components/schemas/PatchHumanTransfer' voicemailDetection: allOf: - $ref: '#/components/schemas/PatchBuiltInToolCommon' - type: object properties: voicemailMessage: type: string PatchDataCollectionEntity: type: object required: - type - description properties: type: type: string enum: - boolean - string - number - integer description: JSON-compatible type for the collected field. description: type: string description: What this entity represents. enum: type: array items: type: string description: Optional allowed values (for string-like fields). AgentConversationConfiguration: type: object required: - agent properties: asr: type: object properties: userInputAudioFormat: type: string default: pcm_16000 enum: - pcm_8000 - pcm_16000 - pcm_22050 - pcm_24000 - pcm_44100 - pcm_48000 - ulaw_8000 description: The format of the audio to be transcribed keywords: type: array items: type: string description: Keywords to boost prediction probability for description: Configuration for conversational transcription turn: type: object properties: turnTimeout: type: number default: 7 description: >- Maximum wait time for the user’s reply before re-engaging the user silenceEndCallTimeout: type: number default: -1 description: >- Maximum wait time since the user last spoke before terminating the call turnEagerness: type: string enum: - patient - normal - eager default: normal description: >- Controls how eager the agent is to respond. Low = less eager (waits longer), Standard = default eagerness, High = more eager (responds sooner) spellingPatience: type: string enum: - auto - 'off' default: auto description: >- Controls if the agent should be more patient when user is spelling numbers and named entities. Auto = model based, Off = never wait extra description: Configuration for turn detection tts: type: object properties: voiceId: type: string description: The voice ID to use for TTS default: cjVigY5qzO86Huf0OWal supportedVoices: type: array items: type: object required: - label - voiceId properties: label: type: string voiceId: type: string language: type: string stability: type: number minimum: 0 maximum: 1 speed: type: number minimum: 0.7 maximum: 1.2 similarityBoost: type: number minimum: 0 maximum: 1 description: Additional supported voices for the agent expressiveMode: type: boolean default: false description: When enabled, applies expressive audio tags prompt. suggestedAudioTags: type: array items: type: object required: - tag properties: tag: type: string minLength: 1 maxLength: 30 description: type: string maxLength: 200 description: >- Suggested audio tags to boost expressive speech. The agent can still use other tags not listed here. agentOutputAudioFormat: type: string default: pcm_16000 enum: - pcm_8000 - pcm_16000 - pcm_22050 - pcm_24000 - pcm_44100 - pcm_48000 - ulaw_8000 description: The audio format to use for TTS optimizeStreamingLatency: type: integer enum: - 0 - 1 - 2 - 3 - 4 default: 3 description: Streaming latency optimization level (0–4). stability: type: number minimum: 0 maximum: 1 default: 0.5 description: Controls the stability of the generated speech speed: type: number minimum: 0.7 maximum: 1.2 default: 1 description: Controls the speed of the generated speech similarityBoost: type: number minimum: 0 maximum: 1 default: 0.8 description: The similarity boost for generated speech description: Configuration for conversational text to speech conversation: type: object properties: maxDurationSeconds: type: number default: 300 description: The maximum duration of the conversation in seconds description: Configuration for the conversation languagePresets: type: object additionalProperties: $ref: '#/components/schemas/LanguagePreset' description: Per-locale preset overrides (record keyed by locale code). agent: type: object required: - prompt properties: greetingMessage: type: string description: >- If non-empty, the first message the agent will say. If empty, the agent waits for the user to start the discussion. primaryLanguage: type: string default: en description: The primary language of the agent - used for ASR and TTS. hinglishMode: type: boolean default: false description: >- When enabled, optimizes behavior for Hindi–English (Hinglish) conversations. dynamicVariables: type: object additionalProperties: type: string description: Dynamic variable placeholders (string keys and string values). disableFirstMessageInterruptions: type: boolean default: false description: >- If true, the user will not be able to interrupt the agent while the first message is being delivered. prompt: type: object required: - prompt properties: prompt: type: string description: The prompt for the agent llm: type: string enum: - gpt-oss-120b - glm-45-air-fp8 - neuron-1.0 - gpt-4.1-nano - gpt-5-nano - gemini-2.5-flash-lite - gemini-2.5-flash default: gemini-2.5-flash description: >- The LLM to query with the prompt and the chat history. If using data residency, the LLM must be supported in the data residency environment temperature: type: number minimum: 0 maximum: 1 default: 0 description: The temperature for the LLM toolIds: type: array items: type: string description: A list of IDs of tools used by the agent builtInTools: $ref: '#/components/schemas/BuiltInTools' knowledgeBase: type: array items: type: string description: A list of IDs of knowledge bases used by the agent ignoreDefaultPersonality: type: boolean default: false description: >- Whether to remove the default personality lines from the system prompt timezone: type: string default: UTC description: >- Timezone for displaying current time in system prompt. If set, the current time will be included in the system prompt using this timezone. Must be a valid timezone name (e.g., ‘America/New_York’, ‘Europe/London’, ‘UTC’). description: The prompt for the agent description: Agent specific configuration AgentPlatformSettings: type: object properties: callActions: type: object properties: smartOptOut: type: boolean default: false description: Whether to enable smart opt-out issueTracking: type: boolean default: false description: Whether to enable issue tracking postCallWebhook: type: string description: The URL to send the post-call webhook to postCallEmail: type: object properties: enabled: type: boolean default: false emailConfiguration: type: object additionalProperties: type: string description: Configuration for the post-call email scheduleOnCalendar: type: object properties: enabled: type: boolean default: false provider: type: string enum: - google - calcom eventsIds: type: array items: type: string description: Configuration for the schedule on calendar description: Call actions settings widget: type: object additionalProperties: type: string description: Widget configuration as string key/value pairs. dataCollection: type: object properties: entities: type: object additionalProperties: $ref: '#/components/schemas/DataCollectionEntity' description: Named entities to extract (entity name → schema). storeData: type: boolean default: false description: Data collection settings callRetry: type: object properties: retryCount: type: integer description: The number of times to retry the call retryDelay: type: integer description: The delay in seconds between retries description: Call retry settings summaryLanguage: type: string description: >- Language for all conversation analysis outputs (summaries, titles, evaluation rationales, data collection rationales). If not set, the language will be inferred from the conversation. Must be one of the supported conversation languages. privacy: type: object properties: recordVoice: type: boolean default: false description: Whether to record the voice of the caller description: Privacy settings for the agent telephony: type: object properties: numberRotationEnabled: type: boolean default: false description: Whether to enable number rotation rotationNumbers: type: array items: type: string description: The numbers to rotate through callsPerNumber: type: integer description: The number of calls to make per number stateRestrictionEnabled: type: boolean default: false description: Whether to enable state restriction stateRestrictedNumbers: type: array items: type: string description: The numbers to restrict the agent to description: Telephony settings for the agent description: The platform settings of the agent MetaCreatedBy: type: object properties: userId: type: string description: The ID of the user who created the item userEmail: type: string description: The email of the user who created the item PatchBuiltInToolCommon: type: object properties: enabled: type: boolean description: type: string disableInterruption: type: boolean PatchAgentTransfer: type: object required: - agentId - condition properties: agentId: type: string condition: type: string delayMs: type: number transferMessage: type: string enableTransferredAgentFirstMessage: type: boolean PatchHumanTransfer: type: object required: - transferType - condition - transferDestination properties: transferType: type: string enum: - blind - conference - sip_refer condition: type: string transferDestination: $ref: '#/components/schemas/PatchHumanTransferDestination' LanguagePreset: type: object description: Per-locale overrides for turn, TTS, conversation, and agent fields. properties: overrides: type: object properties: turn: type: object properties: softTimeoutConfig: type: object properties: message: type: string tts: type: object properties: voiceId: type: string stability: type: number minimum: 0 maximum: 1 speed: type: number minimum: 0.7 maximum: 1.2 similarityBoost: type: number minimum: 0 maximum: 1 conversation: type: object properties: textOnly: type: boolean agent: type: object properties: firstMessage: type: string language: type: string prompt: type: object properties: prompt: type: string llm: type: string BuiltInTools: type: object description: Built-in system tools (PromptSchema.builtInTools). properties: endCall: $ref: '#/components/schemas/BuiltInToolCommon' languageDetection: $ref: '#/components/schemas/BuiltInToolCommon' skipTurn: $ref: '#/components/schemas/BuiltInToolCommon' transferToAgent: allOf: - $ref: '#/components/schemas/BuiltInToolCommon' - type: object properties: transfers: type: array items: $ref: '#/components/schemas/AgentTransfer' transferToNumber: allOf: - $ref: '#/components/schemas/BuiltInToolCommon' - type: object properties: transferRuleIds: type: array items: type: string transfers: type: array items: $ref: '#/components/schemas/HumanTransfer' voicemailDetection: allOf: - $ref: '#/components/schemas/BuiltInToolCommon' - type: object properties: voicemailMessage: type: string DataCollectionEntity: type: object required: - type - description properties: type: type: string enum: - boolean - string - number - integer description: JSON-compatible type for the collected field. description: type: string description: What this entity represents. enum: type: array items: type: string description: Optional allowed values (for string-like fields). PatchHumanTransferDestination: type: object required: - type - phoneNumber properties: type: type: string enum: - phone - phone_dynamic_variable - sip_uri - sip_uri_dynamic_variable phoneNumber: type: string sipUri: type: string BuiltInToolCommon: type: object properties: enabled: type: boolean default: true description: type: string disableInterruption: type: boolean default: false AgentTransfer: type: object required: - agentId - condition properties: agentId: type: string condition: type: string delayMs: type: number transferMessage: type: string enableTransferredAgentFirstMessage: type: boolean HumanTransfer: type: object required: - transferType - condition - transferDestination properties: transferType: type: string enum: - blind - conference - sip_refer condition: type: string transferDestination: $ref: '#/components/schemas/HumanTransferDestination' HumanTransferDestination: type: object required: - type - phoneNumber properties: type: type: string enum: - phone - phone_dynamic_variable - sip_uri - sip_uri_dynamic_variable phoneNumber: type: string sipUri: type: string securitySchemes: ApiKeyHeader: type: apiKey in: header name: x-api-key description: Send your Callin API key in the `x-api-key` header. BearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'Same API key as a Bearer token: `Authorization: Bearer `.' ````