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

Overview

This endpoint promotes one trial of an optimization to a blueprint of its own. An optimization does not publish a blueprint per trial — a run of hundreds of trials would bury your catalog, and most trials are never wanted. This endpoint materializes the one you pick: the searched blueprint with that trial’s parameter values, model choices, and trained artifacts applied, so the result is a blueprint you can evaluate, package, or use as the base of another optimization by its returned blueprint_id. The new blueprint belongs to your organization and records where it came from in its source field — the blueprint that was searched, the overrides applied, and the trial that produced them. When the run is in a project, the new blueprint lands in the same project, and promoting requires being able to modify that project. A run in a project you cannot see returns 404. Only a completed trial can be promoted; attempting to promote a trial whose status has any other value will result in an HTTP 409 error. A trial that met none of the run’s constraints is still promotable despite being classified as infeasible — the choice of which trade-off to ship is yours. Every field of the body is optional, so {} is a complete request. An empty body promotes the trial under a generated key, inheriting the name and description of the blueprint the optimization searched. Once promoted, the trial’s promoted_blueprint field (see List Optimization Trials) names the new blueprint. A trial can be promoted at most once. The request is rejected with 400 for an invalid blueprint_key or an empty name; with 403 (capability_locked) when the searched blueprint is not available to the caller’s organization; with 404 when the optimization, the trial, or the searched blueprint is not found; and with 409 when the trial has not completed or its blueprint key is already taken.

Request

string
required
Parent optimization opt_ id.
string
required
Trial otr_ id to promote.
string
Key to publish the promoted blueprint under. Defaults to the searched blueprint’s key suffixed with the trial’s id, which is unique per trial; supply one to choose a friendlier handle. Rejected with 409 when your organization already has an active blueprint under this key. Omit it or send null to use the default.Outside projects, choosing a blueprint_key requires the admin role, and other callers get 403. In a project, anyone who can modify the project may choose it.
If you don’t specify a blueprint_key, a key is generated by appending the trial’s ID to the end of the searched blueprint’s key. Promoting the same trial twice in this manner will respond with a 409 error rather than creating a duplicate.
string
Name for the promoted blueprint. Defaults to the searched blueprint’s when omitted or null. Must not be blank when supplied.
string
Description for the promoted blueprint. Defaults to the searched blueprint’s when omitted or null.

Response

Returns 201 Created with the promoted blueprint, in the shape Get Blueprint returns.
string
required
TypeID-encoded blueprint identifier (blp_ prefix) of the new blueprint.
Use this blueprint ID as the blueprint_id for a new eval, another optimization, or to build a package using Create Package.
string
required
The key the promoted blueprint was published 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: the searched blueprint with the trial’s parameter values, model choices, and trained artifacts applied.
boolean
required
false — a promoted blueprint belongs to your organization, not the platform gallery.
boolean
required
true for the current version of a key; false once it has been replaced by a newer blueprint.
string
The project the blueprint lives in: the run’s project. null outside any project. v2.0.0+
object
Where this blueprint came from: the blueprint that was searched, the overrides applied, and the trial that produced them. Always present on a promoted blueprint; omitted for a blueprint authored directly. See Source object for the format of this record.
string
The YAML rendering of the blueprint, when one is included; omitted otherwise.
string
required
Creation timestamp (date-time).

Source object (source)

string
required
How the blueprint was derived, which decides the other fields present. Always promotion for a blueprint returned by this endpoint. v1.1.13+
string
required
The ID of the blueprint this one was derived from; the one the optimization searched.
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
required
What produced this blueprint.
  • id (string, required) — the producer itself: the otr_ id of the promoted trial.
  • parent_id (string, required) — the run it belonged to: the opt_ id of the optimization.
  • name (string) — the human label of the enclosing run, when one was given to it.