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

# Create Bundle

> Create a deployable bundle that pins a blueprint

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

## Overview

This endpoint creates a bundle: a named, deployable customization of a blueprint.

The bundle pins one blueprint by ID or key and carries the parameters a run will use — `values`,
an optional `model` override, and optional `artifacts`. Runs bind only their I/O, via `POST
/agents/bundles/{bundle_id}/run`.

## Request

<ParamField body="blueprint" type="string" required>
  Blueprint reference to pin: a `blp_` ID or key (e.g. `osm`).

  <Note>
    While `blueprint` accepts either a `blp_` ID or a key, the response records the resolved
    immutable `blueprint_id`.
  </Note>
</ParamField>

<ParamField body="name" type="string" required>
  Human label for this bundle, e.g. `Pump A monitor`.
</ParamField>

<ParamField body="description" type="string">
  Optional human description of this bundle. Defaults to an empty string.
</ParamField>

<ParamField body="values" type="object">
  User value overrides, layered over the blueprint defaults at run time. Must be a JSON object; defaults to `{}`.
</ParamField>

<ParamField body="model" type="string">
  Optional model override; omit to use the blueprint's default.
</ParamField>

<ParamField body="artifacts" type="object">
  Optional artifact links, e.g. `{"calibration": "s3://.../knn_index"}`.
</ParamField>

<ParamField body="canonical" type="boolean" default="false">
  Publish as a canonical (platform-wide) bundle, visible to every org. Requires the super-admin
  role; defaults to an org-owned bundle.
</ParamField>

## Response

Returns the created bundle.

<ResponseField name="id" type="string" required>
  TypeID-encoded bundle identifier (`bnd_` prefix).
</ResponseField>

<ResponseField name="name" type="string" required>
  Human label for the bundle.
</ResponseField>

<ResponseField name="description" type="string" required>
  Human description of the bundle.
</ResponseField>

<ResponseField name="blueprint_id" type="string" required>
  The pinned blueprint's immutable `blp_` id. Resolve its key via the blueprint registry when needed.
</ResponseField>

<ResponseField name="values" type="object" required>
  The value overrides stored on the bundle.
</ResponseField>

<ResponseField name="status" type="string" required>
  Build lifecycle of the bundle: `building`, `ready`, or `failed`.
</ResponseField>

<ResponseField name="is_canonical" type="boolean" required>
  True for a canonical (platform-authored) bundle, visible to every org.
</ResponseField>

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

<ResponseField name="org_id" type="string">
  Owning organization; omitted for a canonical bundle.
</ResponseField>

<ResponseField name="model" type="string">
  Model override; omitted when the bundle uses the blueprint's default.
</ResponseField>

<ResponseField name="artifacts" type="object">
  Artifact links attached to the bundle.
</ResponseField>

<ResponseField name="latest_runs" type="array">
  The bundle's five most recent runs, newest first. Present only when a read asked for it via
  `include_latest_runs=true`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST "$ATAI_API_URL/agents/bundles" \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "blueprint": "osm",
      "name": "Pump A monitor",
      "description": "Open-set monitor tuned for pump A telemetry.",
      "values": {},
      "artifacts": {
        "calibration": "s3://.../knn_index"
      }
    }'
  ```

  ```python Python theme={"system"}
  import os
  import requests

  base_url = os.environ["ATAI_API_URL"]
  api_key = os.environ["ATAI_API_KEY"]

  response = requests.post(
      f"{base_url}/agents/bundles",
      headers={
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json",
      },
      json={
          "blueprint": "osm",
          "name": "Pump A monitor",
          "description": "Open-set monitor tuned for pump A telemetry.",
          "values": {},
          "artifacts": {"calibration": "s3://.../knn_index"},
      },
  )

  if response.status_code == 201:
      bundle = response.json()
      print(f"Created bundle {bundle['id']} pinning {bundle['blueprint_id']}")
  else:
      print(f"Error: {response.json()['errors']}")
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch(`${process.env.ATAI_API_URL}/agents/bundles`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      blueprint: 'osm',
      name: 'Pump A monitor',
      description: 'Open-set monitor tuned for pump A telemetry.',
      values: {},
      artifacts: { calibration: 's3://.../knn_index' }
    })
  });

  const body = await response.json();

  if (response.status === 201) {
    console.log(`Created bundle ${body.id} pinning ${body.blueprint_id}`);
  } else {
    console.error('Error:', body.errors);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 201 - Created theme={"system"}
  {
    "id": "bnd_01jc9pd42kzq7v8n3h5m6rtx0w",
    "org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
    "name": "Pump A monitor",
    "description": "Open-set monitor tuned for pump A telemetry.",
    "blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
    "model": null,
    "values": {},
    "artifacts": {
      "calibration": "s3://.../knn_index"
    },
    "status": "ready",
    "is_canonical": false,
    "created_at": "2026-08-11T15:02:19Z"
  }
  ```

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

  ```json 403 - Super-admin required theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Super-admin required for canonical bundles.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

  ```json 404 - Blueprint not found theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Blueprint not found.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>

## Important Notes

<Note>
  * The pin is immutable: a later version of the key does not change what this bundle runs.
  * Parameters and model live on the bundle, not on the run request — a run supplies only connectors.
  * `canonical: true` requires the super-admin role.
</Note>