curl -X POST "$ATAI_API_URL/agents/bundles" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"blueprint": "osm",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"values": {},
"artifacts": {
"calibration": "s3://.../knn_index"
}
}'
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.post(
f"{base_url}/agents/bundles",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"blueprint": "osm",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"values": {},
"artifacts": {"calibration": "s3://.../knn_index"},
},
)
if response.status_code == 201:
bundle = response.json()
print(f"Created bundle {bundle['id']} pinning {bundle['blueprint_id']}")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(`${process.env.ATAI_API_URL}/agents/bundles`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
blueprint: 'osm',
name: 'Pump A monitor',
description: 'Open-set monitor tuned for pump A telemetry.',
values: {},
artifacts: { calibration: 's3://.../knn_index' }
})
});
const body = await response.json();
if (response.status === 201) {
console.log(`Created bundle ${body.id} pinning ${body.blueprint_id}`);
} else {
console.error('Error:', body.errors);
}
{
"id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"models": {},
"values": {},
"artifacts": {
"calibration": "s3://.../knn_index"
},
"status": "ready",
"is_canonical": false,
"created_at": "2026-08-11T15:02:19Z"
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid request.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Super-admin required for canonical bundles.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Blueprint not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Agents API
Create Bundle
Create a deployable bundle that pins a blueprint
POST
/
agents
/
bundles
curl -X POST "$ATAI_API_URL/agents/bundles" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"blueprint": "osm",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"values": {},
"artifacts": {
"calibration": "s3://.../knn_index"
}
}'
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.post(
f"{base_url}/agents/bundles",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"blueprint": "osm",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"values": {},
"artifacts": {"calibration": "s3://.../knn_index"},
},
)
if response.status_code == 201:
bundle = response.json()
print(f"Created bundle {bundle['id']} pinning {bundle['blueprint_id']}")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(`${process.env.ATAI_API_URL}/agents/bundles`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
blueprint: 'osm',
name: 'Pump A monitor',
description: 'Open-set monitor tuned for pump A telemetry.',
values: {},
artifacts: { calibration: 's3://.../knn_index' }
})
});
const body = await response.json();
if (response.status === 201) {
console.log(`Created bundle ${body.id} pinning ${body.blueprint_id}`);
} else {
console.error('Error:', body.errors);
}
{
"id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"models": {},
"values": {},
"artifacts": {
"calibration": "s3://.../knn_index"
},
"status": "ready",
"is_canonical": false,
"created_at": "2026-08-11T15:02:19Z"
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid request.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Super-admin required for canonical bundles.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Blueprint not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 1.1.9 or later of the Archetype platform.
Overview
This endpoint creates a bundle: a named, deployable customization of a blueprint. The bundle pins one blueprint by ID or key and carries the parameters a run will use —values,
an optional model override, and optional artifacts. Runs bind only their I/O, via POST /agents/bundles/{bundle_id}/run.
Request
string
required
Blueprint reference to pin: a
blp_ ID or key (e.g. osm).While
blueprint accepts either a blp_ ID or a key, the response records the resolved
immutable blueprint_id.string
required
Human label for this bundle, e.g.
Pump A monitor.string
Optional human description of this bundle. Defaults to an empty string.
object
User value overrides, layered over the blueprint defaults at run time. Must be a JSON object; defaults to
{}.object
Per-slot model overrides: slot name to registry tag. Must be a flat JSON object of strings;
defaults to
{}, which uses the blueprint’s default model for every slot.object
Optional artifact links, e.g.
{"calibration": "s3://.../knn_index"}.boolean
default:"false"
Publish as a canonical (platform-wide) bundle, visible to every org. Requires the super-admin
role; defaults to an org-owned bundle.
Response
Returns the created bundle.string
required
TypeID-encoded bundle identifier (
bnd_ prefix).string
required
Human label for the bundle.
string
required
Human description of the bundle.
string
required
The pinned blueprint’s immutable
blp_ id. Resolve its key via the blueprint registry when needed.object
required
The value overrides stored on the bundle.
string
required
Build lifecycle of the bundle:
building, ready, or failed.boolean
required
True for a canonical (platform-authored) bundle, visible to every org.
string
required
Creation timestamp (date-time).
string
Owning organization; omitted for a canonical bundle.
string
Per-slot model overrides: slot name to registry tag. If this object is empty, the bundle uses
the blueprint’s default for every slot.
object
Artifact links attached to the bundle.
array
The bundle’s five most recent runs, newest first. Present only when a read asked for it via
include_latest_runs=true.curl -X POST "$ATAI_API_URL/agents/bundles" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"blueprint": "osm",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"values": {},
"artifacts": {
"calibration": "s3://.../knn_index"
}
}'
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.post(
f"{base_url}/agents/bundles",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"blueprint": "osm",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"values": {},
"artifacts": {"calibration": "s3://.../knn_index"},
},
)
if response.status_code == 201:
bundle = response.json()
print(f"Created bundle {bundle['id']} pinning {bundle['blueprint_id']}")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(`${process.env.ATAI_API_URL}/agents/bundles`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
blueprint: 'osm',
name: 'Pump A monitor',
description: 'Open-set monitor tuned for pump A telemetry.',
values: {},
artifacts: { calibration: 's3://.../knn_index' }
})
});
const body = await response.json();
if (response.status === 201) {
console.log(`Created bundle ${body.id} pinning ${body.blueprint_id}`);
} else {
console.error('Error:', body.errors);
}
{
"id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"name": "Pump A monitor",
"description": "Open-set monitor tuned for pump A telemetry.",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"models": {},
"values": {},
"artifacts": {
"calibration": "s3://.../knn_index"
},
"status": "ready",
"is_canonical": false,
"created_at": "2026-08-11T15:02:19Z"
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid request.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Super-admin required for canonical bundles.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Blueprint not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
- The pin is immutable: a later version of the key does not change what this bundle runs.
- Parameters and model live on the bundle, not on the run request — a run supplies only connectors.
canonical: truerequires the super-admin role.
Was this page helpful?