# Import an agent from another platform (/api-reference/agents/importAgent)

## POST /api/v1/agents/import

Operation ID: `importAgent`
Import an agent from another platform
Creates a **draft** agent from JSON exported from another platform. Review it,
then publish with publishAgent. Fields that have no equivalent, and values that had to be
approximated, are listed in `warnings` instead of failing the import.

| Our field | Vapi | Retell | Bland |
| --- | --- | --- | --- |
| name | `name` | `agent_name` | `name` |
| system prompt | system entries of `model.messages` | `llm.general_prompt` | `task` (or `prompt`) |
| greeting | `firstMessage` | `llm.begin_message` | `first_sentence` |
| language model | `model.model` | `llm.model` | `model` (Bland tiers map to the default) |
| temperature | `model.temperature` | `llm.model_temperature` | `temperature` |
| voice | `voice.provider` + `voice.voiceId` | `voice_id` | `voice` |
| transcriber | `transcriber.provider` | - | - |
| language | `transcriber.language` | `language` | `language` |
| speaking speed | `voice.speed` | `voice_speed` | - |
| call time limit | `maxDurationSeconds` | `max_call_duration_ms` | `max_duration` (minutes) |
| background sound | `backgroundSound` | `ambient_sound` | `background_track` |
| recording | `recordingEnabled` | - | `record` |

A voice or language that is not available here is replaced: first by a voice with the same id
or name, then by the language's default voice, with a warning. Tools, knowledge bases, webhooks
and multi-state flows are not imported. `callmitra` copies another workspace's agent config
(signing secrets are not copied).

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. |

### Request body

`application/json` (required)

```json
{
  "description": "An agent exported from another platform.",
  "properties": {
    "config": {
      "additionalProperties": true,
      "description": "The exported JSON: a Vapi assistant, a Retell agent (with its LLM as `llm`), a Bland call or agent configuration, or a Call Mitra agent from getAgent.",
      "title": "Config",
      "type": "object"
    },
    "source": {
      "description": "Platform the JSON comes from.",
      "enum": [
        "vapi",
        "retell",
        "bland",
        "callmitra"
      ],
      "title": "Source",
      "type": "string"
    }
  },
  "required": [
    "source",
    "config"
  ],
  "title": "AgentImportInput",
  "type": "object"
}
```

Example:

```json
{
  "config": {
    "firstMessage": "Hi, this is Riley from Acme Realty. Is now a good time?",
    "model": {
      "messages": [
        {
          "content": "You qualify home-buyer leads.",
          "role": "system"
        }
      ],
      "model": "gpt-4o",
      "provider": "openai"
    },
    "name": "Riley",
    "transcriber": {
      "language": "en",
      "provider": "deepgram"
    },
    "voice": {
      "provider": "11labs",
      "voiceId": "burt"
    }
  },
  "source": "vapi"
}
```

### Responses

#### 200 OK

Example (example):

```json
{
  "agent": {
    "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10",
    "name": "Riley",
    "status": "draft"
  },
  "success": true,
  "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'."
    }
  ]
}
```

#### 400 Bad request: `bad_request`.

Example (The request could not be processed.):

```json
{
  "detail": "The request could not be processed.",
  "error": {
    "code": "bad_request",
    "docUrl": "https://docs.callmitra.ai/errors/bad_request",
    "message": "The request could not be processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 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"
  }
}
```

#### 402 Payment required: `payment_required`.

Example (Your account does not have enough balance or an active plan for this request.):

```json
{
  "detail": "Your account does not have enough balance or an active plan for this request.",
  "error": {
    "code": "payment_required",
    "docUrl": "https://docs.callmitra.ai/errors/payment_required",
    "message": "Your account does not have enough balance or an active plan for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "billing_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"
  }
}
```

#### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`.

Example (This Idempotency-Key was already used with a different request body.):

```json
{
  "detail": "This Idempotency-Key was already used with a different request body.",
  "error": {
    "code": "idempotency_key_reused",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request body.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

Example (A request with this Idempotency-Key is still being processed.):

```json
{
  "detail": "A request with this Idempotency-Key is still being processed.",
  "error": {
    "code": "idempotency_request_in_progress",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress",
    "message": "A request with this Idempotency-Key is still being processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_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: `parameter_invalid`.

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

- [`bad_request`](/errors/bad_request)
- [`api_key_expired`](/errors/api_key_expired)
- [`invalid_api_key`](/errors/invalid_api_key)
- [`unauthenticated`](/errors/unauthenticated)
- [`payment_required`](/errors/payment_required)
- [`api_key_scope_denied`](/errors/api_key_scope_denied)
- [`permission_denied`](/errors/permission_denied)
- [`idempotency_key_reused`](/errors/idempotency_key_reused)
- [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress)
- [`payload_too_large`](/errors/payload_too_large)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`internal_error`](/errors/internal_error)
