> ## 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.

# Get Blueprint

> Retrieve a single blueprint, including its full document

<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 returns one blueprint, addressed either by its immutable `blp_` id or by its key.

Unlike the list endpoint, the response carries the full blueprint `document`, and optionally its YAML rendering.

## Request

<ParamField path="reference" type="string" required>
  Blueprint `blp_` id or key (e.g. `osm`).
</ParamField>

<ParamField query="yaml" type="boolean">
  Controls the `yaml_document` in the response. Omitted: include the stored YAML if one exists. `true`: always include, generating it from the document when none is stored. `false`: never include.
</ParamField>

## Response

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

<ResponseField name="blueprint_key" type="string" required>
  Human-readable key for the blueprint, e.g. `osm`.
</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. See the `yaml` query parameter.
</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>

### Blueprint document fields

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

<ResponseField name="blueprint_id" type="string">
  The assigned blueprint id, echoed inside the document.
</ResponseField>

<ResponseField name="connectors" type="object">
  Id-keyed map of source/sink nodes. Each entry is `{"key": "<node key>", "config": {...}}`.
</ResponseField>

<ResponseField name="nodes" type="object">
  Id-keyed map of every non-connector node, in the same entry shape as `connectors`.
</ResponseField>

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

<ResponseField name="description" type="string">
  The blueprint's own description.
</ResponseField>

<ResponseField name="values" type="object">
  The blueprint's default values.
</ResponseField>

<ResponseField name="models" type="object">
  The blueprint's models.
</ResponseField>

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

<RequestExample>
  ```bash cURL - By Key theme={"system"}
  curl "$ATAI_API_URL/agents/blueprints/osm" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

  ```bash cURL - By Id, With YAML theme={"system"}
  curl "$ATAI_API_URL/agents/blueprints/blp_01jc9n7k3xf8mbq2v5t0ary6de?yaml=true" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

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

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

  response = requests.get(
      f"{base_url}/agents/blueprints/osm",
      headers={"Authorization": f"Bearer {api_key}"},
      params={"yaml": "true"},
  )

  if response.status_code == 200:
      blueprint = response.json()
      print(f"{blueprint['name']} ({blueprint['id']}), active={blueprint['is_active']}")
      print(blueprint.get("yaml_document"))
  else:
      print(f"Error: {response.json()['errors']}")
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch(
    `${process.env.ATAI_API_URL}/agents/blueprints/osm?yaml=true`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
      }
    }
  );

  const body = await response.json();

  if (response.ok) {
    console.log(`${body.name} (${body.id}), active=${body.is_active}`);
    console.log(body.yaml_document);
  } else {
    console.error('Error:', body.errors);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success 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": "name: Open-set monitor\ngraph:\n  edges: []\n",
    "is_canonical": true,
    "is_active": true,
    "created_at": "2026-08-11T14:32:07Z"
  }
  ```

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

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

## Important Notes

<Note>
  * `reference` accepts either a `blp_` id or a blueprint key, so the same URL shape works for both.
  * Ask for `?yaml=true` when you want YAML even for a blueprint that was created from JSON — the service renders it from the document.
  * A blueprint with `is_active: false` has been replaced by a newer version of its key; it remains readable by id.
</Note>