> ## 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="source" type="object">
  Where this blueprint came from, when it was not authored directly. Omitted for an authored
  blueprint. It names the blueprint that was customized and the exact overrides applied to it, so
  the derived blueprint's ancestry stays readable even after whatever produced it has been
  deleted. <Badge color="blue">[v1.1.12+](/release-notes/1.1.x#v1-1-12)</Badge>
</ResponseField>

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

### Source object (`source`) <Badge color="blue">[v1.1.12+](/release-notes/1.1.x#v1-1-12)</Badge>

<ResponseField name="blueprint_id" type="string" required>
  The blueprint this one was derived from.
</ResponseField>

<ResponseField name="values" type="object" required>
  Parameter value overrides applied on top of that blueprint's own.
</ResponseField>

<ResponseField name="models" type="object" required>
  Model slot overrides applied on top of that blueprint's own.
</ResponseField>

<ResponseField name="artifacts" type="object">
  Artifact locations applied on top of that blueprint's own, keyed by artifact name.
</ResponseField>

<ResponseField name="created_by" type="object" required>
  What produced this blueprint, as an id pair plus an optional label. The `id` prefix says what
  kind of thing it was: `otr_` is an optimization trial, whose `parent_id` is then the
  optimization run it belonged to.

  * `id` (string, required) — the producer itself; an `otr_` id for an optimization trial.
  * `parent_id` (string, required) — the run the producer belonged to; an `opt_` id for an optimization trial.
  * `name` (string) — the human label of the enclosing run, when one was given to it.
</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>

<ResponseField name="metrics" type="object">
  Optional metrics catalog: what an eval may score this blueprint against, as the blueprint
  itself publishes it. A blueprint publishing none cannot be evaluated. <Badge color="blue">[v1.1.12+](/release-notes/1.1.x#v1-1-12)</Badge>

  * `primary` (string, required) — the run's headline, as `<target>.<objective>`, naming a declared target and one of its objectives. Also the objective an optimization maximizes by default.
  * `targets` (array) — the targets this blueprint can be scored on. Exactly one is supported today.
</ResponseField>

### Metrics target (`document.metrics.targets[]`) <Badge color="blue">[v1.1.12+](/release-notes/1.1.x#v1-1-12)</Badge>

One thing the agent decides, and the unit an eval scores.

<ResponseField name="name" type="string" required>
  The target's name. Identifies it in the metrics report, in an eval request's `targets`
  overrides, and in each input's own declarations — where it is also the default name of the
  column the labels are read from.
</ResponseField>

<ResponseField name="type" type="string" required>
  The target's type. `category` — exactly one of N mutually exclusive classes per scored unit.
</ResponseField>

<ResponseField name="objectives" type="array" required>
  Every objective an eval may compute for this target: `macro_f1`, `accuracy`. Must be non-empty.
</ResponseField>

<ResponseField name="predicted" type="string" required>
  Where this target's decision is in the agent's output — the named output column that holds it.
</ResponseField>

<ResponseField name="labels" type="array">
  For a `category` target, the classes it predicts. A blueprint rarely knows them literally: they
  can be written as a `${…}` reference that is substituted only when the blueprint is resolved.
</ResponseField>

<ResponseField name="pairing" type="object">
  How this target's scored items are formed: what one scored thing is, and how a prediction is
  matched to the ground truth it is compared against. Two wire forms — the bare name
  (`pairing: by_time`) when every parameter defaults, and a single-key map
  (`pairing: {"by_time": {"downsampling": "majority_vote"}}`) when one does not.
</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": {},
      "metrics": {
        "primary": "state.macro_f1",
        "targets": [
          {
            "name": "state",
            "type": "category",
            "labels": "${models.classifier.parameters.states}",
            "objectives": ["macro_f1", "accuracy"],
            "predicted": "predicted_state",
            "pairing": "by_time"
          }
        ]
      }
    },
    "yaml_document": "name: Open-set monitor\ngraph:\n  edges: []\n",
    "is_canonical": true,
    "is_active": true,
    "created_at": "2026-08-11T14:32:07Z"
  }
  ```

  ```json 200 - Promoted from an optimization trial theme={"system"}
  {
    "id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
    "blueprint_key": "osm-otr-01jcb2v9h4x7mq3nt8k5rdzy6w",
    "name": "Open-set monitor",
    "description": "Classifies incoming records against a known class vocabulary.",
    "document": {
      "blueprint_id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
      "name": "Open-set monitor",
      "graph": {"edges": []},
      "values": {"window_size": 512},
      "artifacts": {"fit-classifier": "s3://.../fit-classifier"}
    },
    "yaml_document": null,
    "is_canonical": false,
    "is_active": true,
    "source": {
      "blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
      "values": {"window_size": 512},
      "models": {},
      "artifacts": {"fit-classifier": "s3://.../fit-classifier"},
      "created_by": {
        "id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
        "parent_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
        "name": "Window size sweep"
      }
    },
    "created_at": "2026-09-18T11:24:03Z"
  }
  ```

  ```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.
  * List every version of a key with `GET /agents/blueprints/{reference}/versions`. <Badge color="blue">[v1.1.12+](/release-notes/1.1.x#v1-1-12)</Badge>
  * `source` is present only on a derived blueprint — one promoted from an optimization trial, for example — and records the blueprint that was searched together with the overrides applied to it. <Badge color="blue">[v1.1.12+](/release-notes/1.1.x#v1-1-12)</Badge>
  * A blueprint without a `metrics` catalog in its document cannot be evaluated or optimized. <Badge color="blue">[v1.1.12+](/release-notes/1.1.x#v1-1-12)</Badge>
</Note>


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