curl -X POST "$ATAI_API_URL/api/agents/packages" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"blueprint_ids": ["blp_01jc9n7k3xf8mbq2v5t0ary6de"],
"target": {"kind": "platform"},
"name": "Pump line 3",
"description": "Pump A monitor"
}'
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.post(
f"{base_url}/api/agents/packages",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"blueprint_ids": ["blp_01jc9n7k3xf8mbq2v5t0ary6de"],
"target": {"kind": "platform"},
"name": "Pump line 3",
"description": "Pump A monitor",
},
)
if response.status_code == 202:
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`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
blueprint_ids: ['blp_01jc9n7k3xf8mbq2v5t0ary6de'],
target: { kind: 'platform' },
name: 'Pump line 3',
description: 'Pump A monitor'
})
});
const body = await response.json();
if (response.status === 202) {
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": "<error_code>",
"message": "Invalid request, or a blueprint that cannot be resolved or could not run.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "capability_locked",
"message": "Blueprint not available to the caller's organization.",
"suggestion": "Contact [email protected] to unlock it.",
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "not_found",
"message": "A blueprint, or a model tag, model id or artifact one of its slots names, was not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "not_supported",
"message": "edge packages are not supported yet",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Packages
Create Package
Build an immutable package from a blueprint so you can run it as a batch job or a serving agent
POST
/
api
/
agents
/
packages
curl -X POST "$ATAI_API_URL/api/agents/packages" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"blueprint_ids": ["blp_01jc9n7k3xf8mbq2v5t0ary6de"],
"target": {"kind": "platform"},
"name": "Pump line 3",
"description": "Pump A monitor"
}'
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.post(
f"{base_url}/api/agents/packages",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"blueprint_ids": ["blp_01jc9n7k3xf8mbq2v5t0ary6de"],
"target": {"kind": "platform"},
"name": "Pump line 3",
"description": "Pump A monitor",
},
)
if response.status_code == 202:
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`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
blueprint_ids: ['blp_01jc9n7k3xf8mbq2v5t0ary6de'],
target: { kind: 'platform' },
name: 'Pump line 3',
description: 'Pump A monitor'
})
});
const body = await response.json();
if (response.status === 202) {
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": "<error_code>",
"message": "Invalid request, or a blueprint that cannot be resolved or could not run.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "capability_locked",
"message": "Blueprint not available to the caller's organization.",
"suggestion": "Contact [email protected] to unlock it.",
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "not_found",
"message": "A blueprint, or a model tag, model id or artifact one of its slots names, was not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "not_supported",
"message": "edge packages are not supported yet",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 2.0.0 or later of the Archetype platform.
Overview
This endpoint builds a package: an immutable build of a blueprint for a target, ready to run with Create Agent. When the package is built, every model slot of the blueprint is resolved the way running it would resolve them:- A model registry tag resolves to the model it names.
- An
mdl_model id resolves to that model. - An optimization’s fitted artifact, named in the slot by its
aar_id (as a promoted trial’s blueprint carries it), resolves to that artifact.
blueprints[].resolved_models shows what each slot resolved to. To change any of it, build a new
package.
The target says where the package will run. Whether it runs as a batch job or a serving agent is
chosen when you run it, not when you build it.
The endpoint returns 202 Accepted with the package. A build can take longer than the request,
so check its status. Use the package once it is ready. If it is still building, poll Get
Package until it is ready or failed.
Request
array
required
The blueprints to package, by
blp_ id. A blp_ id names one immutable blueprint version, so
the package holds exactly what you asked for. Must contain exactly one blueprint.object
required
Where the package is meant to run.
string
required
platform for the Archetype platform, or edge for a device outside it. Building for edge
returns 501: it is not available yet.string
Human label for the package, for example
Pump line 3. Lists show it, and every run of the
package is called by it. Trimmed, then up to 128 characters. Omit it, or leave it blank, to
name the package after its blueprint.string
Optional human description of what the package is for. Defaults to an empty string. Capped at
512 characters, as on bundles.
Response
Returns202 Accepted with the package.
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).
curl -X POST "$ATAI_API_URL/api/agents/packages" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"blueprint_ids": ["blp_01jc9n7k3xf8mbq2v5t0ary6de"],
"target": {"kind": "platform"},
"name": "Pump line 3",
"description": "Pump A monitor"
}'
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.post(
f"{base_url}/api/agents/packages",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"blueprint_ids": ["blp_01jc9n7k3xf8mbq2v5t0ary6de"],
"target": {"kind": "platform"},
"name": "Pump line 3",
"description": "Pump A monitor",
},
)
if response.status_code == 202:
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`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
blueprint_ids: ['blp_01jc9n7k3xf8mbq2v5t0ary6de'],
target: { kind: 'platform' },
name: 'Pump line 3',
description: 'Pump A monitor'
})
});
const body = await response.json();
if (response.status === 202) {
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": "<error_code>",
"message": "Invalid request, or a blueprint that cannot be resolved or could not run.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "capability_locked",
"message": "Blueprint not available to the caller's organization.",
"suggestion": "Contact [email protected] to unlock it.",
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "not_found",
"message": "A blueprint, or a model tag, model id or artifact one of its slots names, was not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "not_supported",
"message": "edge packages are not supported yet",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
- A
namelonger than 128 characters after trimming returns400. - A package holds exactly one blueprint for now. An empty
blueprint_ids, or one with more than one id, returns400. - A
400also covers a blueprint that cannot be resolved: a slot with no model yet, an invalid model reference, an archived tag, or a fine-tuned (promoted) model that is not a Newton-C LoRA fine-tune or sits in a slot whose node cannot apply it. It also covers a blueprint that could not run, such as one that requires values only an optimization fills in. - A
403with codecapability_lockedmeans the blueprint is not available to your organization. A403without that code means you can see the blueprint’s project but not modify it. - A
404covers a blueprint you cannot see or that was deleted during the build, and a slot that names a tag, model id or artifact that does not exist or is not visible to your organization. - A package of a blueprint in a project is in that project. Creating it requires being able to modify the project.
- Deleting a package never touches the blueprint it holds.
Was this page helpful?