curl -X POST "$ATAI_API_ENDPOINT/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_ENDPOINT/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"}
}
}'
curl -X POST "$ATAI_API_ENDPOINT/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"mode": "serving"}'
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
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_ENDPOINT}/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",
"mode": "batch",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": null,
"completed_at": null,
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid request: a batch run with no source file, a serving run that sent connectors or whose blueprint cannot be served, or a serving run a worker refused.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "capability_locked",
"message": "Blueprint not available to the caller's organization.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"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": "The requested `sink` output name already exists.",
"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"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "A serving run could not be placed: no worker was free, the pool could not be reached, or a worker could not start the agent.",
"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_ENDPOINT/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_ENDPOINT/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"}
}
}'
curl -X POST "$ATAI_API_ENDPOINT/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"mode": "serving"}'
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
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_ENDPOINT}/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",
"mode": "batch",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": null,
"completed_at": null,
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid request: a batch run with no source file, a serving run that sent connectors or whose blueprint cannot be served, or a serving run a worker refused.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "capability_locked",
"message": "Blueprint not available to the caller's organization.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"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": "The requested `sink` output name already exists.",
"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"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "A serving run could not be placed: no worker was free, the pool could not be reached, or a worker could not start the agent.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 1.1.9 or later of the Archetype platform.
Starting with version 2.0.1, this endpoint is removed from the platform. Build a package with Create Package, deploy it with Create Deployment, then open a session on it with Create Session. To move existing code, see Migrating from Bundles and Instances.
Overview
This endpoint starts a run of a bundle and returns the created agent, already inrunning
status. The run is owned by the caller: other members of the organization cannot see it unless
they are org admins.
The request supplies only the run’s I/O binding and its execution mode — parameters and model come from the bundle. Each run is a separate agent: to re-run, call this endpoint again.
mode picks how the agent executes. A batch run (the default) processes its input files and
finishes. A serving run stays up to answer queries over Query
Agent and Connect to
Agent; since its input and output are those
endpoints, it takes no connectors. A serving run is placed on a worker before it is accepted.
Request
How the agent executes:
batch (default) processes the inputs and finishes; serving stays
up to answer queries. Persisted on the agent, so a run’s mode outlives the request that created
it. v1.1.13+Source/sink connectors binding this run’s I/O. Bound at run time — I/O stays external to the
agent (“build once, run anywhere”). A
batch run reads its input from these files, so it must
list at least one file ref in source; omitting the field, or sending a source with no
file ref, returns 400. A serving run takes its input from the query it is answering, so
it must omit connectors entirely — binding files to one is refused with 400 rather than
accepted and ignored.One or more input refs; multiple files are staged on the same JOS input port. Each entry is a data ref.
Optional output ref; omit it or send
null for the default. It must not name an output that
already exists. 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
Optional whole-file CRC32C checksum of the referenced bytes, base64-encoded exactly as S3 emits
it. v1.1.13+
Free-form detail about this ref. Any key is carried through untouched. v1.1.13+
Response
Returns202 Accepted with the created agent.
How the agent executes:
batch, a run that finishes on its own, or serving, an agent that
stays up to answer queries. v1.1.13+The I/O binding this run was started with. Absent only on runs recorded before I/O bindings
were stored.
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.curl -X POST "$ATAI_API_ENDPOINT/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_ENDPOINT/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"}
}
}'
curl -X POST "$ATAI_API_ENDPOINT/agents/bundles/bnd_01jc9pd42kzq7v8n3h5m6rtx0w/run" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"mode": "serving"}'
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
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_ENDPOINT}/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",
"mode": "batch",
"job_id": "job_01jc9q9k4t8v2mnr5xh7bdzy3s",
"created_at": "2026-08-11T15:10:00Z",
"started_at": null,
"completed_at": null,
"error": null
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid request: a batch run with no source file, a serving run that sent connectors or whose blueprint cannot be served, or a serving run a worker refused.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "capability_locked",
"message": "Blueprint not available to the caller's organization.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"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": "The requested `sink` output name already exists.",
"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"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "A serving run could not be placed: no worker was free, the pool could not be reached, or a worker could not start the agent.",
"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 execution mode.
- A
batchrun must bind at least onefileref inconnectors.source; an empty, omitted, or file-lesssourcereturns400. - A
servingrun must send noconnectorsat all. Sending any returns400, as does a blueprint that cannot be served or that sets a setting the platform owns; none of these creates an agent. - A
servingrun is placed on a worker before it is accepted. A503means the pool had nothing free, could not be reached, or took the agent and could not start it (the last of those quotes the worker’s own reason); a worker refusing the blueprint returns400. Either way the agent is leftfailed, and running the bundle again is what retries it. - A
501meansmode: servingwas requested in an environment where serving is not enabled. - 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+ - A
409means thesinknames an output that already exists; choose another name. - A
403with codecapability_lockedmeans the bundle’s blueprint is not available to the caller’s organization. - A
404covers both an unknown bundle and a model slot whose tag is not in the registry. v1.1.12+ - A model slot set to an
mdl_model ID resolves to a model in the caller’s organization or a platform model, and keeps resolving after the model’s tags are archived. An ID belonging to another organization returns404, the same as an unknown ID. v2.0.0+ - A fine-tuned Newton-C LoRA model (such as variant
newton-c-2.5-8b-loraornewton-c-2.5-2b-lora) can fill a model slot by itsmdl_ID or a tag. The platform merges the fine-tuned adapter into the base model when the agent loads it. A400means the slot names a fine-tuned model of any other variant, or a node other than Newton-C reads the slot. v2.0.0+ - 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?