curl "$ATAI_API_ENDPOINT/agents/blueprints?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints?key=osm" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints?project_id=prj_01jcd4m8t2vq6xn3r7k5hbzw9e" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints?canonical_only=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints?bundles_count=true" \
-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", headers=headers, params=params)
page = response.json()
for blueprint in page["data"]:
print(f"{blueprint['blueprint_key']}: {blueprint['name']} ({blueprint['id']})")
if not page["has_more"]:
break
cursor = page["next_cursor"]
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/blueprints?limit=20`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(blueprint => {
console.log(`${blueprint.blueprint_key}: ${blueprint.name} (${blueprint.id})`);
});
if (page.has_more) {
console.log(`Next cursor: ${page.next_cursor}`);
}
{
"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": true,
"next_cursor": "blp_01jc8k2m9vr4te7hn5b3qdzx8w",
"prev_cursor": null
}
{
"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,
"bundles_count": 3,
"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,
"bundles_count": 0,
"created_at": "2026-07-02T09:15:44Z"
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"data": [],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid cursor.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Blueprints
List Blueprints
Page through the blueprint catalog
GET
/
agents
/
blueprints
curl "$ATAI_API_ENDPOINT/agents/blueprints?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints?key=osm" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints?project_id=prj_01jcd4m8t2vq6xn3r7k5hbzw9e" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints?canonical_only=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints?bundles_count=true" \
-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", headers=headers, params=params)
page = response.json()
for blueprint in page["data"]:
print(f"{blueprint['blueprint_key']}: {blueprint['name']} ({blueprint['id']})")
if not page["has_more"]:
break
cursor = page["next_cursor"]
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/blueprints?limit=20`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(blueprint => {
console.log(`${blueprint.blueprint_key}: ${blueprint.name} (${blueprint.id})`);
});
if (page.has_more) {
console.log(`Next cursor: ${page.next_cursor}`);
}
{
"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": true,
"next_cursor": "blp_01jc8k2m9vr4te7hn5b3qdzx8w",
"prev_cursor": null
}
{
"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,
"bundles_count": 3,
"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,
"bundles_count": 0,
"created_at": "2026-07-02T09:15:44Z"
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"data": [],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid cursor.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 1.1.9 or later of the Archetype platform.
Overview
This endpoint returns the blueprint catalog visible to the caller’s organization — the organization’s own blueprints plus the platform-authored (canonical) ones — as a cursor-paginated page of blueprint summaries, newest first. Summaries omit the full blueprint document — fetch a single blueprint withGET /agents/blueprints/{reference} when you need its document or yaml_document.
Request
Forward cursor: return blueprints older than the one with this id. Pass the
next_cursor of the previous page to fetch the next page. Mutually exclusive with before.Backward cursor: return blueprints newer than the one with this id. Pass the
prev_cursor of the current page to walk back. Mutually exclusive with after.Filter by project. Omitted: the platform blueprints, your
organization’s blueprints outside projects, and those of every project you can see. A project’s
prj_ id: that project’s blueprints only (404 when it does not exist or you cannot see it).
none: lists the blueprints outside any project, platform ones included. v2.0.0+When
true, returns only the platform-authored (canonical) blueprints and leaves out your
organization’s own blueprints. Omitted or false: both. Canonical blueprints are never in a
project, so canonical_only=true with a project_id other than none returns 400. v2.0.1+When
true, each item carries bundles_count — the number of bundles visible to the caller’s
organization pinned to that blueprint. v1.1.11+When
true, the response includes total. Off by default because it costs an extra count per
request. v2.0.1+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.How many blueprints match the request’s filters across all pages, ignoring
limit and the cursor.
Present only when you set include_total=true. v2.0.1+Blueprint summary object
Human-readable key for the blueprint, e.g.
osm. An archived version’s key carries a -<date>
suffix.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 (its key was archived to
<key>-<date>).The project the blueprint lives in, or
null if the blueprint lives outside any project. v2.0.0+Number of bundles visible to the caller’s organization — its own plus canonical ones — pinned to this
blueprint. Present only when the list was requested with
bundles_count=true; omitted
otherwise. A blueprint with no matching bundles reports 0. v1.1.11+curl "$ATAI_API_ENDPOINT/agents/blueprints?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints?key=osm" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints?project_id=prj_01jcd4m8t2vq6xn3r7k5hbzw9e" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints?canonical_only=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/blueprints?bundles_count=true" \
-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", headers=headers, params=params)
page = response.json()
for blueprint in page["data"]:
print(f"{blueprint['blueprint_key']}: {blueprint['name']} ({blueprint['id']})")
if not page["has_more"]:
break
cursor = page["next_cursor"]
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/blueprints?limit=20`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const page = await response.json();
page.data.forEach(blueprint => {
console.log(`${blueprint.blueprint_key}: ${blueprint.name} (${blueprint.id})`);
});
if (page.has_more) {
console.log(`Next cursor: ${page.next_cursor}`);
}
{
"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": true,
"next_cursor": "blp_01jc8k2m9vr4te7hn5b3qdzx8w",
"prev_cursor": null
}
{
"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,
"bundles_count": 3,
"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,
"bundles_count": 0,
"created_at": "2026-07-02T09:15:44Z"
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"data": [],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid cursor.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
afterandbeforeare blueprint ids, and are mutually exclusive — send at most one of them. Passing both, or a malformed one, returns400.- Results are ordered newest first in both cursor directions, so render
dataas returned. - Without
project_id, the page includes the blueprints of every project you can see. Passproject_id=noneto leave project blueprints out. Aproject_idthat does not exist or that you cannot see returns404. v2.0.0+ canonical_only=truecannot be combined with aproject_idother thannone; that pair returns400. Omitproject_idor passproject_id=none. v2.0.1+- An archived (replaced) blueprint stays in the catalog with
is_active: falseand a key of the form<key>-<date>. bundles_count=truecounts only the bundles visible to the caller’s organization — its own plus canonical ones — so the count is per-viewer. The count is computed over the blueprints on the current page. v1.1.11+
Was this page helpful?