> ## 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 /api/lens/query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT is the base URL https://platform.u1.archetypeai.app with no version path; every endpoint path begins with /api. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# Create Package

> Build an immutable package from a blueprint so you can run it as a batch job or a serving agent

Requires [version 2.0.0](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-0) or later of the Archetype platform.

## Overview

This endpoint builds a package: an immutable build of a blueprint for a target, ready to run
with [Create Agent](https://docs.archetypeai.app/api-reference/agents/instances/create-agent.md).

When the package is built, every model slot of the blueprint is resolved the way running it would
resolve them:

* A model registry tag resolves to the model it names.
* An `mdl_` model id resolves to that model.
* An optimization's fitted artifact, named in the slot by its `aar_` id (as a promoted trial's
  blueprint carries it), resolves to that artifact.

What every slot resolved to is fixed at build time. If a tag later moves to another model, or
the blueprint's key is replaced, the package still runs the same models. The response's
`blueprints[].resolved_models` shows what each slot resolved to. To change any of it, build a new
package.

The target says where the package will run. Whether it runs as a batch job or a serving agent is
chosen when you run it, not when you build it.

The endpoint returns `202 Accepted` with the package. A build can take longer than the request,
so check its `status`. Use the package once it is `ready`. If it is still `building`, poll [Get
Package](https://docs.archetypeai.app/api-reference/agents/packages/get-package.md) until it is `ready` or `failed`.

## Request

**blueprint\_ids** `array` *required*

The blueprints to package, by `blp_` id. A `blp_` id names one immutable blueprint version, so
the package holds exactly what you asked for. Must contain exactly one blueprint.

**target** `object` *required*

Where the package is meant to run.

**target.kind** `string` *required*

`platform` for the Archetype platform, or `edge` for a device outside it. Building for `edge`
returns `501`: it is not available yet.

**name** `string`

Human label for the package, for example `Pump line 3`. Lists show it, and every run of the
package is called by it. Trimmed, then up to 128 characters. Omit it, or leave it blank, to
name the package after its blueprint.

**description** `string`

Optional human description of what the package is for. Defaults to an empty string. Capped at
512 characters, as on bundles.

## Response

Returns `202 Accepted` with the package.

**id** `string` *required*

TypeID-encoded package identifier (`pkg_` prefix).

**org\_id** `string` *required*

Organization the package belongs to.

**name** `string` *required*

Human label given on create, or the blueprint's name when none was given. Also the name of every
run of the package.

**description** `string` *required*

Human description given on create. Empty when none was given.

**created\_by** `string` *required*

Subject id (`usr_...` or `key_...`) that created the package.

**target** `object` *required*

Where the package is meant to run, as `{"kind": "platform"}` or `{"kind": "edge"}`.

**status** `string` *required*

Build status: `building`, `ready`, or `failed`. You can run the package once it is `ready`.

**blueprints** `array` *required*

The blueprints the package holds, in the order they were given.

**blueprints\[].blueprint\_id** `string` *required*

The blueprint's immutable `blp_` id.

**blueprints\[].resolved\_models** `object` *required*

What each model slot resolved to when the package was built: slot name to an `mdl_` id (a model
from the model registry) or an `aar_` id (an artifact an optimization trial produced, as named
in a promoted blueprint). Slots bound to an artifact the blueprint names itself are absent.
Empty when no slot named a registry entry.

**project\_id** `string`

The project the package is in, which is its blueprint's project. `null` outside any project.

**created\_at** `string` *required*

When the package was built (date-time).

```bash cURL theme={"system"}
curl -X POST "$ATAI_API_URL/api/agents/packages" \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blueprint_ids": ["blp_01jc9n7k3xf8mbq2v5t0ary6de"],
    "target": {"kind": "platform"},
    "name": "Pump line 3",
    "description": "Pump A monitor"
  }'
```

```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}/api/agents/packages",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "blueprint_ids": ["blp_01jc9n7k3xf8mbq2v5t0ary6de"],
        "target": {"kind": "platform"},
        "name": "Pump line 3",
        "description": "Pump A monitor",
    },
)

if response.status_code == 202:
    package = response.json()
    print(f"Package {package['id']} is {package['status']}")
else:
    print(f"Error: {response.json()['errors']}")
```

```javascript JavaScript theme={"system"}
const response = await fetch(`${process.env.ATAI_API_URL}/api/agents/packages`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    blueprint_ids: ['blp_01jc9n7k3xf8mbq2v5t0ary6de'],
    target: { kind: 'platform' },
    name: 'Pump line 3',
    description: 'Pump A monitor'
  })
});

const body = await response.json();

if (response.status === 202) {
  console.log(`Package ${body.id} is ${body.status}`);
} else {
  console.error('Error:', body.errors);
}
```

```json 202 - Build accepted theme={"system"}
{
  "id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
  "org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
  "name": "Pump line 3",
  "description": "Pump A monitor",
  "created_by": "usr_01jc8m6t3wr0yv5cp8j4mezt7x",
  "target": {"kind": "platform"},
  "status": "ready",
  "blueprints": [
    {
      "blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
      "resolved_models": {
        "embedder": "mdl_01jc7k2p9xq4vm8n3t5rbh6dzw"
      }
    }
  ],
  "project_id": null,
  "created_at": "2026-10-21T15:10:00Z"
}
```

```json 400 - Invalid request theme={"system"}
{
  "errors": [
    {
      "code": "<error_code>",
      "message": "Invalid request, or a blueprint that cannot be resolved or could not run.",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

```json 403 - Blueprint not available theme={"system"}
{
  "errors": [
    {
      "code": "capability_locked",
      "message": "Blueprint not available to the caller's organization.",
      "suggestion": "Contact support@archetypeai.dev to unlock it.",
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

```json 404 - Blueprint or model not found theme={"system"}
{
  "errors": [
    {
      "code": "not_found",
      "message": "A blueprint, or a model tag, model id or artifact one of its slots names, was not found.",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

```json 501 - Edge target theme={"system"}
{
  "errors": [
    {
      "code": "not_supported",
      "message": "edge packages are not supported yet",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

## Important Notes

> [!NOTE]
>
> * A `name` longer than 128 characters after trimming returns `400`.
> * A package holds exactly one blueprint for now. An empty `blueprint_ids`, or one with more than one id, returns `400`.
> * A `400` also covers a blueprint that cannot be resolved: a slot with no model yet, an invalid model reference, an archived tag, or a fine-tuned (promoted) model that is not a Newton-C LoRA fine-tune or sits in a slot whose node cannot apply it. It also covers a blueprint that could not run, such as one that requires values only an optimization fills in.
> * A `403` with code `capability_locked` means the blueprint is not available to your organization. A `403` without that code means you can see the blueprint's project but not modify it.
> * A `404` covers a blueprint you cannot see or that was deleted during the build, and a slot that names a tag, model id or artifact that does not exist or is not visible to your organization.
> * A package of a blueprint in a project is in that project. Creating it requires being able to modify the project.
> * Deleting a package never touches the blueprint it holds.


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