# Update an agent (/api-reference/agents/updateAgent)

## PATCH /api/v1/agents/{agent_id}

Operation ID: `updateAgent`
Update an agent
Saves the change as the agent's draft; calls keep using the published version until you call publishAgent. Only the `config` keys you send change; a nested object you send (for example `script`) replaces the stored one. Bad values are refused with `parameter_invalid` naming the field.

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `agent_id` | path | yes |  |

### Request body

`application/json` (required)

```json
{
  "description": "Fields to change. The change is saved as a draft; publish it with publishAgent.",
  "properties": {
    "config": {
      "anyOf": [
        {
          "additionalProperties": true,
          "description": "Agent configuration. Omitted keys keep their current (or default) value.\n\nKeys are snake_case by design: this object is the stored agent config and the\nshape importAgent produces, so it is saved and returned exactly as written here,\nwhile the rest of the API uses camelCase. A known key with a bad value is refused\nwith `parameter_invalid` and a `param` path such as `config.tts_volume`. Unknown keys\nare not refused: they are dropped without an error and do not appear in the saved config.",
          "properties": {
            "agent_gender": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Voice gender: `female`, `male` or `any`.",
              "title": "Agent Gender"
            },
            "agent_mode": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Kind of call the agent runs.",
              "enum": [
                "announcement",
                "awareness",
                "conversation",
                "ivr_survey",
                "survey"
              ],
              "title": "Agent Mode"
            },
            "ai_disclosure": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Tell the caller they are speaking to an AI agent.",
              "title": "Ai Disclosure"
            },
            "auto_adapt_language": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Follow the caller when they switch language.",
              "title": "Auto Adapt Language"
            },
            "background_sound": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/AgentBackgroundSound"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Background room tone."
            },
            "call_recording": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Record calls.",
              "title": "Call Recording"
            },
            "call_time_limit_seconds": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Hard limit on call length.",
              "maximum": 3600,
              "minimum": 10,
              "title": "Call Time Limit Seconds"
            },
            "caller_name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Name the agent introduces itself with.",
              "title": "Caller Name"
            },
            "calling_mode": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "`instant` answers new leads right away; `bulk` runs campaigns; empty means not set.",
              "enum": [
                "",
                "bulk",
                "instant"
              ],
              "title": "Calling Mode"
            },
            "conversation_engine": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Turn-taking engine version.",
              "enum": [
                "v1",
                "v2"
              ],
              "title": "Conversation Engine"
            },
            "extra_language": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Second language the agent may switch to, e.g. `hi-IN`.",
              "title": "Extra Language"
            },
            "greeting_message": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Shortcut for `template_payload.greeting_message` on write.",
              "title": "Greeting Message"
            },
            "interrupt_min_speech_ms": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Caller speech needed to interrupt (time mode).",
              "maximum": 2000,
              "minimum": 100,
              "title": "Interrupt Min Speech Ms"
            },
            "interrupt_mode": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "How the caller interrupts the agent: by speaking time or by word count.",
              "enum": [
                "time",
                "words"
              ],
              "title": "Interrupt Mode"
            },
            "interrupt_word_count": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Caller words needed to interrupt (words mode).",
              "maximum": 3,
              "minimum": 1,
              "title": "Interrupt Word Count"
            },
            "interruption_sensitivity": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "How easily the caller can interrupt.",
              "enum": [
                "low",
                "medium",
                "high"
              ],
              "title": "Interruption Sensitivity"
            },
            "job_role": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Job title the agent plays, e.g. `Sales associate`.",
              "title": "Job Role"
            },
            "knowledge": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/AgentKnowledgeConfig"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Structured knowledge."
            },
            "language": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Primary call language code from `GET /voices` languages, e.g. `en-IN`, `hi-IN`.",
              "title": "Language"
            },
            "llm_model": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Language model id, e.g. `gpt-4o-mini`, `gpt-4.1-mini`.",
              "title": "Llm Model"
            },
            "max_tokens": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Longest reply in tokens.",
              "maximum": 32000,
              "minimum": 1,
              "title": "Max Tokens"
            },
            "noise_reduction": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Background noise filtering.",
              "enum": [
                "off",
                "standard",
                "strong"
              ],
              "title": "Noise Reduction"
            },
            "post_call_webhook": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/AgentPostCallWebhookConfig"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Post-call webhook. Prefer setAgentPostCallWebhook, which also stores the signing secret."
            },
            "realtime_model": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Realtime speech model when `voice_engine` is not pipeline.",
              "title": "Realtime Model"
            },
            "realtime_voice": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Realtime voice when `voice_engine` is not pipeline.",
              "title": "Realtime Voice"
            },
            "reasoning_effort": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Reasoning effort for models that support it; lower is faster.",
              "enum": [
                "none",
                "minimal",
                "low",
                "medium",
                "high",
                "xhigh",
                "max"
              ],
              "title": "Reasoning Effort"
            },
            "recording_notice": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Tell the caller the call is recorded.",
              "title": "Recording Notice"
            },
            "required_fields": {
              "anyOf": [
                {
                  "items": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Values to collect on the call, as `{key, label, type}` objects.",
              "title": "Required Fields"
            },
            "script": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/AgentScriptConfig"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Structured call script."
            },
            "stt": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Speech-to-text provider id from the active catalog, for example `deepgram` or `sarvam`. An id that is not active is refused with `parameter_invalid`.",
              "title": "Stt"
            },
            "success_criteria": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "What counts as a successful call, for call analysis.",
              "title": "Success Criteria"
            },
            "system_prompt": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Shortcut for `template_payload.system_prompt` on write.",
              "title": "System Prompt"
            },
            "temperature": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Sampling temperature.",
              "maximum": 2,
              "minimum": 0,
              "title": "Temperature"
            },
            "template_payload": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/AgentPromptContent"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Free-form prompt content (system prompt, greeting, knowledge text)."
            },
            "tone": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Speaking style, e.g. `natural`, `friendly`, `formal`.",
              "title": "Tone"
            },
            "tools": {
              "anyOf": [
                {
                  "items": {
                    "$ref": "#/components/schemas/AgentToolConfig"
                  },
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Tools the agent may use (at most 32).",
              "title": "Tools"
            },
            "tts": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Text-to-speech provider id from `GET /voices` providers.",
              "title": "Tts"
            },
            "tts_speed": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Speaking speed; 1.0 is normal.",
              "maximum": 1.5,
              "minimum": 0.5,
              "title": "Tts Speed"
            },
            "tts_volume": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Voice loudness; 1.0 is full.",
              "maximum": 1,
              "minimum": 0.2,
              "title": "Tts Volume"
            },
            "voice": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Voice id (`voiceId`) from `GET /voices` for the `tts` provider.",
              "title": "Voice"
            },
            "voice_engine": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "`pipeline` uses separate speech-to-text, model and voice; the others use a single realtime speech model.",
              "enum": [
                "pipeline",
                "gemini_live",
                "openai_realtime",
                "elevenlabs_agents"
              ],
              "title": "Voice Engine"
            }
          },
          "title": "AgentConfig",
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "Config keys to change; omitted keys keep their current value. Nested objects are replaced."
    },
    "name": {
      "anyOf": [
        {
          "maxLength": 255,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "New display name.",
      "title": "Name"
    }
  },
  "title": "AgentUpdateInput",
  "type": "object"
}
```

Example:

```json
{
  "config": {
    "tts_speed": 1.1,
    "voice": "anushka"
  }
}
```

### Responses

#### 200 OK

Example (example):

```json
{
  "agent": {
    "config": {
      "language": "hi-IN",
      "llm_model": "gpt-4o-mini",
      "tts": "sarvam",
      "voice": "priya"
    },
    "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10",
    "language": "hi-IN",
    "name": "Priya",
    "rosterState": "in_training",
    "status": "draft",
    "takingCalls": false,
    "unpublishedChanges": true
  },
  "success": true
}
```

#### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`.

Example (The API key has expired.):

```json
{
  "detail": "The API key has expired.",
  "error": {
    "code": "api_key_expired",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_expired",
    "message": "The API key has expired.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (The API key is invalid or has been revoked.):

```json
{
  "detail": "The API key is invalid or has been revoked.",
  "error": {
    "code": "invalid_api_key",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (Authentication required.):

```json
{
  "detail": "Authentication required.",
  "error": {
    "code": "unauthenticated",
    "docUrl": "https://docs.callmitra.ai/errors/unauthenticated",
    "message": "Authentication required.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

#### 403 Forbidden: `api_key_scope_denied`, `permission_denied`.

Example (The API key does not have the scope required for this request.):

```json
{
  "detail": "The API key does not have the scope required for this request.",
  "error": {
    "code": "api_key_scope_denied",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied",
    "message": "The API key does not have the scope required for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (You do not have permission to perform this action.):

```json
{
  "detail": "You do not have permission to perform this action.",
  "error": {
    "code": "permission_denied",
    "docUrl": "https://docs.callmitra.ai/errors/permission_denied",
    "message": "You do not have permission to perform this action.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

#### 404 Not found: `agent_not_found`.

Example (Agent not found.):

```json
{
  "detail": "Agent not found.",
  "error": {
    "code": "agent_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/agent_not_found",
    "message": "Agent not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

#### 413 Payload too large: `payload_too_large`.

Example (The request body is too large.):

```json
{
  "detail": "The request body is too large.",
  "error": {
    "code": "payload_too_large",
    "docUrl": "https://docs.callmitra.ai/errors/payload_too_large",
    "message": "The request body is too large.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 422 Invalid parameters: `agent_state_blocked`, `parameter_invalid`.

Example (The agent cannot make this change yet.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "agent_state_blocked",
    "docUrl": "https://docs.callmitra.ai/errors/agent_state_blocked",
    "message": "The agent cannot make this change yet.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

Example (One or more parameters are invalid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "parameter_invalid",
    "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
    "message": "One or more parameters are invalid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 429 Too many requests: `rate_limit_exceeded`.

Example (Too many requests. Slow down and retry later.):

```json
{
  "detail": "Too many requests. Slow down and retry later.",
  "error": {
    "code": "rate_limit_exceeded",
    "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry later.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

#### 500 Server error: `internal_error`.

Example (Something went wrong on our side.):

```json
{
  "detail": "Something went wrong on our side.",
  "error": {
    "code": "internal_error",
    "docUrl": "https://docs.callmitra.ai/errors/internal_error",
    "message": "Something went wrong on our side.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

### Error codes

- [`api_key_expired`](/errors/api_key_expired)
- [`invalid_api_key`](/errors/invalid_api_key)
- [`unauthenticated`](/errors/unauthenticated)
- [`api_key_scope_denied`](/errors/api_key_scope_denied)
- [`permission_denied`](/errors/permission_denied)
- [`agent_not_found`](/errors/agent_not_found)
- [`payload_too_large`](/errors/payload_too_large)
- [`agent_state_blocked`](/errors/agent_state_blocked)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`internal_error`](/errors/internal_error)
