> ## 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 /query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT must include the version path: /v0.5 for most APIs, /v0.6 for the Fine-Tuning Service. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# Create Blueprint

> Register a new blueprint, or a new version of an existing key

<Callout icon="clock" color="#3064E3" iconType="solid">
  Requires [version 1.1.9](/release-notes/1.1.x#v1-1-9) or later of the Archetype platform.
</Callout>

## Overview

This endpoint registers a blueprint under a human-readable **key** and returns the stored
blueprint with its assigned `blp_` ID.

Supply the blueprint as a JSON `document`, as a `yaml_document`, or as both. Set
`replacement_of` to re-point an existing key at a new version; the previous blueprint is
archived and flagged inactive, and bundles and agents pinned to it keep resolving it by ID.

## Request

<ParamField body="blueprint_key" type="string" required>
  Human-readable blueprint key as shown in the table below. The reference users put in agent
  configurations. A service-level catalog key (not part of the `agent_core` blueprint).

  | Blueprint Key | Blueprint Name                     |
  | ------------- | ---------------------------------- |
  | `mga`         | Manual Generation Agent            |
  | `osm`         | Operational State Monitoring Agent |
  | `red`         | Rare Event Detection Agent         |
  | `tva`         | Task Verification Agent            |
</ParamField>

<ParamField body="document" type="object">
  The blueprint document, in the `agent_core` shape. It carries the blueprint's own
  `name`/`description` and its `values`/`bundles`, the `connectors`/`nodes` id-keyed node maps,
  and a `graph` of edges. Any `blueprint_id` in the document is ignored — the service assigns
  one on store.

  <Note>
    **Optional:** Provide this parameter, `yaml_document`, or both. When only `yaml_document` is
    given, the document is parsed from it. When both are given, they must describe the same
    blueprint.
  </Note>
</ParamField>

<ParamField body="yaml_document" type="string">
  A YAML rendering of the blueprint (the same shape as `document`). Stored verbatim so authored
  comments/formatting are preserved and returned by the get endpoint.

  <Note>
    **Optional:** Provide this parameter, `document`, or both. When only this is provided,
    `document` is parsed from it; when both this parameter and `document` are provided, they
    must describe the same blueprint.
  </Note>
</ParamField>

<ParamField body="canonical" type="boolean" default="false">
  Set to `true` to publish a platform-authored (gallery) blueprint visible to every org; this
  requires the super-admin grant. Defaults to `false`, registering it under the caller's organization
  (which requires the admin role).
</ParamField>

<ParamField body="replacement_of" type="string">
  Replacement mode: the `blp_` id of the blueprint currently holding `blueprint_key`, which this
  request re-points to a new version. The previous blueprint is archived under
  `<blueprint_key>-<its creation date>` and flagged inactive; existing bundles/agents keep
  resolving it by id. Must be the current active holder of `blueprint_key` in the same scope
  (`canonical` or not); omit to create a blueprint under a new and unique key.
</ParamField>

### Blueprint document

<ParamField body="graph" type="object" required>
  The blueprint's edges: `{"edges": [{"from": "<node id>", "to": "<node id>"}]}`.
</ParamField>

<ParamField body="connectors" type="object">
  ID-keyed map of source/sink nodes. Each entry is `{"key": "<node key>", "config": {...}}`,
  where `key` is a node key from the node registry. Defaults to empty.
</ParamField>

<ParamField body="nodes" type="object">
  ID-keyed map of every non-connector node, in the same entry shape as `connectors`. Defaults to empty.
</ParamField>

<ParamField body="name" type="string">
  The blueprint's own name.
</ParamField>

<ParamField body="description" type="string">
  The blueprint's own description.
</ParamField>

<ParamField body="values" type="object">
  The blueprint's default values.
</ParamField>

<ParamField body="models" type="object">
  The blueprint's models.
</ParamField>

<ParamField body="artifacts" type="object">
  Map of artifact name to artifact reference (string values).
</ParamField>

<ParamField body="blueprint_id" type="string">
  Ignored on create — the service assigns the id when it stores the blueprint.
</ParamField>

## Response

Returns the stored blueprint.

<ResponseField name="id" type="string" required>
  TypeID-encoded blueprint identifier (`blp_` prefix).
</ResponseField>

<ResponseField name="blueprint_key" type="string" required>
  The key this blueprint was registered under.
</ResponseField>

<ResponseField name="name" type="string" required>
  Name of the blueprint.
</ResponseField>

<ResponseField name="description" type="string" required>
  Description of the blueprint.
</ResponseField>

<ResponseField name="document" type="object" required>
  The blueprint document, in the `agent_core` shape — the same format accepted on create, now carrying the assigned `blueprint_id`.
</ResponseField>

<ResponseField name="yaml_document" type="string">
  The YAML rendering of the blueprint, when included. Present when one was stored (or requested via `?yaml=true`); omitted otherwise.
</ResponseField>

<ResponseField name="is_canonical" type="boolean" required>
  True for platform-authored (gallery) blueprints shared with every org; false for blueprints owned by a specific org.
</ResponseField>

<ResponseField name="is_active" type="boolean" required>
  True for the current version of a key; false once it has been replaced by a newer blueprint (its key was archived to `<key>-<date>`). Bundles/agents pinned to an inactive blueprint keep working — the console can badge them.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  Creation timestamp (date-time).
</ResponseField>

<RequestExample>
  ```bash cURL - JSON Document theme={"system"}
  curl -X POST "$ATAI_API_URL/agents/blueprints" \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "blueprint_key": "osm",
      "document": {
        "name": "Open-set monitor",
        "description": "Classifies incoming records against a known class vocabulary.",
        "connectors": {
          "input": {"key": "<node_key>", "config": {}},
          "output": {"key": "<node_key>", "config": {}}
        },
        "nodes": {
          "classifier": {"key": "<node_key>", "config": {}}
        },
        "graph": {
          "edges": [
            {"from": "input", "to": "classifier"},
            {"from": "classifier", "to": "output"}
          ]
        },
        "values": {},
        "artifacts": {}
      }
    }'
  ```

  ```bash cURL - New Version Of A Key theme={"system"}
  curl -X POST "$ATAI_API_URL/agents/blueprints" \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "blueprint_key": "osm",
      "replacement_of": "blp_01jc8k2m9vr4te7hn5b3qdzx8w",
      "yaml_document": "name: Open-set monitor\ngraph:\n  edges: []\n"
    }'
  ```

  ```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}/agents/blueprints",
      headers={
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json",
      },
      json={
          "blueprint_key": "osm",
          "document": {
              "name": "Open-set monitor",
              "description": "Classifies incoming records against a known class vocabulary.",
              "connectors": {
                  "input": {"key": "<node_key>", "config": {}},
                  "output": {"key": "<node_key>", "config": {}},
              },
              "nodes": {
                  "classifier": {"key": "<node_key>", "config": {}},
              },
              "graph": {
                  "edges": [
                      {"from": "input", "to": "classifier"},
                      {"from": "classifier", "to": "output"},
                  ]
              },
          },
      },
  )

  if response.status_code == 201:
      blueprint = response.json()
      print(f"Created {blueprint['id']} under key {blueprint['blueprint_key']}")
  else:
      print(f"Error: {response.json()['errors']}")
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch(`${process.env.ATAI_API_URL}/agents/blueprints`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      blueprint_key: 'osm',
      document: {
        name: 'Open-set monitor',
        description: 'Classifies incoming records against a known class vocabulary.',
        connectors: {
          input: { key: '<node_key>', config: {} },
          output: { key: '<node_key>', config: {} }
        },
        nodes: {
          classifier: { key: '<node_key>', config: {} }
        },
        graph: {
          edges: [
            { from: 'input', to: 'classifier' },
            { from: 'classifier', to: 'output' }
          ]
        }
      }
    })
  });

  const body = await response.json();

  if (response.status === 201) {
    console.log(`Created ${body.id} under key ${body.blueprint_key}`);
  } else {
    console.error('Error:', body.errors);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 201 - Created theme={"system"}
  {
    "id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
    "blueprint_key": "osm",
    "name": "Open-set monitor",
    "description": "Classifies incoming records against a known class vocabulary.",
    "document": {
      "blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
      "name": "Open-set monitor",
      "description": "Classifies incoming records against a known class vocabulary.",
      "connectors": {
        "input": {"key": "<node_key>", "config": {}},
        "output": {"key": "<node_key>", "config": {}}
      },
      "nodes": {
        "classifier": {"key": "<node_key>", "config": {}}
      },
      "graph": {
        "edges": [
          {"from": "input", "to": "classifier"},
          {"from": "classifier", "to": "output"}
        ]
      },
      "values": {},
      "artifacts": {}
    },
    "yaml_document": null,
    "is_canonical": false,
    "is_active": true,
    "created_at": "2026-08-11T14:32:07Z"
  }
  ```

  ```json 400 - Invalid request theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Invalid request, or `replacement_of` does not match the given key/scope.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

  ```json 403 - Admin role required theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Admin role required (super-admin required for canonical blueprints).",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

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

  ```json 409 - Key or version conflict theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Blueprint key already exists, or `replacement_of` is no longer the active version.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>

## Important Notes

<Note>
  * Creating a blueprint requires the admin role; `canonical: true` requires the super-admin grant.
  * Omit `replacement_of` to create a blueprint under a new and unique key; a key that already exists returns `409`.
  * `replacement_of` must name the current active holder of `blueprint_key` in the same scope (canonical or org-owned).
  * Node keys used in `connectors` and `nodes` come from the node registry — see `GET /agents/nodes/registry`.
</Note>