> ## Documentation Index > Fetch the complete documentation index at: https://docs.callva.io/llms.txt > Use this file to discover all available pages before exploring further. # Clone an agent > Requires permission: `agents.create`. What a token may call depends on its role: see [Authentication and permissions](/authentication). Body: `{ "name": "..." }` - optional; a name is derived from the source's when none is given. **What the copy carries:** everything that survives a stack swap - name, prompt, knowledge, greeting, who speaks first, farewell, duration and silence limits, prompt attempts and phrases, webhook configuration, overrides - plus the agent's active preset, **every** `agent_preset` row it holds, and **every** `agent_tool` row. Every row, because the point of the copy is to vary one stack while holding the others equal: a clone that dropped the stacks the operator was not currently looking at would make the comparison it exists to serve impossible. **What it deliberately does not carry:** - *Phone numbers.* `provisioned_phone_numbers.assigned_agent_id` is a single foreign key, so a number belongs to one agent and two agents cannot share it. The clone gets none, and the response says so rather than leaving the operator to discover it through an inbound call that never arrives. - *Default and system status.* The project already has a default agent, and a copy an operator asked for is theirs rather than the platform's. - *Calls, transcripts and webhook logs.* They are the history of the agent that made them. ## OpenAPI ````yaml /api-reference/openapi.json post /agents/{id}/clone openapi: 3.1.2 info: title: CallVA External API version: 1.0.0 description: >- The CallVA External API lets your own systems - or an autonomous agent acting for you - run a CallVA project: place calls, read and update call records, configure voice agents and their presets, manage custom fields, assets, webhook schedules, automations, phone numbers and projects. ## Authentication Every request carries an API token as a bearer token: `Authorization: Bearer `. Tokens are created in the dashboard; see the `bearerAuth` security scheme for how. ## Not every endpoint is open to every token Which endpoints a token can call depends on the role given to that token when it was created. A role is a set of permissions, such as `calls.read` or `agents.update`, and each endpoint below names the one permission it requires ("Requires permission: ...", and the `x-permission` field of the operation). A call to an endpoint whose permission the token's role does not hold answers `403` with `"code": "insufficient_permission"`; it never answers a partial result. To reach more endpoints, give the token a role that holds their permissions. ## Projects A project-scoped token works in its own project and needs nothing more. An organization-wide token names the project of each request: in the `X-Project-ID` header, or as `project_id` (in the query string for reads and deletes, in the body for writes). A request with no project answers `400` with `"code": "PROJECT_REQUIRED"`. ## Responses Every response is a JSON envelope: `{"success": true, "message": "...", "data": ...}`. Lists that are paginated add `pagination` (`current_page`, `last_page`, `per_page`, `total`, `from`, `to`); `per_page` sets the page size, up to the server's maximum, and `page` the page. A failure answers `{"success": false, "message": "...", "errors": {...}}`, with `errors` present where a field-level reason exists (`422`). servers: - url: https://api.callva.io/api/v1/external description: Production - url: https://staging.api.callva.io/api/v1/external description: Staging - url: https://api.dev.callva.io/api/v1/external description: Development security: - bearerAuth: [] tags: - name: Outbound calls description: >- Place an outbound call through the project's voice agent. Guide: [Calls and outbound dispatch](/guides/calls). - name: Calls description: >- Call records with the project's custom fields: list, filter, read, create, update, delete, and aggregate them. Guide: [Calls and outbound dispatch](/guides/calls). - name: Transcripts description: >- The transcript of a call. Guide: [Calls and outbound dispatch](/guides/calls). - name: Recordings description: >- The audio recording of a call. Guide: [Calls and outbound dispatch](/guides/calls). - name: Actions description: >- Record actions defined for the project, and pressing them on a call. Guide: [Authentication and permissions](/authentication). - name: Agents description: >- Voice agents: their prompt, behaviour and the configuration a call runs on. Guide: [Authentication and permissions](/authentication). - name: Presets description: >- The speech-stack presets an agent can run on, and an agent's configuration on each of them. Guide: [Authentication and permissions](/authentication). - name: Agent tools description: >- The tools an agent may call during a conversation. Guide: [Authentication and permissions](/authentication). - name: Assets description: >- Reusable prompt content that agents reference. Guide: [Authentication and permissions](/authentication). - name: Custom fields description: >- The project's data model: the fields every call record carries. Guide: [Custom fields](/guides/custom-fields). - name: Custom field groups description: >- How custom fields are grouped and ordered. Guide: [Custom fields](/guides/custom-fields). - name: Saved views description: >- Shared calls-list views of the project. Guide: [Authentication and permissions](/authentication). - name: Webhook schedules description: >- Rules that send scheduled webhooks for matching calls. Guide: [Webhooks](/guides/webhooks). - name: Webhook logs description: >- The webhooks the platform sent and what they answered. Guide: [Webhooks](/guides/webhooks). - name: Automations description: >- Scripts that run on platform events, on a schedule or on demand, and their runs. Guide: [Automations](/guides/automations). - name: Automation triggers description: >- HTTP triggers that start an automation from outside. Guide: [Automations](/guides/automations). - name: Variables description: >- Values and secrets that automations read. Guide: [Automations](/guides/automations). - name: Knowledge description: >- What the project holds true, and what not to do. Guide: [Authentication and permissions](/authentication). - name: Issues description: >- What was found to work or not work on calls. Guide: [Authentication and permissions](/authentication). - name: Projects description: >- The projects of the organization the token belongs to. Guide: [Quickstart](/quickstart). - name: Project settings description: 'The settings of the token''s project. Guide: [Webhooks](/guides/webhooks).' - name: Phone numbers description: >- The phone numbers the project calls from and answers on. Guide: [Authentication and permissions](/authentication). - name: Phone providers description: >- The telephony providers connected to the organization. Guide: [Authentication and permissions](/authentication). paths: /agents/{id}/clone: post: tags: - Agents summary: Clone an agent description: >- Requires permission: `agents.create`. What a token may call depends on its role: see [Authentication and permissions](/authentication). Body: `{ "name": "..." }` - optional; a name is derived from the source's when none is given. **What the copy carries:** everything that survives a stack swap - name, prompt, knowledge, greeting, who speaks first, farewell, duration and silence limits, prompt attempts and phrases, webhook configuration, overrides - plus the agent's active preset, **every** `agent_preset` row it holds, and **every** `agent_tool` row. Every row, because the point of the copy is to vary one stack while holding the others equal: a clone that dropped the stacks the operator was not currently looking at would make the comparison it exists to serve impossible. **What it deliberately does not carry:** - *Phone numbers.* `provisioned_phone_numbers.assigned_agent_id` is a single foreign key, so a number belongs to one agent and two agents cannot share it. The clone gets none, and the response says so rather than leaving the operator to discover it through an inbound call that never arrives. - *Default and system status.* The project already has a default agent, and a copy an operator asked for is theirs rather than the platform's. - *Calls, transcripts and webhook logs.* They are the history of the agent that made them. operationId: agents.clone parameters: - name: id in: path required: true schema: type: string - $ref: '#/components/parameters/ProjectId' requestBody: content: application/json: schema: type: object properties: name: type: - string - 'null' maxLength: 255 responses: '201': description: '' content: application/json: schema: type: object properties: success: type: boolean message: type: string const: Agent cloned successfully data: type: object properties: id: type: string name: type: - string - 'null' preset: type: string source_agent_id: type: string presets_copied: type: array description: >- Which stacks came across, named the way the operator chose them, so a caller can say what it copied without a second request. items: {} phone_numbers_copied: type: boolean description: >- Stated rather than implied: a single foreign key cannot be in two places, so the copy answers no number until one is moved to it. required: - id - name - preset - source_agent_id - presets_copied - phone_numbers_copied required: - success - message - data '400': description: '' content: application/json: schema: anyOf: - type: object properties: success: type: boolean message: type: string const: Project context required required: - success - message - type: object properties: success: type: boolean message: type: string const: Tenant context required required: - success - message '401': $ref: '#/components/responses/Unauthenticated' '403': description: '' content: application/json: schema: type: object properties: success: type: boolean message: type: string const: Insufficient permission. code: type: string const: insufficient_permission required: - success - message - code '404': description: '' content: application/json: schema: type: object properties: success: type: boolean message: type: string const: Agent not found required: - success - message '422': description: Validation error content: application/json: schema: anyOf: - type: object properties: success: type: boolean message: type: string const: Validation failed errors: type: object additionalProperties: type: array items: type: string required: - success - message - type: object properties: success: type: boolean message: type: string const: >- Cannot clone an agent in single-agent mode. Enable multi-agent in project settings first. required: - success - message - type: object properties: message: type: string description: Errors overview. errors: type: object description: >- A detailed description of each field that failed validation. additionalProperties: type: array items: type: string required: - message - errors '500': description: '' content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success - message components: parameters: ProjectId: name: X-Project-ID in: header description: >- The project this request acts in. Required with an organization-wide token (or send `project_id` instead); ignored with a project token, which always acts in its own project. schema: type: string format: uuid responses: Unauthenticated: description: The bearer token is missing, invalid, revoked or expired. content: application/json: schema: type: object properties: error: type: string examples: - Invalid or expired token message: type: string examples: - The provided token is invalid or has expired required: - error - message securitySchemes: bearerAuth: type: http description: >- A CallVA API token, sent as `Authorization: Bearer `. **Creating one.** In the CallVA dashboard, open the organization's Settings, then API Keys, and choose Create API Key: give the key a name, choose its role, and choose its project scope - All projects for an organization-wide token, or one project for a project token. The key is shown once, when it is created, and cannot be read again; store it then. Creating keys needs the `api_tokens.create` permission, which owners and admins hold, and a key cannot create another key. **Organization-wide or project token.** A project token works in the one project it was created for; any project named in the request is ignored. An organization-wide token reaches the projects of its organization, and each request names its project with the `X-Project-ID` header or `project_id` (query string for reads and deletes, body for writes). **What it can call.** The token's role decides which endpoints it may call; each endpoint names the permission it requires, and a token whose role lacks it is answered `403`. scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.