Skip to main content
POST
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 in running 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

string
required
Bundle bnd_ id to run.
string
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+
object
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.
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; 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

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.
string
Optional whole-file CRC32C checksum of the referenced bytes, base64-encoded exactly as S3 emits it. v1.1.13+
object
Free-form detail about this ref. Any key is carried through untouched. v1.1.13+

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
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+
string
required
Creation timestamp (date-time).
object
The I/O binding this run was started with. Absent only on runs recorded before I/O bindings were stored.
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 execution mode.
  • A batch run must bind at least one file ref in connectors.source; an empty, omitted, or file-less source returns 400.
  • A serving run must send no connectors at all. Sending any returns 400, as does a blueprint that cannot be served or that sets a setting the platform owns; none of these creates an agent.
  • A serving run is placed on a worker before it is accepted. A 503 means 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 returns 400. Either way the agent is left failed, and running the bundle again is what retries it.
  • A 501 means mode: serving was requested in an environment where serving is not enabled.
  • 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+
  • A 409 means the sink names an output that already exists; choose another name.
  • A 403 with code capability_locked means the bundle’s blueprint is not available to the caller’s organization.
  • A 404 covers 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 returns 404, the same as an unknown ID. v2.0.0+
  • A fine-tuned Newton-C LoRA model (such as variant newton-c-2.5-8b-lora or newton-c-2.5-2b-lora) can fill a model slot by its mdl_ ID or a tag. The platform merges the fine-tuned adapter into the base model when the agent loads it. A 400 means 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 /events and /logs pages, and /results for outputs.