# Import agents (/migrate/import-agents)

[`POST /api/v1/agents/import`](/api-reference/agents/importAgent) turns an agent exported from another platform into a CallMitra agent. You send the source platform's JSON as it is. CallMitra maps what it can, replaces what is not available, and tells you about everything else in a list of `warnings`.

The new agent is always a **draft**. Nothing takes calls until you review it, publish it and go live.

## Request [#request]

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `source` | `vapi`, `retell`, `bland`, `callmitra` | yes | The platform the JSON comes from. |
| `config` | object | yes | The agent JSON exported from that platform, unchanged. |

What to send in `config` for each source:

| `source` | Send |
| --- | --- |
| `vapi` | The assistant object, as returned by Vapi's `GET /assistant/{id}`. |
| `retell` | `{"agent": {...}, "llm": {...}}` with the Retell agent and its Retell LLM. You can also send the agent object with the LLM fields merged into it, or put the LLM under `retell_llm`. |
| `bland` | The body of a Bland `POST /v1/calls` request, or a saved Bland agent config. |
| `callmitra` | A [getAgent](/api-reference/agents/getAgent) response, its `agent` object, `{name, config}`, or a bare config. |

There is no dry-run mode. Every successful request creates an agent. The endpoint accepts an `Idempotency-Key` header, so a retry does not create a second agent ([Idempotency](/idempotency)).

The API key needs the **Agents** resource, with write access ([Authentication](/authentication)).

## Response [#response]

```json
{
  "success": true,
  "agent": {
    "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10",
    "name": "Riley",
    "status": "draft"
  },
  "warnings": [
    { "field": "language", "message": "Language 'en' is not available; using en-IN." },
    { "field": "voice", "message": "Voice '11labs/burt' is not available; using sarvam voice 'shubh'." }
  ]
}
```

- `agent` is the full agent, the same shape as [getAgent](/api-reference/agents/getAgent) (shortened above). The imported settings are in `config`.
- `warnings` lists each value that was changed, replaced or not imported. Each item has the source `field` and a `message`. An empty list means everything mapped.

## How an import works [#how-an-import-works]

<Steps>
<Step>
**Map.** CallMitra reads the fields it knows for the source and writes them to CallMitra config keys. The tables below list them.
</Step>

<Step>
**Pick a language.** An exact match wins (case does not matter). If there is none, CallMitra uses a language with the same base, preferring the India variant (for example `hi` becomes `hi-IN`). If nothing matches, it uses `en-IN` and adds a warning.
</Step>

<Step>
**Pick a voice.** CallMitra looks for the same provider and voice ID that supports the language. Next it tries the same voice ID or name with any provider, and warns that it matched by name. If there is still no match, it uses the default voice for the language, or the first voice that supports it, and warns that the original voice is not available.
</Step>

<Step>
**Fill the gaps.** If the source sets no speech-to-text provider, CallMitra picks the default for the language. An unsupported language model is replaced with `gpt-4o-mini`, with a warning.
</Step>

<Step>
**Drop bad values.** Each value that would fail CallMitra's save checks (for example out of range) is removed, with a warning that starts `Not imported:`. The agent is created with the rest.
</Step>

<Step>
**Report the rest.** Every non-empty source field that CallMitra does not read gets the warning `Not imported: there is no matching setting.`
</Step>
</Steps>

A vendor value never makes the import fail. Text-to-speech provider names are matched loosely: `11labs`, `elevenlabs` and `eleven_labs` all mean `elevenlabs`, and `google` means `gemini`. An unknown provider is ignored and the voice is searched across all providers.

If the source has no name, the agent is called `Imported Vapi agent`, `Imported Retell agent`, `Imported Bland agent` or `Imported agent`.

## Field maps [#field-maps]

CallMitra config keys are listed as they appear in `config`. See the [config reference](/guides/agents#config-reference) for their ranges.

### Vapi [#vapi]

| Vapi field | CallMitra field | Notes |
| --- | --- | --- |
| `name` | agent name | |
| `model.messages` (role `system`) | `template_payload.system_prompt` | All system messages are joined. Other messages are skipped, with a warning. |
| `model.model` | `llm_model` | Must be a supported model, else `gpt-4o-mini` with a warning. |
| `model.provider` | — | `custom-llm` is not supported. You get a warning and the default model. |
| `model.temperature` | `temperature` | `0` to `2`. |
| `model.maxTokens` | `max_tokens` | `1` to `32000`. |
| `firstMessage` | `template_payload.greeting_message` | |
| `firstMessageMode` | — | `assistant-waits-for-user` is not supported, with a warning. The agent speaks first. |
| `voice.provider` + `voice.voiceId` | `tts` + `voice` | Resolved as described above. |
| `voice.speed` | `tts_speed` | Clamped to `0.5`–`1.5`, with a warning if changed. |
| `transcriber.provider` | `stt` | If CallMitra supports it. Otherwise a warning and the default. |
| `transcriber.language` | `language` | Resolved as described above. |
| `endCallMessage` | `template_payload.system_prompt` | Added to the end of the prompt as the closing line, with a warning. |
| `maxDurationSeconds` | `call_time_limit_seconds` | `10` to `3600`. |
| `backgroundSound` | `background_sound` | `off` turns it off. `office` and call-center sounds map to `office`. Any other value, such as a sound URL, also becomes `office`, with a warning. |
| `recordingEnabled`, `artifactPlan.recordingEnabled` | `call_recording` | |

Not imported, with a warning: `model.tools`, `model.toolIds`. Skipped without a warning: `id`, `orgId`, `createdAt`, `updatedAt`, `isServerUrlSecretSet`.

### Retell [#retell]

| Retell field | CallMitra field | Notes |
| --- | --- | --- |
| `agent_name` | agent name | |
| `llm.general_prompt` | `template_payload.system_prompt` | |
| `llm.begin_message` | `template_payload.greeting_message` | If `null`, you get a warning to add a greeting. |
| `llm.model` | `llm_model` | Must be a supported model, else `gpt-4o-mini` with a warning. |
| `llm.model_temperature` | `temperature` | `0` to `2`. |
| `voice_id` | `tts` + `voice` | A prefixed ID such as `11labs-Adrian` is split into provider `elevenlabs` and voice `adrian`. |
| `voice_speed` | `tts_speed` | `0.5` to `1.5`. |
| `volume` | `tts_volume` | `0.2` to `1.0`. |
| `language` | `language` | Resolved as described above. |
| `interruption_sensitivity` | `interruption_sensitivity` | Below `0.34` is `low`, below `0.67` is `medium`, otherwise `high`. |
| `ambient_sound` | `background_sound` | `null` or `off` turns it off. `office` and call-center sounds map to `office`. Any other value also becomes `office`, with a warning. |
| `max_call_duration_ms` | `call_time_limit_seconds` | Divided by 1,000. |

Not imported, with a warning: `llm.general_tools`, `llm.states` (multi-state flows), and a `response_engine.type` other than `retell-llm`. Skipped without a warning: `agent_id`, `version`, `is_published`, `last_modification_timestamp`, `llm_id`, `voice_model`, `starting_state`.

### Bland [#bland]

| Bland field | CallMitra field | Notes |
| --- | --- | --- |
| `name` | agent name | |
| `task` or `prompt` | `template_payload.system_prompt` | If both are set and differ, `task` is used, with a warning. |
| `first_sentence` | `template_payload.greeting_message` | |
| `voice` | `tts` + `voice` | Bland sends no provider, so the voice is matched by ID or name. |
| `language` | `language` | Resolved as described above. |
| `model` | `llm_model` | Bland model tiers are not supported. You get `gpt-4o-mini` with a warning. |
| `temperature` | `temperature` | `0` to `2`. |
| `max_duration` | `call_time_limit_seconds` | Minutes, multiplied by 60. |
| `record` | `call_recording` | |
| `background_track` | `background_sound` | `null` or `none` turns it off. `office` and call-center sounds map to `office`. Any other value also becomes `office`, with a warning. |

Skipped without a warning: `phone_number`, `from`, `agent_id`, `call_id`, `created_at`, `metadata`.

### CallMitra [#callmitra]

Use `source: "callmitra"` to copy an agent between workspaces. The config is copied as it is, including inline tools and the post-call webhook URL, with two exceptions. An inline tool whose `tool_id` is not a tool in **your** workspace, or whose URL is not a public `http(s)` address, is dropped as a whole. A post-call webhook URL that is not public is dropped too. Each drop adds a `Not imported:` warning.

The webhook signing secret is not copied, with a warning. Set it again with [setAgentPostCallWebhook](/api-reference/webhooks/setAgentPostCallWebhook).

## What never imports [#what-never-imports]

- Tools and function definitions from Vapi, Retell or Bland.
- Knowledge bases from other platforms.
- Webhooks and server URLs from other platforms.
- Multi-state flows (Retell `states`).
- Phone numbers.
- Custom LLM endpoints.
- Webhook signing secrets.

Rebuild these in CallMitra after the import. Inline tools go in `config.tools` ([Tools](/guides/agents#tools)).

## Errors [#errors]

The import fails only when the request itself cannot be served:

| Code | When |
| --- | --- |
| [`parameter_invalid`](/errors/parameter_invalid) | `source` is not one of the four values, or `config` is not an object or is nested more than 16 levels deep. Also when a value is refused and cannot be dropped. |
| [`payload_too_large`](/errors/payload_too_large) | `config` (the source JSON) is larger than 512 KB. |
| [`payment_required`](/errors/payment_required) | Your plan's agent limit is reached. |
| [`permission_denied`](/errors/permission_denied) | The key cannot write agents. |
| [`idempotency_key_reused`](/errors/idempotency_key_reused) | The `Idempotency-Key` was used before with a different body. |

See [Errors](/errors) for the envelope.

## Example: import a Vapi assistant [#example-import-a-vapi-assistant]

Fetch the assistant from Vapi, then send it as `config`:

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl -X POST https://api.callmitra.ai/api/v1/agents/import \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-vapi-riley-001" \
  -d '{
    "source": "vapi",
    "config": {
      "name": "Riley",
      "firstMessage": "Hi, this is Riley from Acme Realty. Is now a good time?",
      "model": {
        "provider": "openai",
        "model": "gpt-4o",
        "messages": [
          { "role": "system", "content": "You qualify home-buyer leads." }
        ]
      },
      "voice": { "provider": "11labs", "voiceId": "burt" },
      "transcriber": { "provider": "deepgram", "language": "en" }
    }
  }'
```
</Tab>

<Tab value="Node.js">
```js
// The assistant JSON you fetched from Vapi's GET /assistant/{id}.
const vapiAssistant = {
  name: 'Riley',
  firstMessage: 'Hi, this is Riley from Acme Realty. Is now a good time?',
  model: {
    provider: 'openai',
    model: 'gpt-4o',
    messages: [{ role: 'system', content: 'You qualify home-buyer leads.' }],
  },
  voice: { provider: '11labs', voiceId: 'burt' },
  transcriber: { provider: 'deepgram', language: 'en' },
};

const res = await fetch('https://api.callmitra.ai/api/v1/agents/import', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CALLMITRA_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'import-vapi-riley-001',
  },
  body: JSON.stringify({ source: 'vapi', config: vapiAssistant }),
});
const { agent, warnings } = await res.json();
for (const w of warnings) console.log(`${w.field}: ${w.message}`);
```
</Tab>

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

# The assistant JSON you fetched from Vapi's GET /assistant/{id}.
vapi_assistant = {
    "name": "Riley",
    "firstMessage": "Hi, this is Riley from Acme Realty. Is now a good time?",
    "model": {
        "provider": "openai",
        "model": "gpt-4o",
        "messages": [{"role": "system", "content": "You qualify home-buyer leads."}],
    },
    "voice": {"provider": "11labs", "voiceId": "burt"},
    "transcriber": {"provider": "deepgram", "language": "en"},
}

res = requests.post(
    "https://api.callmitra.ai/api/v1/agents/import",
    headers={
        "X-API-Key": os.environ["CALLMITRA_API_KEY"],
        "Idempotency-Key": "import-vapi-riley-001",
    },
    json={"source": "vapi", "config": vapi_assistant},
    timeout=30,
)
body = res.json()
for w in body["warnings"]:
    print(f"{w['field']}: {w['message']}")
```
</Tab>
</Tabs>

The response creates the draft agent `Riley`. In this example the language `en` and the ElevenLabs voice `burt` are not available, so the warnings show the replacements: `en-IN` and a Sarvam voice.

## After importing [#after-importing]

<Steps>
<Step>
**Read the warnings.** Then read the agent with [getAgent](/api-reference/agents/getAgent) and check `config`.
</Step>

<Step>
**Check the voice and language.** Pick a voice with [listVoices](/api-reference/agents/listVoices) and fix it with [`PATCH`](/api-reference/agents/updateAgent) if needed.
</Step>

<Step>
**Add what did not import.** Greeting, tools, knowledge, and the [post-call webhook](/api-reference/webhooks/setAgentPostCallWebhook).
</Step>

<Step>
**Assign a phone number** to the agent in the console.
</Step>

<Step>
**Publish** with [publishAgent](/api-reference/agents/publishAgent).
</Step>

<Step>
**Place a test call** with [testCallAgent](/api-reference/agents/testCallAgent).
</Step>

<Step>
**Go live** with [startAgent](/api-reference/agents/startAgent).
</Step>
</Steps>

## Related [#related]

- [Build agents with the API](/guides/agents)
- [Migrate to CallMitra](/migrate)
- [Idempotency](/idempotency)
- [Errors](/errors)