> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Start with /introduction/getting-started. Use the Direct Query API (POST /query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT must include the version path: /v0.5 for most APIs, /v0.6 for the Fine-Tuning Service. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# Promote Trial

> Publish one optimization trial as a blueprint of its own

<Callout icon="clock" color="#3064E3" iconType="solid">
  Requires [version 1.1.12](/release-notes/1.1.x#v1-1-12) or later of the Archetype platform.
</Callout>

## 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.

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

<ParamField path="optimization_id" type="string" required>
  Parent optimization `opt_` id.
</ParamField>

<ParamField path="trial_id" type="string" required>
  Trial `otr_` id to promote.
</ParamField>

<ParamField body="blueprint_key" type="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.

  <Note>
    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.
  </Note>
</ParamField>

<ParamField body="name" type="string">
  Name for the promoted blueprint. Defaults to the searched blueprint's. Must not be blank when
  supplied.
</ParamField>

<ParamField body="description" type="string">
  Description for the promoted blueprint. Defaults to the searched blueprint's.
</ParamField>

## Response

Returns `201 Created` with the promoted blueprint, in the shape
[Get Blueprint](/api-reference/agents/blueprints/get-blueprint) returns.

<ResponseField name="id" type="string" required>
  TypeID-encoded blueprint identifier (`blp_` prefix) of the new blueprint.

  <Note>
    Use this blueprint ID as the `blueprint_id` for a new eval, another optimization, or to
    create a new bundle using [Create Bundle](/api-reference/agents/bundles/create-bundle).
  </Note>
</ResponseField>

<ResponseField name="blueprint_key" type="string" required>
  The key the promoted blueprint was published under.
</ResponseField>

<ResponseField name="name" type="string" required>
  Name of the blueprint.
</ResponseField>

<ResponseField name="description" type="string" required>
  Description of the blueprint.
</ResponseField>

<ResponseField name="document" type="object" required>
  The blueprint document: the searched blueprint with the trial's parameter values, model
  choices, and trained artifacts applied.
</ResponseField>

<ResponseField name="is_canonical" type="boolean" required>
  `false` — a promoted blueprint belongs to your organization, not the platform gallery.
</ResponseField>

<ResponseField name="is_active" type="boolean" required>
  True for the current version of the key.
</ResponseField>

<ResponseField name="source" type="object" required>
  Where this blueprint came from: the blueprint that was searched, the overrides applied, and the
  trial that produced them.
</ResponseField>

<ResponseField name="yaml_document" type="string">
  The YAML rendering of the blueprint, when one is included.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  Creation timestamp (date-time).
</ResponseField>

### Source object (`source`)

<ResponseField name="blueprint_id" type="string" required>
  The blueprint this one was derived from — the one the optimization searched.
</ResponseField>

<ResponseField name="values" type="object" required>
  Parameter value overrides applied on top of that blueprint's own.
</ResponseField>

<ResponseField name="models" type="object" required>
  Model slot overrides applied on top of that blueprint's own.
</ResponseField>

<ResponseField name="artifacts" type="object">
  Artifact locations applied on top of that blueprint's own, keyed by artifact name.
</ResponseField>

<ResponseField name="created_by" type="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.
</ResponseField>

<RequestExample>
  ```bash cURL - Generated Key theme={"system"}
  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 '{}'
  ```

  ```bash cURL - Chosen Key And Name theme={"system"}
  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."
    }'
  ```

  ```python Python theme={"system"}
  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']}")
  ```

  ```javascript JavaScript theme={"system"}
  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);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 201 - The promoted blueprint theme={"system"}
  {
    "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"
  }
  ```

  ```json 400 - Invalid blueprint_key or empty name theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Invalid `blueprint_key`, or an empty `name`.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

  ```json 404 - Optimization, trial, or searched blueprint not found theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Optimization, trial, or the searched blueprint not found.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

  ```json 409 - Trial not completed, or key taken theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Trial has not completed, or its blueprint key is already taken.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.