curl "$ATAI_API_URL/api/agents/packages/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/api/agents/packages/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0?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/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
headers={"Authorization": f"Bearer {api_key}"},
)
if response.status_code == 200:
package = response.json()
print(f"Package {package['id']} is {package['status']}")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/api/agents/packages/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
console.log(`Package ${body.id} is ${body.status}`);
} else {
console.error('Error:', body.errors);
}
{
"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"
}
{
"errors": [
{
"code": "not_found",
"message": "Package 'pkg_01jcb2x7m4qv8n3h5t6rk9dzs0' not found",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Packages
Get Package
Retrieve one package by id, with its build status and the model each slot resolved to
GET
/
api
/
agents
/
packages
/
{package_id}
curl "$ATAI_API_URL/api/agents/packages/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/api/agents/packages/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0?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/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
headers={"Authorization": f"Bearer {api_key}"},
)
if response.status_code == 200:
package = response.json()
print(f"Package {package['id']} is {package['status']}")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/api/agents/packages/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
console.log(`Package ${body.id} is ${body.status}`);
} else {
console.error('Error:', body.errors);
}
{
"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"
}
{
"errors": [
{
"code": "not_found",
"message": "Package 'pkg_01jcb2x7m4qv8n3h5t6rk9dzs0' not found",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 2.0.0 or later of the Archetype platform.
Overview
This endpoint returns one package by itspkg_ id.
Poll it after Create Package until status is
ready or failed. Run a ready package with Create
Agent.
Set include_latest_runs=true to attach the package’s most recent runs, so a package detail view
can show run history without a second call to /api/agents/instances. v2.0.0+
Request
string
required
Package
pkg_ id.boolean
default:"false"
Include the package’s most recent runs as
latest_runs. Off by default because it costs an
extra query. v2.0.0+Response
string
required
TypeID-encoded package identifier (
pkg_ prefix).string
required
Organization the package belongs to.
string
required
Human label given on create, or the blueprint’s name when none was given. Also the name of every
run of the package.
string
required
Human description given on create. Empty when none was given.
string
required
Subject id (
usr_... or key_...) that created the package.object
required
Where the package is meant to run, as
{"kind": "platform"} or {"kind": "edge"}.string
required
Build status:
building, ready, or failed. You can run the package once it is ready.array
required
The blueprints the package holds, in the order they were given.
string
required
The blueprint’s immutable
blp_ id.object
required
What each model slot resolved to when the package was built: slot name to an
mdl_ id (a model
from the model registry) or an aar_ id (an artifact an optimization trial produced, as named
in a promoted blueprint). Slots bound to an artifact the blueprint names itself are absent.
Empty when no slot named a registry entry.string
The project the package is in, which is its blueprint’s project.
null outside any project.string
required
When the package was built (date-time).
array
The package’s five most recent runs that you may see, newest first. Present only when the
request asked for it via
include_latest_runs=true; an empty array means none of its runs are
visible to you. v2.0.0+Run summary object (latest_runs[])
A thin slice of a run, without its name or connectors. Fetch the full run with Get
Agent.
string
required
TypeID-encoded agent identifier (
agt_ prefix).string
required
Agent lifecycle status, for example
deploying, running, completed, or failed.string
required
When the run was created (date-time).
string
When the run began executing. Absent until it has been dispatched.
string
When the run reached a terminal status. Absent while it is unfinished.
string
The executor’s job id for this run. Present once the run has been dispatched.
string
Why the run failed. Present only when
status is failed.curl "$ATAI_API_URL/api/agents/packages/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/api/agents/packages/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0?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/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
headers={"Authorization": f"Bearer {api_key}"},
)
if response.status_code == 200:
package = response.json()
print(f"Package {package['id']} is {package['status']}")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/api/agents/packages/pkg_01jcb2x7m4qv8n3h5t6rk9dzs0`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
console.log(`Package ${body.id} is ${body.status}`);
} else {
console.error('Error:', body.errors);
}
{
"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"
}
{
"errors": [
{
"code": "not_found",
"message": "Package 'pkg_01jcb2x7m4qv8n3h5t6rk9dzs0' not found",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
- A
404means the package does not exist, belongs to another organization, or is in a project you cannot see. - A
failedpackage cannot be run. Fix the blueprint and build a new package.
Was this page helpful?