curl "$ATAI_API_URL/agents/blueprints/osm" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/blueprints/blp_01jc9n7k3xf8mbq2v5t0ary6de?yaml=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.get(
f"{base_url}/agents/blueprints/osm",
headers={"Authorization": f"Bearer {api_key}"},
params={"yaml": "true"},
)
if response.status_code == 200:
blueprint = response.json()
print(f"{blueprint['name']} ({blueprint['id']}), active={blueprint['is_active']}")
print(blueprint.get("yaml_document"))
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/blueprints/osm?yaml=true`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
console.log(`${body.name} (${body.id}), active=${body.is_active}`);
console.log(body.yaml_document);
} else {
console.error('Error:', body.errors);
}
{
"id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"blueprint_key": "osm",
"name": "Open-set monitor",
"description": "Classifies incoming records against a known class vocabulary.",
"document": {
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"name": "Open-set monitor",
"description": "Classifies incoming records against a known class vocabulary.",
"connectors": {
"input": {"key": "<node_key>", "config": {}},
"output": {"key": "<node_key>", "config": {}}
},
"nodes": {
"classifier": {"key": "<node_key>", "config": {}}
},
"graph": {
"edges": [
{"from": "input", "to": "classifier"},
{"from": "classifier", "to": "output"}
]
},
"values": {},
"artifacts": {},
"metrics": {
"primary": "state.macro_f1",
"targets": [
{
"name": "state",
"type": "category",
"labels": "${models.classifier.parameters.states}",
"objectives": ["macro_f1", "accuracy"],
"predicted": "predicted_state",
"pairing": "by_time"
}
]
}
},
"yaml_document": "name: Open-set monitor\ngraph:\n edges: []\n",
"is_canonical": true,
"is_active": true,
"created_at": "2026-08-11T14:32:07Z"
}
{
"id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
"blueprint_key": "osm-otr-01jcb2v9h4x7mq3nt8k5rdzy6w",
"name": "Open-set monitor",
"description": "Classifies incoming records against a known class vocabulary.",
"document": {
"blueprint_id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
"name": "Open-set monitor",
"graph": {"edges": []},
"values": {"window_size": 512},
"artifacts": {"fit-classifier": "s3://.../fit-classifier"}
},
"yaml_document": null,
"is_canonical": false,
"is_active": true,
"source": {
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"values": {"window_size": 512},
"models": {},
"artifacts": {"fit-classifier": "s3://.../fit-classifier"},
"created_by": {
"id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
"parent_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"name": "Window size sweep"
}
},
"created_at": "2026-09-18T11:24:03Z"
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid reference.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Blueprint not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Blueprints
Get Blueprint
Retrieve a single blueprint, including its full document
GET
/
agents
/
blueprints
/
{reference}
curl "$ATAI_API_URL/agents/blueprints/osm" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/blueprints/blp_01jc9n7k3xf8mbq2v5t0ary6de?yaml=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.get(
f"{base_url}/agents/blueprints/osm",
headers={"Authorization": f"Bearer {api_key}"},
params={"yaml": "true"},
)
if response.status_code == 200:
blueprint = response.json()
print(f"{blueprint['name']} ({blueprint['id']}), active={blueprint['is_active']}")
print(blueprint.get("yaml_document"))
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/blueprints/osm?yaml=true`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
console.log(`${body.name} (${body.id}), active=${body.is_active}`);
console.log(body.yaml_document);
} else {
console.error('Error:', body.errors);
}
{
"id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"blueprint_key": "osm",
"name": "Open-set monitor",
"description": "Classifies incoming records against a known class vocabulary.",
"document": {
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"name": "Open-set monitor",
"description": "Classifies incoming records against a known class vocabulary.",
"connectors": {
"input": {"key": "<node_key>", "config": {}},
"output": {"key": "<node_key>", "config": {}}
},
"nodes": {
"classifier": {"key": "<node_key>", "config": {}}
},
"graph": {
"edges": [
{"from": "input", "to": "classifier"},
{"from": "classifier", "to": "output"}
]
},
"values": {},
"artifacts": {},
"metrics": {
"primary": "state.macro_f1",
"targets": [
{
"name": "state",
"type": "category",
"labels": "${models.classifier.parameters.states}",
"objectives": ["macro_f1", "accuracy"],
"predicted": "predicted_state",
"pairing": "by_time"
}
]
}
},
"yaml_document": "name: Open-set monitor\ngraph:\n edges: []\n",
"is_canonical": true,
"is_active": true,
"created_at": "2026-08-11T14:32:07Z"
}
{
"id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
"blueprint_key": "osm-otr-01jcb2v9h4x7mq3nt8k5rdzy6w",
"name": "Open-set monitor",
"description": "Classifies incoming records against a known class vocabulary.",
"document": {
"blueprint_id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
"name": "Open-set monitor",
"graph": {"edges": []},
"values": {"window_size": 512},
"artifacts": {"fit-classifier": "s3://.../fit-classifier"}
},
"yaml_document": null,
"is_canonical": false,
"is_active": true,
"source": {
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"values": {"window_size": 512},
"models": {},
"artifacts": {"fit-classifier": "s3://.../fit-classifier"},
"created_by": {
"id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
"parent_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"name": "Window size sweep"
}
},
"created_at": "2026-09-18T11:24:03Z"
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid reference.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Blueprint not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 1.1.9 or later of the Archetype platform.
Overview
This endpoint returns one blueprint, addressed either by its immutableblp_ 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; anotr_id for an optimization trial.parent_id(string, required) — the run the producer belonged to; anopt_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.curl "$ATAI_API_URL/agents/blueprints/osm" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_URL/agents/blueprints/blp_01jc9n7k3xf8mbq2v5t0ary6de?yaml=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.get(
f"{base_url}/agents/blueprints/osm",
headers={"Authorization": f"Bearer {api_key}"},
params={"yaml": "true"},
)
if response.status_code == 200:
blueprint = response.json()
print(f"{blueprint['name']} ({blueprint['id']}), active={blueprint['is_active']}")
print(blueprint.get("yaml_document"))
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/blueprints/osm?yaml=true`,
{
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
}
}
);
const body = await response.json();
if (response.ok) {
console.log(`${body.name} (${body.id}), active=${body.is_active}`);
console.log(body.yaml_document);
} else {
console.error('Error:', body.errors);
}
{
"id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"blueprint_key": "osm",
"name": "Open-set monitor",
"description": "Classifies incoming records against a known class vocabulary.",
"document": {
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"name": "Open-set monitor",
"description": "Classifies incoming records against a known class vocabulary.",
"connectors": {
"input": {"key": "<node_key>", "config": {}},
"output": {"key": "<node_key>", "config": {}}
},
"nodes": {
"classifier": {"key": "<node_key>", "config": {}}
},
"graph": {
"edges": [
{"from": "input", "to": "classifier"},
{"from": "classifier", "to": "output"}
]
},
"values": {},
"artifacts": {},
"metrics": {
"primary": "state.macro_f1",
"targets": [
{
"name": "state",
"type": "category",
"labels": "${models.classifier.parameters.states}",
"objectives": ["macro_f1", "accuracy"],
"predicted": "predicted_state",
"pairing": "by_time"
}
]
}
},
"yaml_document": "name: Open-set monitor\ngraph:\n edges: []\n",
"is_canonical": true,
"is_active": true,
"created_at": "2026-08-11T14:32:07Z"
}
{
"id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
"blueprint_key": "osm-otr-01jcb2v9h4x7mq3nt8k5rdzy6w",
"name": "Open-set monitor",
"description": "Classifies incoming records against a known class vocabulary.",
"document": {
"blueprint_id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
"name": "Open-set monitor",
"graph": {"edges": []},
"values": {"window_size": 512},
"artifacts": {"fit-classifier": "s3://.../fit-classifier"}
},
"yaml_document": null,
"is_canonical": false,
"is_active": true,
"source": {
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"values": {"window_size": 512},
"models": {},
"artifacts": {"fit-classifier": "s3://.../fit-classifier"},
"created_by": {
"id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
"parent_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"name": "Window size sweep"
}
},
"created_at": "2026-09-18T11:24:03Z"
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid reference.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Blueprint not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
referenceaccepts either ablp_id or a blueprint key, so the same URL shape works for both.- Ask for
?yaml=truewhen you want YAML even for a blueprint that was created from JSON — the service renders it from the document. - A blueprint with
is_active: falsehas 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+ sourceis 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
metricscatalog in its document cannot be evaluated or optimized. v1.1.12+
Was this page helpful?