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

# Replace assistant

> Save an assistant's whole configuration document at once, replacing the stored one.

Saves an assistant with a configuration document you send whole: the stored `config` is **replaced**, not merged into. Use it when you hold the complete document, for example one you read, edited in full and are saving back. To change part of an assistant, [update it](/api-reference/assistants/update) with `PATCH` instead.

`agent_name` and `agent_type` are optional here too, and anything you leave out of the body is untouched. Only a `config` you send replaces the stored one.

## Path parameters

<ParamField path="id" type="string" required>
  UUID of the assistant.
</ParamField>

## Body

At least one field is required.

<ParamField body="agent_name" type="string">
  New display name, 1–255 characters.
</ParamField>

<ParamField body="agent_type" type="string">
  New prompt style.
</ParamField>

<ParamField body="config" type="object">
  The whole configuration document. It **replaces** the stored one: missing settings are filled in with their defaults, so a key you leave out is reset, not kept. Native tools are not switched on for you, as they are on create: a tool your document leaves out of both `nativeTools` and `toolIds` is dropped, `end_call` included. One exception: a document without `kbStoreIds` keeps the assistant's knowledge-base links.
</ParamField>

<Warning>
  `{"config": {"systemPrompt": "…"}}` resets everything else in `config` to its default and drops the assistant's tools, `end_call` included, so it can no longer hang up. To change one setting, send the same body with [`PATCH`](/api-reference/assistants/update), or read the assistant, edit its `config` and send all of it back here.
</Warning>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.verbeo.ai/v1/assistant/550e8400-e29b-41d4-a716-446655440000" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "agent_name": "Customer Support (EU)" }'
  ```

  ```javascript Node.js theme={null}
  const id = "550e8400-e29b-41d4-a716-446655440000";

  // Read, edit, send the whole document back.
  const current = await fetch(`https://api.verbeo.ai/v1/assistant/${id}`, {
    headers: { Authorization: `Bearer ${process.env.VERBEO_API_KEY}` },
  }).then((r) => r.json());

  const config = current.data.config;
  config.settings.maxCallDuration = 5;

  const res = await fetch(`https://api.verbeo.ai/v1/assistant/${id}`, {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${process.env.VERBEO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ config }),
  });
  const { data: assistant } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  assistant_id = "550e8400-e29b-41d4-a716-446655440000"
  headers = {"Authorization": f"Bearer {os.environ['VERBEO_API_KEY']}"}

  current = requests.get(
      f"https://api.verbeo.ai/v1/assistant/{assistant_id}", headers=headers
  ).json()["data"]

  config = current["config"]
  config["settings"]["maxCallDuration"] = 5

  assistant = requests.put(
      f"https://api.verbeo.ai/v1/assistant/{assistant_id}",
      headers=headers,
      json={"config": config},
  ).json()["data"]
  ```
</CodeGroup>

## Response

`200 OK` with the updated assistant, its configuration completed and its `toolIds` re-checked.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_name": "Customer Support (EU)",
    "agent_type": "Single Prompt",
    "config": { "…": "the stored document" },
    "updated_at": "2026-01-23T09:12:00.000Z"
  }
}
```

## Native tools

`nativeTools` entries are three-state here as well. A tool your document does not mention keeps its row and stays switched on or off as it was, as long as its id stays in `toolIds`. Since the document replaces `toolIds` too, send the assistant's own `toolIds` back with it. To switch one tool on or off without restating the rest, use [`PATCH`](/api-reference/assistants/update#switching-a-native-tool-on-or-off).

## Errors

| Code | Status | When |
| - | - | - |
| `VALIDATION_FAILED` | 422 | An empty body, a blank `agent_name`, an unsupported `voice.voiceId`, a knowledge-base id from another workspace, or an enabled static transfer with no `staticDestination`. |
| `NOT_FOUND` | 404 | No such assistant, or it belongs to another workspace. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.