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

Overview

This endpoint registers a blueprint under a human-readable key and returns the stored blueprint with its assigned blp_ ID. Supply the blueprint as a JSON document, as a yaml_document, or as both. The document is validated against the node registry, and the blueprint is registered under the caller’s organization. Set replacement_of to re-point an existing key at a new version; the previous blueprint is archived and flagged inactive, and bundles and agents pinned to it keep resolving it by ID.

Request

string
required
Human-readable blueprint key as shown in the table below. The reference users put in agent configurations. A service-level catalog key (not part of the agent_core blueprint).
object
The blueprint document, in the agent_core shape. It carries the blueprint’s own name/description and its values/models/artifacts, the connectors/nodes id-keyed node maps, and a graph of edges. The service assigns the blueprint’s ID when it stores it, so the document must not carry a blueprint_id; one that does is rejected with HTTP status code 400.
Optional: Provide this parameter, yaml_document, or both; omit it or send null to leave it out. When only yaml_document is given, the document is parsed from it. When both are given, they must describe the same blueprint.
string
A YAML rendering of the blueprint (the same shape as document). Stored verbatim so authored comments/formatting are preserved and returned by the get endpoint.
Optional: Provide this parameter, document, or both; omit it or send null to leave it out. When only this is provided, document is parsed from it; when both this parameter and document are provided, they must describe the same blueprint.
string
Replacement mode: the blp_ id of the blueprint currently holding blueprint_key, which this request re-points to a new version. The previous blueprint is archived under <blueprint_key>-<its creation date> and flagged inactive; existing bundles/agents keep resolving it by id. Must be the current active holder of blueprint_key in the same visibility scope (platform gallery, your org, or the same project); omit it or send null to create a blueprint under a new and unique key.
string
required
The prj_ id of the project to register the blueprint in, which you must be able to modify. A blueprint’s project is fixed when it is created. v2.0.0+
Starting with version 2.0.1, project_id is required. A request without it returns 400 with code project_required. To start from a canonical blueprint, or from one outside any project, copy it into a project with Copy Blueprint instead.

Blueprint document

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>"}. Port names come from each node’s contract in the node registry. edges is empty for a blueprint with a single node.
object
ID-keyed map of source/sink nodes. Each entry is {"key": "<node key>", "config": {...}}, where key (required) is a node key from the node registry and config is validated against that node’s config schema ({} when the node takes no config). Defaults to empty.
object
ID-keyed map of every processing (non-connector) node, in the same entry shape as connectors. Defaults to empty.
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.
Give values directly. A document that takes values from a model’s saved parameters (${models.<model>.parameters…}) is no longer supported and is rejected with HTTP status code 400.
Starting with version 2.0.1, the service checks each node config that these values settle against the node’s config schema. A value the schema rejects (for example, one above the node’s maximum) returns HTTP status code 400, and the error message names the node and the key. Source and sink connector nodes, and configs that still hold an unresolved ${...} reference, are checked when the agent runs instead.
object
Model slots the blueprint exposes and their default models, as a JSON object. A bundle’s models override these per slot.
Starting with version 2.0.0, a slot’s default can be an mdl_ model ID as well as a registry tag. An ID pins one exact model from the model registry, including a fine-tuned Newton-C model.
object
Named external artifacts the blueprint expects, as {name: location} (string values). A bundle’s artifacts supply or override them.
Starting with version 2.0.0, a value that is not a location string (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.
object
Optional metrics catalog: the objectives an eval can score this blueprint against, the recommended primary, the node whose output it scores, and family-specific scoring metadata. A blueprint publishes at most one catalog; one publishing none cannot be evaluated or optimized. See Get Blueprint for the full shape. v1.1.12+
string
Must not be set on create. The service assigns the id when it stores the blueprint, and a supplied one is rejected with HTTP status code 400.

Response

Returns the stored blueprint.
string
required
TypeID-encoded blueprint identifier (blp_ prefix).
string
required
The key this blueprint was registered under.
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.
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; this value is null if the blueprint is not part of a project. v2.0.0+
object
Where this blueprint came from, when it was not authored directly. Omitted for an authored blueprint, so it is absent on a blueprint created through this endpoint. See Get Blueprint. v1.1.12+
string
required
Creation timestamp (date-time).

Important Notes

  • Creating a blueprint requires the admin role, and the blueprint is registered under the caller’s organization.
  • A 403 with code capability_locked means blueprint creation is not available to the caller’s organization.
  • Omit replacement_of to create a blueprint under a new and unique key; a key that already exists returns 409.
  • replacement_of must name the current active holder of blueprint_key in the same visibility scope (platform gallery, your org, or the same project).
  • Registering into a project with project_id still requires the admin role, and you must also be able to modify the project. Any caller who can modify a project can copy a blueprint into it with Copy Blueprint. v2.0.0+
  • Keys are scoped platform, then organization, then project. Registering a key that a broader or narrower scope already uses returns 409, superseded versions included. For example, a project blueprint can’t take a platform blueprint’s key, and an organization blueprint can’t take a key used in one of its projects. Two sibling projects can use the same key. v2.0.0+
  • A request without project_id returns 400 with code project_required. Blueprints are registered in a project; to start from a canonical blueprint, copy it into a project with Copy Blueprint. v2.0.1+
  • A 400 covers an invalid document (including one that sets blueprint_id or takes values from ${models.<model>.parameters…}) and a replacement_of that does not match the given key or scope.
  • A 400 also covers a values entry that a node’s config schema rejects, such as a value out of range. The error names the node and the key. v2.0.1+
  • A 400 also covers a models value starting with aar_ or mdl_ that is not a valid artifact or model ID, and a canonical blueprint that names a model by ID. Canonical blueprints use registry tags. v2.0.0+
  • Node keys used in connectors and nodes, and the port names used in graph.edges, come from the node registry — see GET /agents/nodes/registry.
  • Give the document a metrics catalog if the blueprint is to be evaluated with POST /agents/evals or searched with POST /agents/optimizations; a blueprint publishing none cannot be scored. v1.1.12+
  • Every version registered under a key stays readable — list them with GET /agents/blueprints/{reference}/versions. v1.1.12+