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

> ## Agent Instructions
> Start with /introduction/getting-started. Use the Direct Query API (POST /api/lens/query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT is the base URL https://platform.u1.archetypeai.app with no version path; every endpoint path begins with /api. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# Copy Blueprint

> Copy any blueprint you can see into a project, under a new key

Requires [version 2.0.0](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-0) or later of the Archetype platform.

## Overview

This endpoint copies a blueprint into a [project](https://docs.archetypeai.app/api-reference/projects/about). The copy is a
new blueprint with its own `blp_` id, registered in the project under `blueprint_key`. It has the
same document as the original, apart from `name` and `description` when you give them, and a
`source` of kind `copy` that names the original.

Any blueprint you can see can be copied: a platform one, one of your organization's, or one in a
project, including the target project itself. Copying is how you reuse a blueprint in a project,
since a blueprint's project is fixed when it is created.

The original is named as in [Get Blueprint](https://docs.archetypeai.app/api-reference/agents/blueprints/get-blueprint.md): a
`blp_` id copies that exact version, and a key copies its active version. A key registered in a
project resolves only when `source_project_id` names that project. Either way, the copy's `source`
records the exact version copied.

## Request

**reference** `string` *required*

The blueprint to copy: a `blp_` id or a key (e.g. `osm`).

**project\_id** `string` *required*

The `prj_` id of the project to copy the blueprint into, which you must be able to modify.

**blueprint\_key** `string` *required*

The copy's key. Must not be in use in the project, by the organization's blueprints outside
projects, or by a platform blueprint.

**name** `string`

The copy's display name. Defaults to the original's.

**description** `string`

The copy's description. Defaults to the original's.

**source\_project\_id** `string`

The `prj_` id of the project to resolve the blueprint's key in, as well as outside projects.
Needed to copy a blueprint registered in a project by its key, even into that same project;
ignored for a `blp_` id.

## Response

Returns `201 Created` with the copy, in the same shape as [Get
Blueprint](https://docs.archetypeai.app/api-reference/agents/blueprints/get-blueprint.md).

**id** `string` *required*

TypeID-encoded identifier of the copy (`blp_` prefix).

**blueprint\_key** `string` *required*

The key the copy was registered under.

**name** `string` *required*

Display name of the copy.

**description** `string` *required*

Description of the copy. Empty when it has none.

**document** `object` *required*

The blueprint document, copied from the original and carrying the copy's `blueprint_id`.

**is\_canonical** `boolean` *required*

Always `false`: a copy belongs to your organization.

**is\_active** `boolean` *required*

`true` for the current version of a key.

**project\_id** `string` *required*

The project the copy lives in; this is the `project_id` you specified when calling this endpoint.

**source** `object` *required*

The origin of the copy: `kind` is `copy`, `blueprint_id` is the exact version copied, and
`blueprint_key` is that blueprint's key when it was copied.

**created\_at** `string` *required*

Creation timestamp (date-time).

```bash cURL theme={"system"}
curl -X POST "$ATAI_API_URL/api/agents/blueprints/red/copy" \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "prj_01jcd4m8t2vq6xn3r7k5hbzw9e",
    "blueprint_key": "line3-red",
    "name": "Line 3 rare event detection"
  }'
```

```python Python theme={"system"}
import os
import requests

base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]

response = requests.post(
    f"{base_url}/api/agents/blueprints/red/copy",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "project_id": "prj_01jcd4m8t2vq6xn3r7k5hbzw9e",
        "blueprint_key": "line3-red",
        "name": "Line 3 rare event detection",
    },
)

if response.status_code == 201:
    copy = response.json()
    print(f"Copied {copy['source']['blueprint_key']} to {copy['blueprint_key']} ({copy['id']})")
else:
    print(f"Error: {response.json()['errors']}")
```

```javascript JavaScript theme={"system"}
const response = await fetch(
  `${process.env.ATAI_API_URL}/api/agents/blueprints/red/copy`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      project_id: 'prj_01jcd4m8t2vq6xn3r7k5hbzw9e',
      blueprint_key: 'line3-red',
      name: 'Line 3 rare event detection'
    })
  }
);

const body = await response.json();

if (response.status === 201) {
  console.log(`Copied ${body.source.blueprint_key} to ${body.blueprint_key} (${body.id})`);
} else {
  console.error('Error:', body.errors);
}
```

```json 201 - Blueprint copied theme={"system"}
{
  "id": "blp_01jcd5q2w7k9vt4mx6n3rhzy8b",
  "blueprint_key": "line3-red",
  "name": "Line 3 rare event detection",
  "description": "Detects rare events in sensor streams.",
  "document": {
    "blueprint_id": "blp_01jcd5q2w7k9vt4mx6n3rhzy8b",
    "name": "Line 3 rare event detection",
    "graph": {"edges": []},
    "values": {},
    "artifacts": {}
  },
  "is_canonical": false,
  "is_active": true,
  "project_id": "prj_01jcd4m8t2vq6xn3r7k5hbzw9e",
  "source": {
    "kind": "copy",
    "blueprint_id": "blp_01jc9p4r8t2vx6mk3n5hqdzw7a",
    "blueprint_key": "red"
  },
  "created_at": "2026-10-28T09:20:31Z"
}
```

```json 400 - Invalid reference, key or name theme={"system"}
{
  "errors": [
    {
      "code": "<error_code>",
      "message": "Invalid reference, key or name.",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

```json 403 - Read-only access to the project theme={"system"}
{
  "errors": [
    {
      "code": "<error_code>",
      "message": "Read-only access to the project.",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

```json 404 - Blueprint or project not found theme={"system"}
{
  "errors": [
    {
      "code": "<error_code>",
      "message": "Blueprint or project not found.",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

```json 409 - The key is already in use theme={"system"}
{
  "errors": [
    {
      "code": "<error_code>",
      "message": "The key is already in use.",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

## Important Notes

> [!NOTE]
>
> * Copying is open to every role that can modify the target project, not only admins. Registering a blueprint into a project with [Create Blueprint](https://docs.archetypeai.app/api-reference/agents/blueprints/create-blueprint.md) requires the admin role.
> * In the free trial, only the platform blueprints the trial includes can be copied. Any other returns `403` with code `capability_locked`.
> * A `403` without that code means you have read-only access to the target project.
> * A `404` means the blueprint, the project, or the source project does not exist or is not visible to you.
> * A `409` means `blueprint_key` is already in use in the project, by your organization's blueprints outside projects, or by a platform blueprint.


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