Skip to main content
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: 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

Returns 202 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.

Important Notes

  • Parameters and model come from the bundle, not the run request — the body carries only connectors and the optional mode.
  • Omit sink to 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+
  • mode is recorded on the agent, so a run stays batch or serving for its whole life. Only a serving run answers /query and /connect. v1.1.12+
  • A 404 covers 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 /events and /logs pages, and /results for outputs.