# Build agents with the API (/guides/agents)

An **agent** is the voice AI that talks on your calls. It holds the script, the knowledge, the voice, the language and the call rules. This guide shows how to build one end to end with the API.

| Step | Endpoint |
| --- | --- |
| List agents | [`GET /api/v1/agents/`](/api-reference/agents/listAgents) |
| Create an agent | [`POST /api/v1/agents/`](/api-reference/agents/createAgent) |
| Import from another platform | [`POST /api/v1/agents/import`](/api-reference/agents/importAgent) |
| Read one agent | [`GET /api/v1/agents/{agent_id}`](/api-reference/agents/getAgent) |
| Save draft changes | [`PATCH /api/v1/agents/{agent_id}`](/api-reference/agents/updateAgent) |
| Publish the draft | [`POST /api/v1/agents/{agent_id}/publish`](/api-reference/agents/publishAgent) |
| Start taking calls | [`POST /api/v1/agents/{agent_id}/go-live`](/api-reference/agents/startAgent) |
| Stop taking calls | [`POST /api/v1/agents/{agent_id}/pause`](/api-reference/agents/pauseAgent) |
| Place a test call | [`POST /api/v1/agents/{agent_id}/test-call`](/api-reference/agents/testCallAgent) |
| Set the post-call webhook | [`PUT /api/v1/agents/{agent_id}/post-call-webhook`](/api-reference/webhooks/setAgentPostCallWebhook) |
| Delete an agent | [`DELETE /api/v1/agents/{agent_id}`](/api-reference/agents/deleteAgent) |
| List voices | [`GET /api/v1/voices/`](/api-reference/agents/listVoices) |
| List tools | [`GET /api/v1/tools/`](/api-reference/agents/listTools) |

All agent endpoints need an API key with the **Agents** resource ([Authentication](/authentication)). A read-only key can list and read agents, but cannot create or change them.

## Versions and lifecycle [#versions-and-lifecycle]

Every agent has two copies of its settings:

- **`config`** is the **published** version. Live calls, campaigns and test calls use it.
- **`draftConfig`** is the **working copy**. `PATCH` writes here. When there is no pending draft, `draftConfig` equals `config`.

`unpublishedChanges` is `true` while a draft is waiting to be published. Secrets inside the config (such as webhook signing secrets) are never returned.

Three fields describe where the agent is:

| Field | Values | Meaning |
| --- | --- | --- |
| `status` | `draft`, `published`, `archived` | `draft` until the first publish. |
| `takingCalls` | `true`, `false` | Set by go-live and pause. |
| `rosterState` | see below | One badge that combines the two, plus whether a number is assigned. |

| `rosterState` | When |
| --- | --- |
| `in_training` | The agent has never been published. |
| `paused` | Published, but `takingCalls` is `false`. |
| `ready` | Taking calls, but no phone number is assigned. |
| `live` | Published, taking calls, and a phone number is assigned. |
| `archived` | The agent is archived. |

The usual flow is:

<Steps>
<Step>
**Create** the agent. It starts as a draft (`rosterState` is `in_training`).
</Step>

<Step>
**Edit** it with `PATCH`. Each change lands in `draftConfig`.
</Step>

<Step>
**Publish** it. The draft becomes `config`.
</Step>

<Step>
**Test** it with a test call to your own phone.
</Step>

<Step>
**Go live** once a phone number is assigned. **Pause** it to stop new calls.
</Step>
</Steps>

## Create an agent [#create-an-agent]

Send a `name` and a `config`. Every field is optional, so `{}` creates an empty draft with default settings. In practice you send at least a language, a voice, a system prompt and a greeting:

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl -X POST https://api.callmitra.ai/api/v1/agents/ \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-agent-priya-001" \
  -d '{
    "name": "Priya",
    "config": {
      "language": "hi-IN",
      "stt": "sarvam",
      "tts": "sarvam",
      "voice": "priya",
      "llm_model": "gpt-4o-mini",
      "template_payload": {
        "system_prompt": "You are Priya from Acme Realty. Qualify the lead'\''s budget and preferred area.",
        "greeting_message": "Namaste, main Acme Realty se Priya bol rahi hoon."
      }
    }
  }'
```
</Tab>

<Tab value="Node.js">
```js
const res = await fetch('https://api.callmitra.ai/api/v1/agents/', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CALLMITRA_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'create-agent-priya-001',
  },
  body: JSON.stringify({
    name: 'Priya',
    config: {
      language: 'hi-IN',
      stt: 'sarvam',
      tts: 'sarvam',
      voice: 'priya',
      llm_model: 'gpt-4o-mini',
      template_payload: {
        system_prompt:
          "You are Priya from Acme Realty. Qualify the lead's budget and preferred area.",
        greeting_message: 'Namaste, main Acme Realty se Priya bol rahi hoon.',
      },
    },
  }),
});
const { agent } = await res.json();
```
</Tab>

<Tab value="Python">
```python
import os
import requests

res = requests.post(
    "https://api.callmitra.ai/api/v1/agents/",
    headers={
        "X-API-Key": os.environ["CALLMITRA_API_KEY"],
        "Idempotency-Key": "create-agent-priya-001",
    },
    json={
        "name": "Priya",
        "config": {
            "language": "hi-IN",
            "stt": "sarvam",
            "tts": "sarvam",
            "voice": "priya",
            "llm_model": "gpt-4o-mini",
            "template_payload": {
                "system_prompt": "You are Priya from Acme Realty. Qualify the lead's budget and preferred area.",
                "greeting_message": "Namaste, main Acme Realty se Priya bol rahi hoon.",
            },
        },
    },
    timeout=30,
)
agent = res.json()["agent"]
```
</Tab>
</Tabs>

The response holds the new agent (shortened here):

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

Body fields:

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | string | `""` | Display name, up to 255 characters. |
| `config` | object | defaults | The agent settings. See [Config reference](#config-reference). |
| `status` | `draft` or `published` | `draft` | Send `published` to publish on create. The language model check then runs too. |
| `sourceTemplateId`, `sourceTemplateSlug`, `sourceTemplateVersion` | string / integer | none | Optional record of the template you started from. |

On create and update, CallMitra checks that:

- `config` is at most **512 KB** as JSON (UTF-8) and nested at most 16 levels deep. A bigger config returns `413` [`payload_too_large`](/errors/payload_too_large); a deeper one returns `422` [`parameter_invalid`](/errors/parameter_invalid);
- every value is the right type and within its range or list of choices;
- `config.language` is an active language;
- `config.stt` is a speech-to-text provider that is available;
- `config.voice` exists for the `config.tts` provider and supports `config.language`;
- every tool URL (`base_url`, `url`, `server_url`, `endpoint`, or an absolute `path`) and `post_call_webhook.url` is a public `http(s)` address. Private, internal and loopback addresses are refused at save time;
- every `tools[].config.tool_id` is a tool in your workspace;
- the language model is ready to use (only when `status` is `published`, or when you publish).

A failed check returns `422` [`parameter_invalid`](/errors/parameter_invalid), with `param` set to the config path, for example `config.voice` or `config.tools.0.config.base_url`. If your plan has no room for another agent, you get [`payment_required`](/errors/payment_required).

`createAgent` accepts an `Idempotency-Key` header, so a retry does not create a second agent ([Idempotency](/idempotency)).

## Config reference [#config-reference]

Config keys are **snake_case** by design, unlike the camelCase used in the rest of the API. `config` uses the same shape CallMitra stores, and [agent import](/migrate/import-agents) produces that shape too, so the keys stay as they are. The tables list the fields the API accepts, with types, defaults and allowed values.

<Callout type="warn" title="Unknown keys are dropped, not refused">
A config key CallMitra does not know is ignored and not stored. You do not get an error for it. Check the spelling of every key, and read the agent back to confirm what was saved. Only a known key with a bad value returns `422`.
</Callout>

### Script and knowledge [#script-and-knowledge]

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `template_payload.system_prompt` | string | `""` | The instructions the agent follows. |
| `template_payload.greeting_message` | string | `""` | The first thing the agent says. |
| `template_payload.knowledge_base` | string | `""` | Free-text knowledge. |
| `system_prompt` | string | — | Write shortcut. Fills `template_payload.system_prompt` only when that is empty. |
| `greeting_message` | string | — | Write shortcut. Fills `template_payload.greeting_message` only when that is empty. |
| `script.opening` | string | `""` | Structured script: how the call opens. |
| `script.goal` | string | `""` | What the call should achieve. |
| `script.steps` | array of `{name, instruction}` | `[]` | Ordered call steps. |
| `script.end_rules` | array of strings | `[]` | When to end the call. |
| `script.closing` | string | `""` | How the call closes. |
| `script.strictness` | `flexible`, `balanced`, `strict` | `balanced` | How closely the agent follows the steps. |
| `script.ask_first_question_in_greeting` | boolean | — | Ask the first question in the greeting. |
| `knowledge.details` | array of `{key, label, value}` | `[]` | Business facts, such as hours or address. |
| `knowledge.items` | array of `{kind, q, text}` | `[]` | `kind` is `fact`, `qa`, `rule` or `objection`. |
| `knowledge.notes` | string | `""` | Extra notes. |
| `agent_mode` | `announcement`, `awareness`, `conversation`, `ivr_survey`, `survey` | `conversation` | The kind of call. |
| `job_role` | string | `""` | Up to 200 characters. |
| `success_criteria` | string | `""` | What a successful call looks like. Up to 4,000 characters. |
| `required_fields` | array of `{key, label, type}` | `[]` | Data to collect on the call. Up to 32. `type` is `string`, `number`, `email`, `phone`, `date` or `bool`. |

The script and knowledge together can hold up to **48,000 characters**. Older agents that use only a system prompt can hold up to 40,000. Over the limit, saving and publishing fail with [`agent_state_blocked`](/errors/agent_state_blocked).

### Voice [#voice]

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `tts` | string | `sarvam` | Text-to-speech provider. Use a `provider` value from [listVoices](#pick-a-voice). |
| `voice` | string | `""` | A `voiceId` from listVoices for the `tts` provider. |
| `agent_gender` | `female`, `male`, `any` | `any` | |
| `tone` | string | `natural` | |
| `caller_name` | string | `""` | The name the agent uses. Up to 120 characters. |
| `tts_speed` | number | `1.0` | From `0.5` to `1.5`. |
| `tts_volume` | number | `1.0` | From `0.2` to `1.0`. |
| `background_sound.enabled` | boolean | `false` | Play a background sound. |
| `background_sound.preset` | string | `off` | Sound name, for example `office`. |
| `background_sound.volume` | number | `0.5` | From `0.02` to `1.0`. |

### Language and speech-to-text [#language-and-speech-to-text]

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `language` | string | `en-IN` | Main language. Must be an active language from listVoices `languages`. |
| `extra_language` | string | `""` | A second language. |
| `auto_adapt_language` | boolean | `false` | Switch language to match the caller. |
| `stt` | `deepgram`, `openai`, `sarvam`, `soniox` | `deepgram` | Speech-to-text provider. |
| `noise_reduction` | `off`, `standard`, `strong` | `standard` | |

### Language model [#language-model]

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `llm_model` | string | `gpt-4o-mini` | The model that writes replies. |
| `temperature` | number | `0.55` | From `0` to `2`. |
| `max_tokens` | integer | `250` | From `1` to `32000`. Longest reply per turn. |
| `reasoning_effort` | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` | `minimal` | For reasoning models. |
| `voice_engine` | `pipeline`, `gemini_live`, `openai_realtime`, `elevenlabs_agents` | `pipeline` | `pipeline` chains speech-to-text, the model and text-to-speech. |
| `realtime_model`, `realtime_voice` | string | — | Used with a realtime `voice_engine`. |

### Turn-taking [#turn-taking]

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `interrupt_mode` | `time`, `words` | `time` | How the caller interrupts the agent. |
| `interrupt_min_speech_ms` | integer | `220` | From `100` to `2000`. Speech needed to interrupt, in `time` mode. |
| `interrupt_word_count` | integer | `2` | From `1` to `3`. Words needed to interrupt, in `words` mode. |
| `interruption_sensitivity` | `low`, `medium`, `high` | `medium` | |
| `conversation_engine` | `v1`, `v2` | `v1` | |

### Compliance [#compliance]

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `ai_disclosure` | boolean | `true` | The agent says it is an AI. |
| `recording_notice` | boolean | `true` | The agent says the call is recorded. |
| `call_recording` | boolean | `true` | Record the call. |

### Limits and calling [#limits-and-calling]

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `call_time_limit_seconds` | integer | `600` | From `10` to `3600`. The call ends at this limit. |
| `calling_mode` | `""`, `instant`, `bulk` | `""` | |

### Inline tools [#inline-tools]

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `tools` | array | `[]` | Inline tools. Up to 32. See [Tools](#tools). |
| `tools[].kind` | string | — | `end_call`, `transfer_call`, `api_request`, `function`, `mcp`, `lookup_open_tickets`, `create_ticket`, `add_ticket_note`, `schedule_callback` or `send_whatsapp`. |
| `tools[].name` | string | — | Up to 128 characters. |
| `tools[].description` | string | — | Up to 2,000 characters. Tells the model when to use the tool. |
| `tools[].enabled` | boolean | `true` | |
| `tools[].config` | object | `{}` | Kind-specific settings. For example `{"phone_number": "+919800000000"}` for `transfer_call`, or `{"base_url": "https://api.example.com", "path": "/orders", "method": "POST"}` for `api_request`. |

For an inline `api_request` tool, the host and method always come from the saved config:

- `base_url` must be a public `http(s)` address. An absolute `path` is used as the base only when `base_url` is empty.
- During a call, the model may only add a **relative** path under `base_url`, plus a JSON body. A path with a scheme, `//`, `..` segments, encoded slashes or control characters is refused.
- `method` is `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. The default is `POST`.
- Requests go only to public addresses and do not follow redirects.

### Post-call [#post-call]

| Field | Type | Notes |
| --- | --- | --- |
| `post_call_webhook` | object `{url, trigger}` | Prefer the [post-call webhook endpoint](#post-call-webhook). It applies at once and stores the signing secret safely. |

## Pick a voice [#pick-a-voice]

[`GET /api/v1/voices/`](/api-reference/agents/listVoices) lists the voices, providers and languages you can use. Filter with `provider` and `language`:

```bash
curl "https://api.callmitra.ai/api/v1/voices/?provider=sarvam&language=hi-IN" \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```

The response has three lists. The filters narrow `voices` only:

```json
{
  "success": true,
  "providers": [
    { "id": "sarvam", "name": "Sarvam", "count": 12, "previewSupported": true }
  ],
  "voices": [
    {
      "provider": "sarvam",
      "providerName": "Sarvam",
      "voiceId": "priya",
      "name": "Priya",
      "gender": "female",
      "languageCodes": ["hi-IN", "en-IN"],
      "sortOrder": 1,
      "previewSupported": true
    }
  ],
  "languages": [{ "id": "hi-IN", "name": "Hindi" }]
}
```

Copy three values into the config:

- `config.tts` = the voice's `provider`;
- `config.voice` = its `voiceId`;
- `config.language` = a language `id` that appears in the voice's `languageCodes`.

If the voice does not exist for that provider, or does not support the language, create and update return `422` [`parameter_invalid`](/errors/parameter_invalid) with `param` `config.voice`.

## Update an agent [#update-an-agent]

[`PATCH /api/v1/agents/{agent_id}`](/api-reference/agents/updateAgent) takes `name` and `config`, both optional.

- **Config changes go to the draft.** `config` (the published version) does not change until you publish. Live calls keep using the published version.
- **Only the top-level keys you send change.** Keys you leave out keep their draft values.
- **Nested objects are replaced, not merged.** If you send `script`, send the whole `script` object. Any `script` field you leave out is cleared.
- **`name` applies at once.** It changes the display name immediately and also sets `caller_name` in the draft.

```bash
curl -X PATCH https://api.callmitra.ai/api/v1/agents/3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10 \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "tts_speed": 1.1, "call_time_limit_seconds": 300 } }'
```

After this call, `unpublishedChanges` is `true` and `draftConfig` holds the new values.

`PATCH` returns:

- [`parameter_invalid`](/errors/parameter_invalid) for a bad value, voice or language;
- [`agent_state_blocked`](/errors/agent_state_blocked) when the script and knowledge are over the size limit, when the text uses an unknown `@` token, or when a webhook or `api_request` tool URL is not a public address.

## Publish [#publish]

[`POST /api/v1/agents/{agent_id}/publish`](/api-reference/agents/publishAgent) copies the draft into `config`, clears the draft and sets `status` to `published`. It takes no body.

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl -X POST https://api.callmitra.ai/api/v1/agents/3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10/publish \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```
</Tab>

<Tab value="Node.js">
```js
const agentId = '3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10';
const res = await fetch(
  `https://api.callmitra.ai/api/v1/agents/${agentId}/publish`,
  {
    method: 'POST',
    headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY },
  },
);
const { agent } = await res.json();
```
</Tab>

<Tab value="Python">
```python
agent_id = "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10"
res = requests.post(
    f"https://api.callmitra.ai/api/v1/agents/{agent_id}/publish",
    headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]},
    timeout=30,
)
agent = res.json()["agent"]
```
</Tab>
</Tabs>

Before it publishes, CallMitra checks the content size limit, `@` tokens, public URLs, the voice, and that the language model is ready. If a check fails, nothing is published and you get `422` [`agent_state_blocked`](/errors/agent_state_blocked). The `message` says what to fix.

Publishing does not change `takingCalls`. A live agent stays live and starts using the new version.

## Go live and pause [#go-live-and-pause]

[`POST /api/v1/agents/{agent_id}/go-live`](/api-reference/agents/startAgent) sets `takingCalls` to `true`.

- The agent needs a **phone number assigned**. Assign numbers in the console. You can see them in `assignedPhoneNumbers` and with [listPhoneNumbers](/api-reference/phone-numbers/listPhoneNumbers).
- An archived agent cannot go live.
- If the agent has never been published, or has a pending draft, go-live **publishes the draft first**. The same publish checks run.

If go-live is refused, you get [`agent_state_blocked`](/errors/agent_state_blocked).

[`POST /api/v1/agents/{agent_id}/pause`](/api-reference/agents/pauseAgent) sets `takingCalls` to `false`. The settings and the published version stay as they are. Call go-live again to resume.

## Test call [#test-call]

[`POST /api/v1/agents/{agent_id}/test-call`](/api-reference/agents/testCallAgent) calls a phone you choose, using one of your numbers as caller ID.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `phoneNumberId` | string | yes | The ID of one of your phone numbers, from [listPhoneNumbers](/api-reference/phone-numbers/listPhoneNumbers). |
| `destination` | string | yes | The phone to call. E.164 (`+919812345678`) or a local number. |
| `dynamicValues` | object | no | Values for placeholders in the script, for example `{"customer_name": "Asha"}`. |

```bash
curl -X POST https://api.callmitra.ai/api/v1/agents/3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10/test-call \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumberId": "8d1e4b2a-0c3f-4a5e-9b7d-6f2a1c3e5d70",
    "destination": "+919812345678",
    "dynamicValues": { "customer_name": "Asha" }
  }'
```

```json
{
  "success": true,
  "callId": "c2b7e9d4-1a3f-4e6b-8c5d-7f9a0b1c2d3e",
  "phoneNumber": "+919812345678",
  "message": "Test call initiated"
}
```

Read the result with [getCall](/api-reference/calls/getCall) using `callId`.

<Callout type="info" title="Test calls use the published version">
A test call runs `config`, not `draftConfig`. Publish your changes before you test them.
</Callout>

Test calls are not billed. Free plans have a cap on test calls. Errors:

| Code | When |
| --- | --- |
| [`resource_not_found`](/errors/resource_not_found) | `phoneNumberId` is not one of your numbers (`param` is `phoneNumberId`). |
| [`agent_test_call_failed`](/errors/agent_test_call_failed) | The call could not be placed, for example the free test-call cap is reached or the carrier refused it. |
| [`payment_required`](/errors/payment_required) | Your plan does not include this. |

## Post-call webhook [#post-call-webhook]

[`PUT /api/v1/agents/{agent_id}/post-call-webhook`](/api-reference/webhooks/setAgentPostCallWebhook) sets where CallMitra posts the result after each call this agent handles. It applies to the live agent at once, with no publish needed. A key with the **Agents** or **Webhooks** resource can call it.

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `url` | string | — | A public address, up to 2,000 characters. Send `""` to remove the webhook. |
| `secret` | string | — | Signing secret, up to 500 characters. Leave it out to keep the current secret. |
| `trigger` | `every`, `completed`, `voicemail` | `every` | Which calls send the webhook. |

```bash
curl -X PUT https://api.callmitra.ai/api/v1/agents/3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10/post-call-webhook \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/callmitra", "secret": "whsec_example", "trigger": "completed" }'
```

The response holds the agent and `webhook: {url, trigger, hasSecret}`. The secret itself is never returned. A campaign that has its own webhook uses that one instead. A URL that is not a public address returns [`agent_state_blocked`](/errors/agent_state_blocked).

For the payload and signature, see [Per-agent webhooks](/webhooks/campaign-agent-webhooks). For workspace-wide events, see [Webhooks](/webhooks).

## Tools [#tools]

Tools let the agent act during a call: end it, transfer it, call your API, create a ticket, and more.

- **Inline tools** live in `config.tools`. Add, change or remove them with `PATCH`, then publish. See [Inline tools](#inline-tools) in the config reference. The end-call tool is added for you.
- **Workspace tools** are shared tools you build in the console. The API can read them with [listTools](/api-reference/agents/listTools) and [getTool](/api-reference/agents/getTool), but cannot create them or attach them to an agent. Do both in the console.

A tool's credentials are never returned. `authSecretSet` tells you whether one is stored. An unknown tool ID returns [`tool_not_found`](/errors/tool_not_found).

## Delete an agent [#delete-an-agent]

[`DELETE /api/v1/agents/{agent_id}`](/api-reference/agents/deleteAgent) removes the agent permanently.

- Past calls keep their records.
- Campaigns that used the agent lose it. Starting such a campaign fails with [`campaign_has_no_agent`](/errors/campaign_has_no_agent) until you set a new agent.

To stop an agent without losing it, [pause](#go-live-and-pause) it instead.

## Errors [#errors]

Errors use the standard envelope ([Errors](/errors)):

```json
{
  "detail": "config.tts_speed must be a number from 0.5 to 1.5",
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "config.tts_speed must be a number from 0.5 to 1.5",
    "param": "config.tts_speed",
    "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69"
  }
}
```

| Code | Status | When |
| --- | --- | --- |
| [`parameter_invalid`](/errors/parameter_invalid) | 422 | A config value is the wrong type or out of range; the voice, language or speech-to-text provider is not available; a tool or webhook URL is not public; or a `tool_id` is not in your workspace. |
| [`payload_too_large`](/errors/payload_too_large) | 413 | `config` is larger than 512 KB. |
| [`agent_state_blocked`](/errors/agent_state_blocked) | 422 | Publish or go-live is refused, content is over the limit, or a URL is not public. |
| [`agent_not_found`](/errors/agent_not_found) | 404 | The agent ID does not exist in this workspace. |
| [`agent_test_call_failed`](/errors/agent_test_call_failed) | 400 | The test call could not be placed. |
| [`tool_not_found`](/errors/tool_not_found) | 404 | The tool ID does not exist. |
| [`payment_required`](/errors/payment_required) | 402 | Your plan's agent limit is reached, or the feature is not in your plan. |
| [`permission_denied`](/errors/permission_denied) | 403 | The key cannot write agents. |

## Related [#related]

- [Import agents](/migrate/import-agents) from Vapi, Retell or Bland
- [Run campaigns](/guides/campaigns) with your agent
- [Per-agent webhooks](/webhooks/campaign-agent-webhooks)
- [Idempotency](/idempotency)
- [Errors](/errors)