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 or by its key. 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.

Response

string
required
TypeID-encoded blueprint identifier (blp_ prefix).
string
required
Human-readable key for the blueprint, e.g. osm.
string
required
Name of the blueprint.
string
required
Description of the blueprint.
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.
object
Where this blueprint came from, when it was not authored directly. Omitted for an authored blueprint. It names the blueprint that was customized and the exact overrides applied to it, 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
The blueprint this one was derived from.
object
required
Parameter value overrides applied on top of that blueprint’s own.
object
required
Model slot overrides applied on top of that blueprint’s own.
object
Artifact locations applied on top of that blueprint’s own, keyed by artifact name.
object
required
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
The blueprint’s edges: {"edges": [{"from": "<node id>", "to": "<node id>"}]}.
string
The assigned blueprint id, echoed inside the document.
object
Id-keyed map of source/sink nodes. Each entry is {"key": "<node key>", "config": {...}}.
object
Id-keyed map of every non-connector node, in the same entry shape as connectors.
string
The blueprint’s own name.
string
The blueprint’s own description.
object
The blueprint’s default values.
object
The blueprint’s models.
object
Map of artifact name to artifact reference (string values).
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. Exactly one is supported today.

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.
string
required
The target’s type. category — exactly one of N mutually exclusive classes per scored unit.
array
required
Every objective an eval may compute for this target: macro_f1, accuracy. Must be non-empty.
string
required
Where this target’s decision is in the agent’s output — the named output column that holds it.
array
For a category target, the classes it predicts. A blueprint rarely knows them literally: they can be written as a ${…} reference that is substituted only when the blueprint is resolved.
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. Two wire forms — 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.

Important Notes

  • reference accepts either a blp_ id or a blueprint key, so the same URL shape works for both.
  • 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+