curl "$ATAI_API_URL/api/agents/packages?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/api/agents/packages?blueprint_id=blp_01jc9n7k3xf8mbq2v5t0ary6de" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/api/agents/packages?sort=last_run_at&include_latest_runs=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.get(
f"{base_url}/api/agents/packages",
headers={"Authorization": f"Bearer {api_key}"},
params={"limit": 20},
)
if response.status_code == 200:
page = response.json()
for package in page["data"]:
print(package["id"], package["status"])
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/api/agents/packages?limit=20`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
body.data.forEach((pkg) => console.log(pkg.id, pkg.status));
} else {
console.error('Error:', body.errors);
}
{
"data": [
{
"id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"name": "Pump line 3",
"description": "Pump A monitor",
"created_by": "usr_01jc8m6t3wr0yv5cp8j4mezt7x",
"target": {"kind": "platform"},
"status": "ready",
"blueprints": [
{
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"resolved_models": {
"embedder": "mdl_01jc7k2p9xq4vm8n3t5rbh6dzw"
}
}
],
"project_id": null,
"created_at": "2026-10-21T15:10:00Z"
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid cursor or `blueprint_id`, or both `after` and `before`.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Packages
List Packages
Page through your organization’s packages, sorted by build, last run or name, searched, and filtered by blueprint or project
GET
/
api
/
agents
/
packages
curl "$ATAI_API_URL/api/agents/packages?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/api/agents/packages?blueprint_id=blp_01jc9n7k3xf8mbq2v5t0ary6de" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/api/agents/packages?sort=last_run_at&include_latest_runs=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.get(
f"{base_url}/api/agents/packages",
headers={"Authorization": f"Bearer {api_key}"},
params={"limit": 20},
)
if response.status_code == 200:
page = response.json()
for package in page["data"]:
print(package["id"], package["status"])
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/api/agents/packages?limit=20`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
body.data.forEach((pkg) => console.log(pkg.id, pkg.status));
} else {
console.error('Error:', body.errors);
}
{
"data": [
{
"id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"name": "Pump line 3",
"description": "Pump A monitor",
"created_by": "usr_01jc8m6t3wr0yv5cp8j4mezt7x",
"target": {"kind": "platform"},
"status": "ready",
"blueprints": [
{
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"resolved_models": {
"embedder": "mdl_01jc7k2p9xq4vm8n3t5rbh6dzw"
}
}
],
"project_id": null,
"created_at": "2026-10-21T15:10:00Z"
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid cursor or `blueprint_id`, or both `after` and `before`.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 2.0.0 or later of the Archetype platform.
Overview
This endpoint returns a cursor-paginated page of your organization’s packages. By default the page is newest built first. By default the page holds the packages outside projects and those of every project you can see. Narrow it to one project, or to the packages outside any project, withproject_id. Narrow it to
the packages holding one blueprint with blueprint_id: those are the packages that keep the
blueprint from being deleted. Search by name, description or id with query.
Set include_latest_runs=true to attach each package’s most recent runs, so run history can be
rendered without a second call to /api/agents/instances.
Choose a different ordering with the sort and order parameters.
Request
integer
default:"100"
Page size. Minimum
1, maximum 1000.string
Forward cursor: return the packages ranked after it in the current sort order. Pass the
next_cursor of the previous page to fetch the next page. The cursor is opaque: never build it
from package fields. Mutually exclusive with before.string
Backward cursor: return the packages ranked before it in the current sort order. Pass the
prev_cursor of the current page to walk back. The cursor is opaque: never build it from
package fields. Mutually exclusive with after.string
default:"created_at"
Sort field:
created_at (default) ranks packages by when they were built, last_run_at by the
newest of their runs you may see, with never-run packages last under desc, and name alphabetically, ignoring case. A cursor is only
valid under the sort it was minted for. Replaying it with a different sort is rejected with
HTTP status code 400.string
Sort direction:
asc or desc. Defaults per field: desc for created_at and last_run_at,
asc for name. Keep it constant while paging with a cursor: a cursor replayed
under the other order is accepted but pages the other way from it.string
Case-insensitive substring match over the package name, description and id. Omit for no search
filter.
boolean
default:"false"
Include each package’s most recent runs as
latest_runs. Off by default because it costs an
extra query per page.string
Restrict to packages holding this blueprint (
blp_ id, exact match).string
Filter by project. Omitted: the packages outside projects and those of every project you can
see. A project’s
prj_ id: that project’s packages only (404 when it does not exist or you
cannot see it). none: the packages outside any project.Response
array
required
The page, in the requested
sort and order (by default newest built first) in both cursor
directions. Each entry is a package, with the same fields as Get
Package returns, including latest_runs when you
set include_latest_runs=true.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.string
Cursor to step back the way this page was reached. Pass it as
before after paging forward, or
as after after paging backward. null on a request that carried no cursor.curl "$ATAI_API_URL/api/agents/packages?limit=20" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/api/agents/packages?blueprint_id=blp_01jc9n7k3xf8mbq2v5t0ary6de" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/api/agents/packages?sort=last_run_at&include_latest_runs=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.get(
f"{base_url}/api/agents/packages",
headers={"Authorization": f"Bearer {api_key}"},
params={"limit": 20},
)
if response.status_code == 200:
page = response.json()
for package in page["data"]:
print(package["id"], package["status"])
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/api/agents/packages?limit=20`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
body.data.forEach((pkg) => console.log(pkg.id, pkg.status));
} else {
console.error('Error:', body.errors);
}
{
"data": [
{
"id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"name": "Pump line 3",
"description": "Pump A monitor",
"created_by": "usr_01jc8m6t3wr0yv5cp8j4mezt7x",
"target": {"kind": "platform"},
"status": "ready",
"blueprints": [
{
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"resolved_models": {
"embedder": "mdl_01jc7k2p9xq4vm8n3t5rbh6dzw"
}
}
],
"project_id": null,
"created_at": "2026-10-21T15:10:00Z"
}
],
"has_more": false,
"next_cursor": null,
"prev_cursor": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid cursor or `blueprint_id`, or both `after` and `before`.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
- Passing both
afterandbeforereturns400, as does a malformedblueprint_id, a repeated parameter, or a parameter of the wrong type. - A malformed cursor, or a cursor replayed under a different
sort, returns400. - A
project_idthat does not exist or that you cannot see returns404.
Was this page helpful?