curl "$ATAI_API_URL/agents/blueprints/osm/versions" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/blueprints/blp_01jc9n7k3xf8mbq2v5t0ary6de/versions?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
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"]
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}`);
});
{
"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
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid reference or cursor.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "No blueprint with this key.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Blueprints
List Blueprint Versions
Page through every version registered under one blueprint key
GET
/
agents
/
blueprints
/
{reference}
/
versions
curl "$ATAI_API_URL/agents/blueprints/osm/versions" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/blueprints/blp_01jc9n7k3xf8mbq2v5t0ary6de/versions?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
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"]
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}`);
});
{
"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
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid reference or cursor.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "No blueprint with this key.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 1.1.12 or later of the Archetype platform.
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 withreplacement_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
string
required
Blueprint key (e.g.
osm) or a blp_ id (resolved to its key).integer
default:"100"
Page size. Minimum
1, maximum 1000.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.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.Response
array
required
All versions of the key, newest first. Each entry is a blueprint summary.
boolean
required
True when more results exist beyond this page in the direction of travel.
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.Blueprint summary object
string
required
TypeID-encoded blueprint identifier (
blp_ prefix).string
required
Human-readable key for this version. The active version holds the bare key; an archived one holds
<key>-<date>.string
required
Name of the blueprint.
string
required
Description of the blueprint.
boolean
required
True for platform-authored (gallery) blueprints shared with every org; false for blueprints owned by a specific org.
boolean
required
True for the current version of a key; false once it has been replaced by a newer blueprint.
integer
Number of bundles visible to the caller’s organization pinned to this blueprint. Present only when the read asked for it.
string
required
Creation timestamp (date-time).
curl "$ATAI_API_URL/agents/blueprints/osm/versions" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/blueprints/blp_01jc9n7k3xf8mbq2v5t0ary6de/versions?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
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"]
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}`);
});
{
"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
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid reference or cursor.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "No blueprint with this key.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
- 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: falseand 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}. afterandbeforeare mutually exclusive — send at most one of them.
Was this page helpful?