curl -X POST "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials/otr_01jcb2v9h4x7mq3nt8k5rdzy6w/promote" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
curl -X POST "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials/otr_01jcb2v9h4x7mq3nt8k5rdzy6w/promote" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"blueprint_key": "osm-pump-a",
"name": "Open-set monitor (pump A)",
"description": "Tuned on the September pump A sweep."
}'
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
optimization_id = "opt_01jcb1m3t7v5xq8nr2h6kdzs4w"
trial_id = "otr_01jcb2v9h4x7mq3nt8k5rdzy6w"
response = requests.post(
f"{base_url}/agents/optimizations/{optimization_id}/trials/{trial_id}/promote",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={"blueprint_key": "osm-pump-a", "name": "Open-set monitor (pump A)"},
)
if response.status_code == 201:
blueprint = response.json()
print(f"Promoted to {blueprint['id']} under key {blueprint['blueprint_key']}")
else:
print(f"Error: {response.json()['errors']}")
const optimizationId = 'opt_01jcb1m3t7v5xq8nr2h6kdzs4w';
const trialId = 'otr_01jcb2v9h4x7mq3nt8k5rdzy6w';
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations/${optimizationId}/trials/${trialId}/promote`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ blueprint_key: 'osm-pump-a', name: 'Open-set monitor (pump A)' })
}
);
const body = await response.json();
if (response.status === 201) {
console.log(`Promoted to ${body.id} under key ${body.blueprint_key}`);
} else {
console.error('Error:', body.errors);
}
{
"id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
"blueprint_key": "osm-pump-a",
"name": "Open-set monitor (pump A)",
"description": "Tuned on the September pump A sweep.",
"document": {
"blueprint_id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
"name": "Open-set monitor (pump A)",
"graph": {"edges": []},
"values": {"window_size": 1024},
"artifacts": {"fit-classifier": "s3://.../fit-classifier"}
},
"yaml_document": null,
"is_canonical": false,
"is_active": true,
"source": {
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"values": {"window_size": 1024},
"models": {},
"artifacts": {"fit-classifier": "s3://.../fit-classifier"},
"created_by": {
"id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
"parent_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"name": "Window size sweep"
}
},
"created_at": "2026-09-18T14:05:38Z"
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid `blueprint_key`, or an empty `name`.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization, trial, or the searched blueprint not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Trial has not completed, or its blueprint key is already taken.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Optimizations
Promote Trial
Publish one optimization trial as a blueprint of its own
POST
/
agents
/
optimizations
/
{optimization_id}
/
trials
/
{trial_id}
/
promote
curl -X POST "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials/otr_01jcb2v9h4x7mq3nt8k5rdzy6w/promote" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
curl -X POST "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials/otr_01jcb2v9h4x7mq3nt8k5rdzy6w/promote" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"blueprint_key": "osm-pump-a",
"name": "Open-set monitor (pump A)",
"description": "Tuned on the September pump A sweep."
}'
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
optimization_id = "opt_01jcb1m3t7v5xq8nr2h6kdzs4w"
trial_id = "otr_01jcb2v9h4x7mq3nt8k5rdzy6w"
response = requests.post(
f"{base_url}/agents/optimizations/{optimization_id}/trials/{trial_id}/promote",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={"blueprint_key": "osm-pump-a", "name": "Open-set monitor (pump A)"},
)
if response.status_code == 201:
blueprint = response.json()
print(f"Promoted to {blueprint['id']} under key {blueprint['blueprint_key']}")
else:
print(f"Error: {response.json()['errors']}")
const optimizationId = 'opt_01jcb1m3t7v5xq8nr2h6kdzs4w';
const trialId = 'otr_01jcb2v9h4x7mq3nt8k5rdzy6w';
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations/${optimizationId}/trials/${trialId}/promote`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ blueprint_key: 'osm-pump-a', name: 'Open-set monitor (pump A)' })
}
);
const body = await response.json();
if (response.status === 201) {
console.log(`Promoted to ${body.id} under key ${body.blueprint_key}`);
} else {
console.error('Error:', body.errors);
}
{
"id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
"blueprint_key": "osm-pump-a",
"name": "Open-set monitor (pump A)",
"description": "Tuned on the September pump A sweep.",
"document": {
"blueprint_id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
"name": "Open-set monitor (pump A)",
"graph": {"edges": []},
"values": {"window_size": 1024},
"artifacts": {"fit-classifier": "s3://.../fit-classifier"}
},
"yaml_document": null,
"is_canonical": false,
"is_active": true,
"source": {
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"values": {"window_size": 1024},
"models": {},
"artifacts": {"fit-classifier": "s3://.../fit-classifier"},
"created_by": {
"id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
"parent_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"name": "Window size sweep"
}
},
"created_at": "2026-09-18T14:05:38Z"
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid `blueprint_key`, or an empty `name`.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization, trial, or the searched blueprint not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Trial has not completed, or its blueprint key is already taken.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
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 returnedblueprint_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.
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.
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.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. Must not be blank when
supplied.
string
Description for the promoted blueprint. Defaults to the searched blueprint’s.
Response
Returns201 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
create a new bundle using Create Bundle.string
required
The key the promoted blueprint was published under.
string
required
Name of the blueprint.
string
required
Description of the blueprint.
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 the key.
object
required
Where this blueprint came from: the blueprint that was searched, the overrides applied, and the
trial that produced them.
string
The YAML rendering of the blueprint, when one is included.
string
required
Creation timestamp (date-time).
Source object (source)
string
required
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
Artifact locations applied on top of that blueprint’s own, keyed by artifact name.
object
required
What produced this blueprint.
id(string, required) — the producer itself: theotr_id of the promoted trial.parent_id(string, required) — the run it belonged to: theopt_id of the optimization.name(string) — the human label of the enclosing run, when one was given to it.
curl -X POST "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials/otr_01jcb2v9h4x7mq3nt8k5rdzy6w/promote" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
curl -X POST "$ATAI_API_URL/agents/optimizations/opt_01jcb1m3t7v5xq8nr2h6kdzs4w/trials/otr_01jcb2v9h4x7mq3nt8k5rdzy6w/promote" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"blueprint_key": "osm-pump-a",
"name": "Open-set monitor (pump A)",
"description": "Tuned on the September pump A sweep."
}'
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
optimization_id = "opt_01jcb1m3t7v5xq8nr2h6kdzs4w"
trial_id = "otr_01jcb2v9h4x7mq3nt8k5rdzy6w"
response = requests.post(
f"{base_url}/agents/optimizations/{optimization_id}/trials/{trial_id}/promote",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={"blueprint_key": "osm-pump-a", "name": "Open-set monitor (pump A)"},
)
if response.status_code == 201:
blueprint = response.json()
print(f"Promoted to {blueprint['id']} under key {blueprint['blueprint_key']}")
else:
print(f"Error: {response.json()['errors']}")
const optimizationId = 'opt_01jcb1m3t7v5xq8nr2h6kdzs4w';
const trialId = 'otr_01jcb2v9h4x7mq3nt8k5rdzy6w';
const response = await fetch(
`${process.env.ATAI_API_URL}/agents/optimizations/${optimizationId}/trials/${trialId}/promote`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ blueprint_key: 'osm-pump-a', name: 'Open-set monitor (pump A)' })
}
);
const body = await response.json();
if (response.status === 201) {
console.log(`Promoted to ${body.id} under key ${body.blueprint_key}`);
} else {
console.error('Error:', body.errors);
}
{
"id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
"blueprint_key": "osm-pump-a",
"name": "Open-set monitor (pump A)",
"description": "Tuned on the September pump A sweep.",
"document": {
"blueprint_id": "blp_01jcb3r7n8k5wq2vt6y0mdhx4s",
"name": "Open-set monitor (pump A)",
"graph": {"edges": []},
"values": {"window_size": 1024},
"artifacts": {"fit-classifier": "s3://.../fit-classifier"}
},
"yaml_document": null,
"is_canonical": false,
"is_active": true,
"source": {
"blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
"values": {"window_size": 1024},
"models": {},
"artifacts": {"fit-classifier": "s3://.../fit-classifier"},
"created_by": {
"id": "otr_01jcb2v9h4x7mq3nt8k5rdzy6w",
"parent_id": "opt_01jcb1m3t7v5xq8nr2h6kdzs4w",
"name": "Window size sweep"
}
},
"created_at": "2026-09-18T14:05:38Z"
}
{
"errors": [
{
"code": "<error_code>",
"message": "Invalid `blueprint_key`, or an empty `name`.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Optimization, trial, or the searched blueprint not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Trial has not completed, or its blueprint key is already taken.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Was this page helpful?