Skip to main content
GET
Requires version 1.1.9 or later of the Archetype platform.

Overview

This endpoint returns one blueprint, addressed either by its immutable blp_ id, which targets that exact version, or by its key, which resolves to the key’s active version (org-owned or canonical, or in the project project_id names). Unlike the list endpoint, the response carries the full blueprint document, and optionally its YAML rendering.

Request

string
required
Blueprint blp_ id or key (e.g. osm).
boolean
Controls the yaml_document in the response. Omitted: include the stored YAML if one exists. true: always include, generating it from the document when none is stored. false: never include.
string
The prj_ id of the project to resolve a key in, as well as outside projects. Needed for a key registered in a project; ignored for a blp_ id. v2.0.0+

Response

string
required
TypeID-encoded blueprint identifier (blp_ prefix).
string
required
Human-readable key for the blueprint, e.g. osm.
string
required
Display name of the blueprint, from the document.
string
required
Description of the blueprint, from the document. Empty when the document has none.
object
required
The blueprint document, in the agent_core shape — the same format accepted on create, now carrying the assigned blueprint_id.
string
The YAML rendering of the blueprint, when included. Present when one was stored (or requested via ?yaml=true); omitted otherwise. See the yaml query parameter.
boolean
required
True for platform-authored (gallery) blueprints shared with every org; false for blueprints owned by a specific org.
boolean
required
True for the current version of a key; false once it has been replaced by a newer blueprint (its key was archived to <key>-<date>). Bundles/agents pinned to an inactive blueprint keep working — the console can badge them.
string
The project the blueprint lives in, or null if the blueprint is outside any project. v2.0.0+
object
Where this blueprint came from, when it was not authored directly. Omitted for an authored blueprint. It names the blueprint it was derived from, so the derived blueprint’s ancestry stays readable even after whatever produced it has been deleted. v1.1.12+
string
required
Creation timestamp (date-time).

Source object (source) v1.1.12+

string
required
How the blueprint was derived, which decides the other fields present. v1.1.13+
  • promotion: promoted from an optimization trial, as the blueprint the optimization searched with the trial’s overrides applied. Carries blueprint_id, values, models, and created_by.
  • copy: copied into a project from another blueprint with Copy Blueprint. Carries blueprint_id and blueprint_key. v2.0.0+
string
required
The blueprint this one was derived from. For a copy, the exact version that was copied.
string
For a copy, the original blueprint’s key when it was copied. v2.0.0+
object
For a promotion, the parameter value overrides applied on top of that blueprint’s own.
object
For a promotion, the model slot overrides applied on top of that blueprint’s own.
object
For a promotion, what produced this blueprint, as an id pair plus an optional label. The id prefix says what kind of thing it was: otr_ is an optimization trial, whose parent_id is then the optimization run it belonged to.
  • id (string, required) — the producer itself; an otr_ id for an optimization trial.
  • parent_id (string, required) — the run the producer belonged to; an opt_ id for an optimization trial.
  • name (string) — the human label of the enclosing run, when one was given to it.

Blueprint document fields

object
required
How the nodes are wired together, as {"edges": [...]}. Each edge connects a producing port to a consuming port: {"from": "<node id>.<output port>", "to": "<node id>.<input port>"}. edges is empty for a blueprint with a single node.
string
The assigned blueprint id, echoed inside the document.
object
Id-keyed map of source/sink nodes. Each entry is {"key": "<node key>", "config": {...}}, where key is a node key from the node registry and config is the node’s configuration ({} when the node takes no config).
object
Id-keyed map of every processing (non-connector) node, in the same entry shape as connectors.
string
Display name of the blueprint.
string
Description of what the blueprint does.
object
Default values for the knobs the blueprint exposes, as a JSON object. A bundle’s values override these at run time.
object
Model slots the blueprint exposes and their default registry tags, as a JSON object. A bundle’s models override these per slot.
object
Named external artifacts the blueprint expects, as {name: location} (string values). A bundle’s artifacts supply or override them.
object
Optional metrics catalog: what an eval may score this blueprint against, as the blueprint itself publishes it. A blueprint publishing none cannot be evaluated. v1.1.12+
  • primary (string, required) — the run’s headline, as <target>.<objective>, naming a declared target and one of its objectives. Also the objective an optimization maximizes by default.
  • targets (array) — the targets this blueprint can be scored on, each under its own name. An eval scores every one of them. A blueprint with several targets and a trainable node names the target the node learns in the node’s train_on setting.
  • constraints (array) — bounds the objectives must respect, each naming one of a target’s objectives as <target>.<objective>, with a min, a max, or both, inclusive. An eval reports whether each holds; an optimization never picks a trial known to miss one. A run may give its own in their place. See Constraint. v2.0.0+
Starting with version 2.0.0, a blueprint may declare several targets. Earlier versions supported exactly one.

Metrics target (document.metrics.targets[]) v1.1.12+

One thing the agent decides, and the unit an eval scores.
string
required
The target’s name. Identifies it in the metrics report, in an eval request’s targets overrides, and in each input’s own declarations — where it is also the default name of the column the labels are read from.
A target name may not contain a ., which separates a target from its objective where a headline is written <target>.<objective>.
string
required
The target’s type, which decides how a prediction is aligned to its ground truth:
  • category — exactly one of N mutually exclusive classes per scored unit.
  • binary — one of two classes per scored unit, one of which the target names positive.
array
required
Every objective an eval may compute for this target, each under its own name. Must be non-empty. One or more of macro_f1, accuracy, balanced_accuracy, foreground_macro_f1, detection_recall, and detection_precision, or the per-class precision, recall, and f1 written in full with the class they measure, such as {"name": "f1_bearing", "f1": {"class": "bearing"}}. The set is closed: an objective outside it is rejected when the blueprint is published or the eval is created. foreground_macro_f1, detection_recall, and detection_precision require the target to declare a background class. See Target override for the full form.
Starting with version 2.0.0, a target may declare the per-class precision, recall, and f1 objectives, and give any objective a name.
string
required
Where this target’s decision is in the agent’s output, as a <scheme>:<path> selector. The scheme is output: (the default, normally left off) or metadata:; for example, predicted_state names the predicted_state column of the output. Which forms a target accepts depends on its type.
array | string | null
required
The classes the target predicts; for a binary target, exactly two. A blueprint rarely knows them literally: they are typically written as a ${…} reference, such as ${values.states}, that is substituted only when the blueprint is resolved. null when substitution resolved the reference to nothing.
string
For a binary target (where it is required), which of the two labels is the positive class. A target whose positive is not one of its labels is rejected. v1.1.13+
string
For a category target, the class meaning that nothing happened, when there is one: what a scored unit is when none of the other classes occurs in it. Must be one of labels. Required by foreground_macro_f1, detection_recall, and detection_precision. v1.1.13+
string | object
How this target’s scored items are formed: what one scored thing is, and how a prediction is matched to the ground truth it is compared against. Required in practice: a target without one is rejected when the blueprint is validated. Two wire forms that mean the same thing — the bare name (pairing: by_time) when every parameter defaults, and a single-key map (pairing: {"by_time": {"downsampling": "majority_vote"}}) when one does not.by_time is the only pairing. Its downsampling parameter sets how the labels of the records making up one analysis window collapse to the single label that window is scored against: last_record or majority_vote. An input may override it.

Important Notes

  • reference accepts either a blp_ id or a blueprint key, so the same URL shape works for both. An id returns that exact version; a key returns its active version.
  • A 404 means the blueprint does not exist or is not visible to the caller’s organization. It is also returned for a blueprint in a project you cannot see, and when project_id names a project that does not exist or that you cannot see. v2.0.0+
  • A key registered in a project resolves only when project_id names that project. v2.0.0+
  • Ask for ?yaml=true when you want YAML even for a blueprint that was created from JSON — the service renders it from the document.
  • A blueprint with is_active: false has been replaced by a newer version of its key; it remains readable by id.
  • List every version of a key with GET /agents/blueprints/{reference}/versions. v1.1.12+
  • source is present only on a derived blueprint — one promoted from an optimization trial, for example — and records the blueprint that was searched together with the overrides applied to it. v1.1.12+
  • A blueprint without a metrics catalog in its document cannot be evaluated or optimized. v1.1.12+