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 instead. To move existing code, see Migrating from Bundles and Instances.

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. The blueprint must be visible to the caller’s organization. Its reference is resolved once and pinned by ID, so a later replacement of the key does not change what this bundle runs. The bundle is returned in ready status.

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. Capped at 512 characters, mirroring the console’s client-side cap. v1.1.12+
object
User value overrides, layered over the blueprint defaults at run time. Must be a JSON object; defaults to {}.
object
Per-slot model overrides: slot name to registry tag. Must be a flat JSON object of strings; omitting it or sending null defaults to {}, which uses the blueprint’s default model for every slot.
Starting with version 2.0.0, a slot can also be set to an mdl_ model ID, which pins one exact model from the model registry, including a fine-tuned Newton-C model.
object
Optional links to the external files the blueprint expects, e.g. {"calibration": "s3://.../knn_index"}. Must be a JSON object.
Starting with version 2.0.0, every value must be a location string; any other value (for example, an object) is rejected with HTTP status code 400. To use a fine-tuned model, reference it by its mdl_ model ID in models instead.

Response

Returns the created bundle.
string
required
TypeID-encoded bundle identifier (bnd_ prefix).
string
required
Human label given on create, e.g. Pump A monitor. Also the name of every run of this bundle.
string
required
Human description given on create. Empty when none was given.
string
required
The pinned blueprint’s immutable blp_ id. Resolve its key via the blueprint registry when needed.
object
required
User value overrides, layered over the blueprint’s defaults at run time. {} when the bundle overrides nothing.
string
required
Whether the bundle can be run: 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.
object
required
Per-slot model overrides: slot name to registry tag or mdl_ model ID. If this object is empty, the bundle uses the blueprint’s default for every slot.
object
Artifact links the blueprint expects, as {name: location}. Absent when none were given.
array
The bundle’s five most recent runs, newest first. Present only when a read asked for it via include_latest_runs=true, so it is absent from this endpoint’s response. An empty array means the bundle has never been run.

Important Notes

  • The pin is immutable: a later version of the key does not change what this bundle runs.
  • Parameters and models live on the bundle, not on the run request — a run supplies only connectors.
  • A 400 means name is blank, description exceeds 512 characters, or models, values, or artifacts is not a JSON object.
  • A 400 also means an artifacts value is not a location string, a models value starting with aar_ or mdl_ is not a valid artifact or model ID, or a canonical bundle names a model by ID. Canonical bundles use registry tags. v2.0.0+
  • A 403 with code capability_locked means the blueprint is not available to the caller’s organization; a 404 means the blueprint does not exist or is not visible to it.