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

# List Blueprint Versions

> Page through every version registered under one blueprint key

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

## Overview

This endpoint returns all versions of one blueprint key as a cursor-paginated page of blueprint
summaries, newest first.

Each time a key is re-pointed at a new version with `replacement_of`, the previous blueprint is
archived under `<key>-<its creation date>` and flagged inactive. This endpoint walks that
history: the current active version plus every archived one.

`reference` accepts either the key itself or a `blp_` id, which is resolved to its key first — so
any version of a key is a valid way to ask for all of them.

## Request

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

<ParamField query="limit" type="integer" default="100">
  Page size. Minimum `1`, maximum `1000`.
</ParamField>

<ParamField query="after" type="string">
  Forward cursor: return versions older than the one with this id. Pass the `next_cursor` of the previous page (or the id of its last version) to fetch the next page. Mutually exclusive with `before`.
</ParamField>

<ParamField query="before" type="string">
  Backward cursor: return versions newer than the one with this id. Pass the id of the first version of the current page to walk back. Mutually exclusive with `after`.
</ParamField>

## Response

<ResponseField name="data" type="array" required>
  All versions of the key, newest first. Each entry is a blueprint summary.
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  True when more results exist beyond this page in the direction of travel.
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Cursor for the next page in the same direction — pass it as `after` when paging forward, or as `before` when you supplied `before`. `null` when `has_more` is false.
</ResponseField>

### Blueprint summary object

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

<ResponseField name="blueprint_key" type="string" required>
  Human-readable key for this version. The active version holds the bare key; an archived one holds `<key>-<date>`.
</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="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.
</ResponseField>

<ResponseField name="bundles_count" type="integer">
  Number of bundles visible to the caller's organization pinned to this blueprint. Present only when the read asked for it.
</ResponseField>

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

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

  ```bash cURL - By Id theme={"system"}
  curl "$ATAI_API_URL/agents/blueprints/blp_01jc9n7k3xf8mbq2v5t0ary6de/versions?limit=20" \
    -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"]
  headers = {"Authorization": f"Bearer {api_key}"}

  cursor = None
  while True:
      params = {"limit": 100}
      if cursor:
          params["after"] = cursor

      response = requests.get(f"{base_url}/agents/blueprints/osm/versions", headers=headers, params=params)
      page = response.json()

      for version in page["data"]:
          marker = "active" if version["is_active"] else "archived"
          print(f"{version['blueprint_key']} ({version['id']}) [{marker}] {version['created_at']}")

      if not page["has_more"]:
          break
      cursor = page["next_cursor"]
  ```

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

  const page = await response.json();

  page.data.forEach(version => {
    const marker = version.is_active ? 'active' : 'archived';
    console.log(`${version.blueprint_key} (${version.id}) [${marker}] ${version.created_at}`);
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={"system"}
  {
    "data": [
      {
        "id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
        "blueprint_key": "osm",
        "name": "Open-set monitor",
        "description": "Classifies incoming records against a known class vocabulary.",
        "is_canonical": true,
        "is_active": true,
        "created_at": "2026-08-11T14:32:07Z"
      },
      {
        "id": "blp_01jc8k2m9vr4te7hn5b3qdzx8w",
        "blueprint_key": "osm-2026-07-02",
        "name": "Open-set monitor",
        "description": "Classifies incoming records against a known class vocabulary.",
        "is_canonical": true,
        "is_active": false,
        "created_at": "2026-07-02T09:15:44Z"
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
  ```

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

  ```json 404 - No blueprint with this key theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "No blueprint with this key.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>

## Important Notes

<Note>
  * Passing a `blp_` id resolves it to its key first, so asking about any one version returns the whole history of that key.
  * At most one version of a key is active at a time; the rest carry `is_active: false` and an archived key of the form `<key>-<date>`.
  * Summaries omit the full blueprint document — fetch a single version by id with `GET /agents/blueprints/{reference}`.
  * `after` and `before` are mutually exclusive — send at most one of them.
</Note>


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