curl "$ATAI_API_ENDPOINT/agents/blueprints/osm/versions" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints/blp_01jc9n7k3xf8mbq2v5t0ary6de/versions?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
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_ENDPOINT}/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,
"prev_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_ENDPOINT/agents/blueprints/osm/versions" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints/blp_01jc9n7k3xf8mbq2v5t0ary6de/versions?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
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_ENDPOINT}/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,
"prev_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
The
prj_ id of the project to resolve a key in, as well as outside projects. Needed for a key
registered in a project; ignored for a blp_ id. v2.0.0+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.Backward cursor: return versions newer than the one with this id. Pass the
prev_cursor of the current page to walk back. Mutually exclusive with after.Response
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.Cursor to step back the way this page was reached — pass it as
before after a forward page,
or as after after a backward one. null when the request carried no cursor. v1.1.13+Blueprint summary object
Human-readable key for this version. The active version holds the bare key; an archived one holds
<key>-<date>.True for platform-authored (gallery) blueprints shared with every org; false for blueprints owned by a specific org.
True for the current version of a key; false once it has been replaced by a newer blueprint.
The project the blueprint lives in, or
null if the blueprint doesn’t live in any project. v2.0.0+curl "$ATAI_API_ENDPOINT/agents/blueprints/osm/versions" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints/blp_01jc9n7k3xf8mbq2v5t0ary6de/versions?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
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_ENDPOINT}/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,
"prev_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
- A key registered in a project resolves only when
project_idnames that project. v2.0.0+ - 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 blueprint ids, and are mutually exclusive — send at most one of them. Passing both, or a malformed one, returns400.
Was this page helpful?