curl -X POST "$ATAI_API_URL/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectors": {
"source": [
{"type": "file", "id": "file_abc123", "format": "csv"}
]
}
}'
curl -X POST "$ATAI_API_URL/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectors": {
"source": [
{"type": "file", "id": "file_abc123", "format": "csv"},
{"type": "file", "id": "file_def456", "format": "csv"}
],
"sink": {"type": "file", "id": "file_ghi789"}
}
}'
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/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"connectors": {
"source": [{"type": "file", "id": "file_abc123", "format": "csv"}],
}
},
)
if response.status_code == 202:
agent = response.json()
print(f"Run accepted: {agent['id']} (status {agent['status']})")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
connectors: {
source: [{ type: 'file', id: 'file_abc123', format: 'csv' }]
}
})
}
);
const body = await response.json();
if (response.status === 202) {
console.log(`Run accepted: ${body.id} (status ${body.status})`);
} else {
console.error('Error:', body.errors);
}
{
"id": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f",
"name": "Pump A monitor",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"bundle_id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"blueprint": "osm",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"connectors": {
"source": [
{"type": "file", "id": "file_abc123", "format": "csv"}
],
"sink": null
},
"status": "running",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": null,
"completed_at": null,
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Bundle not found, or a model slot's tag not found in the registry.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "`mode: serving` requested where serving is not enabled.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Bundles
Run Bundle
Start a run of a bundle by binding its inputs and outputs
POST
/
agents
/
bundles
/
{bundle_id}
/
run
curl -X POST "$ATAI_API_URL/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectors": {
"source": [
{"type": "file", "id": "file_abc123", "format": "csv"}
]
}
}'
curl -X POST "$ATAI_API_URL/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectors": {
"source": [
{"type": "file", "id": "file_abc123", "format": "csv"},
{"type": "file", "id": "file_def456", "format": "csv"}
],
"sink": {"type": "file", "id": "file_ghi789"}
}
}'
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/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"connectors": {
"source": [{"type": "file", "id": "file_abc123", "format": "csv"}],
}
},
)
if response.status_code == 202:
agent = response.json()
print(f"Run accepted: {agent['id']} (status {agent['status']})")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
connectors: {
source: [{ type: 'file', id: 'file_abc123', format: 'csv' }]
}
})
}
);
const body = await response.json();
if (response.status === 202) {
console.log(`Run accepted: ${body.id} (status ${body.status})`);
} else {
console.error('Error:', body.errors);
}
{
"id": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f",
"name": "Pump A monitor",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"bundle_id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"blueprint": "osm",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"connectors": {
"source": [
{"type": "file", "id": "file_abc123", "format": "csv"}
],
"sink": null
},
"status": "running",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": null,
"completed_at": null,
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Bundle not found, or a model slot's tag not found in the registry.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "`mode: serving` requested where serving is not enabled.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 1.1.9 or later of the Archetype platform.
Overview
This endpoint starts a run of a bundle and returns the created agent. The request supplies only the run’s I/O binding — parameters and model come from the bundle. Each run is a separate agent: to re-run, call this endpoint again.Request
string
required
Bundle
bnd_ id to run.object
required
Source/sink connectors binding this run’s I/O. Bound at run time — I/O stays external to the agent (“build once, run anywhere”).
array
required
One or more input refs; multiple files are staged on the same JOS input port. Each entry is a data ref.
object
Optional output ref. Omitted (the default): the runner writes one output per input, named after
the input. Provided: for concatenable formats (e.g. CSV) all output folds into this single file;
for standalone-document sinks (
json/per-request) it namespaces each per-request artifact
instead of concatenating them. Passed to the runner as the output_ref job-config key. v1.1.12+Data ref
string
required
Storage kind, e.g.
file or dataset.string
required
Identifier within that storage kind, e.g.
file_abc123.string
Optional format hint, e.g.
csv.Response
Returns202 Accepted with the created agent.
string
required
TypeID-encoded agent identifier (
agt_ prefix).string
required
Name of the agent (a run’s name is its bundle’s name).
string
required
Organization identifier the agent belongs to.
string
required
The bundle this agent was run from (provenance).
string
required
Human-readable pinned blueprint reference (its key), e.g.
osm.string
required
Immutable blueprint id the bundle pinned.
string
required
Agent lifecycle status:
running, paused, completed, failed, or cancelled.string
required
Creation timestamp (date-time).
object
The I/O binding this run was started with;
null when none is recorded.string
External executor’s job id for the current run (a JOS
job_ id). Present once the run has been dispatched; lets clients query JOS for run progress.string
When the run started;
null before then.string
When the run finished;
null while unfinished.string
Failure detail;
null unless the run failed.curl -X POST "$ATAI_API_URL/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectors": {
"source": [
{"type": "file", "id": "file_abc123", "format": "csv"}
]
}
}'
curl -X POST "$ATAI_API_URL/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectors": {
"source": [
{"type": "file", "id": "file_abc123", "format": "csv"},
{"type": "file", "id": "file_def456", "format": "csv"}
],
"sink": {"type": "file", "id": "file_ghi789"}
}
}'
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/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"connectors": {
"source": [{"type": "file", "id": "file_abc123", "format": "csv"}],
}
},
)
if response.status_code == 202:
agent = response.json()
print(f"Run accepted: {agent['id']} (status {agent['status']})")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
connectors: {
source: [{ type: 'file', id: 'file_abc123', format: 'csv' }]
}
})
}
);
const body = await response.json();
if (response.status === 202) {
console.log(`Run accepted: ${body.id} (status ${body.status})`);
} else {
console.error('Error:', body.errors);
}
{
"id": "agt_01jc9q8v5nm3ry7t2bkz4dhs6f",
"name": "Pump A monitor",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"bundle_id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
"blueprint": "osm",
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"connectors": {
"source": [
{"type": "file", "id": "file_abc123", "format": "csv"}
],
"sink": null
},
"status": "running",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": null,
"completed_at": null,
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Bundle not found, or a model slot's tag not found in the registry.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "`mode: serving` requested where serving is not enabled.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
- Parameters and model come from the bundle, not the run request — the body carries only connectors and the optional
mode. - Omit
sinkto get one output per input, named after the input; provide it to fold concatenable output into a single file, or to namespace each per-request artifact for a standalone-document sink. v1.1.12+ modeis recorded on the agent, so a run staysbatchorservingfor its whole life. Only aservingrun answers/queryand/connect. v1.1.12+- A
404covers both an unknown bundle and a model slot whose tag is not in the registry. v1.1.12+ - Each run is a new agent. To re-run, call this endpoint again rather than restarting an existing agent.
- Track progress with
GET /agents/instances/{agent_id}, its/eventsand/logspages, and/resultsfor outputs.
Was this page helpful?