Agents API
Run Bundle
Start a run of a bundle by binding its inputs and outputs
POST
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: all output goes to this single file. Passed to the runner as the
output_ref job-config key.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 canceled.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.Important Notes
- Parameters and model come from the bundle, not the run request — the body carries only connectors.
- Omit
sinkto get one output per input, named after the input; provide it to funnel all output into a single file. - 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.