Agents API
Create Bundle
Create a deployable bundle that pins a blueprint
POST
Requires version 1.1.9 or later of the Archetype platform.
Overview
This endpoint creates a bundle: a named, deployable customization of a blueprint. The bundle pins one blueprint by ID or key and carries the parameters a run will use —values,
an optional model override, and optional artifacts. Runs bind only their I/O, via POST /agents/bundles/{bundle_id}/run.
Request
string
required
Blueprint reference to pin: a
blp_ ID or key (e.g. osm).While
blueprint accepts either a blp_ ID or a key, the response records the resolved
immutable blueprint_id.string
required
Human label for this bundle, e.g.
Pump A monitor.string
Optional human description of this bundle. Defaults to an empty string.
object
User value overrides, layered over the blueprint defaults at run time. Must be a JSON object; defaults to
{}.string
Optional model override; omit to use the blueprint’s default.
object
Optional artifact links, e.g.
{"calibration": "s3://.../knn_index"}.boolean
default:"false"
Publish as a canonical (platform-wide) bundle, visible to every org. Requires the super-admin
role; defaults to an org-owned bundle.
Response
Returns the created bundle.string
required
TypeID-encoded bundle identifier (
bnd_ prefix).string
required
Human label for the bundle.
string
required
Human description of the bundle.
string
required
The pinned blueprint’s immutable
blp_ id. Resolve its key via the blueprint registry when needed.object
required
The value overrides stored on the bundle.
string
required
Build lifecycle of the bundle:
building, ready, or failed.boolean
required
True for a canonical (platform-authored) bundle, visible to every org.
string
required
Creation timestamp (date-time).
string
Owning organization; omitted for a canonical bundle.
string
Model override; omitted when the bundle uses the blueprint’s default.
object
Artifact links attached to the bundle.
array
The bundle’s five most recent runs, newest first. Present only when a read asked for it via
include_latest_runs=true.Important Notes
- The pin is immutable: a later version of the key does not change what this bundle runs.
- Parameters and model live on the bundle, not on the run request — a run supplies only connectors.
canonical: truerequires the super-admin role.