> ## 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 Inference API's Direct Query endpoint (POST /api/inference/query) with the newton-c-2.6 or newton-fusion-1.0 model (text, image, and video reasoning) or the omega-embedding 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 Deployment

> Deploy a ready package as a batch or serving deployment so you can open sessions on it

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

## Overview

This endpoint deploys a package. A deployment is a package placed on a runtime. Once the
deployment is `ready`, you open sessions on it with [Create
Session](https://docs.archetypeai.app/api-reference/agents/sessions/create-session.md). On a `batch` deployment, each session is
one run over its own input files. On a `serving` deployment, each session sends its inputs to the
deployed agent with [Query Session](https://docs.archetypeai.app/api-reference/agents/sessions/query-session.md).

The package must be `ready`, built for the `platform` target, hold exactly one blueprint, and be
in a project. The deployment is in its package's project, and creating it requires being able to
modify that project.

The endpoint returns `202 Accepted` with the deployment in its initial status, which may be
`deploying` or already `ready`. Poll [Get Deployment](https://docs.archetypeai.app/api-reference/agents/deployments/get-deployment.md)
until it is `ready` before you open a session.

A deployment that cannot be started, is not `ready` within the platform's start deadline, or stops
working later becomes `failed`, with the reason in `error`, and its sessions fail with it. Where
the platform stops idle deployments, a `ready` `serving` deployment that no session has queried
for that long becomes `stopped` and its sessions `cancelled`, each with an event giving the
reason. Either end is final: to run the package again, deploy it again.

## Request

**package\_id** `string` *required*

The `pkg_` id of the package to deploy. It must be `ready`, built for the `platform` target,
hold exactly one blueprint, and be in a project.

**kind** `string` *required*

What to deploy the package as. `batch`: each session opened on the deployment is one run over
its own input files. `serving`: the deployed agent answers queries from every session opened on
it.

**sessions** `object`

Limits for a `serving` deployment's sessions. A `batch` deployment refuses it with `400`. Leave
it out, send `null`, or leave out any field for the defaults. Change them later with [Update
Deployment](https://docs.archetypeai.app/api-reference/agents/deployments/update-deployment.md).

**sessions.max** `integer` (default: 16)

The most sessions the deployment holds open at once, per running copy of the deployment.
Minimum `1`, maximum `1000`.

**sessions.idle\_timeout\_secs** `integer` (default: 1800)

Seconds a session can sit unused, counted from its last use, before the deployment closes it.
Maximum `86400`. `0` means never, which is refused with `400` where the platform stops idle
deployments.

## Response

Returns `202 Accepted` with the created deployment.

**id** `string` *required*

The deployment's `dpl_` id.

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

Owning organization.

**project\_id** `string` *required*

The project the deployment is in: its package's.

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

Who created the deployment: a user's `usr_` id, or the `key_` id of the service-account API key
it was created with.

**package\_id** `string` *required*

The package deployed.

**kind** `string` *required*

What the package is deployed as: `batch` or `serving`.

**status** `string` *required*

Where the deployment is in its lifecycle: `deploying`, `ready`, `stopped`, or
`failed`. Sessions can be opened only on a `ready` deployment.

**error** `string`

Why the deployment `failed`; `null` otherwise.

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

When the deployment was created (date-time).

**ready\_at** `string`

When sessions could first be opened on it; `null` until it is `ready`.

**stopped\_at** `string`

When it stopped; `null` until it is `stopped` or `failed`.

**sessions** `object`

The session settings stored for a `serving` deployment: `max` and `idle_timeout_secs`. `null`
for a `batch` deployment.

```bash cURL theme={"system"}
curl -X POST "$ATAI_API_ENDPOINT/agents/deployments" \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "package_id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
    "kind": "batch"
  }'
```

```bash cURL - Serving theme={"system"}
curl -X POST "$ATAI_API_ENDPOINT/agents/deployments" \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "package_id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
    "kind": "serving",
    "sessions": {"max": 32, "idle_timeout_secs": 900}
  }'
```

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

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

response = requests.post(
    f"{base_url}/agents/deployments",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "package_id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
        "kind": "batch",
    },
)

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

```javascript JavaScript theme={"system"}
const response = await fetch(`${process.env.ATAI_API_ENDPOINT}/agents/deployments`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    package_id: 'pkg_01jcb2x7m4qv8n3h5t6rk9dzs0',
    kind: 'batch'
  })
});

const body = await response.json();

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

```json 202 - Batch deployment created theme={"system"}
{
  "id": "dpl_01jcf3n8q5vx2mt7r4k6hbzd9a",
  "org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
  "project_id": "prj_01jcd4m8t2vq6xn3r7k5hbzw9e",
  "created_by": "usr_01jc8m6t3wr0yv5cp8j4mezt7x",
  "package_id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
  "kind": "batch",
  "status": "ready",
  "error": null,
  "created_at": "2026-10-29T16:00:00Z",
  "ready_at": "2026-10-29T16:00:00Z",
  "stopped_at": null,
  "sessions": null
}
```

```json 202 - Serving deployment created theme={"system"}
{
  "id": "dpl_01jcg7r2t9xb5qw3m8n6kfzc4d",
  "org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
  "project_id": "prj_01jcd4m8t2vq6xn3r7k5hbzw9e",
  "created_by": "usr_01jc8m6t3wr0yv5cp8j4mezt7x",
  "package_id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
  "kind": "serving",
  "status": "deploying",
  "error": null,
  "created_at": "2026-11-05T17:00:00Z",
  "ready_at": null,
  "stopped_at": null,
  "sessions": {"max": 32, "idle_timeout_secs": 900}
}
```

## Important Notes

> [!NOTE]
>
> * A `400` means the body does not parse (`invalid_request_body`), a `sessions` value is outside its limits (`out_of_range`), `sessions` is given for a `batch` deployment or `idle_timeout_secs` is `0` where idle deployments are stopped (`bad_request`), or the package was built for a target other than `platform` or holds more than one blueprint.
> * A `400` with the code `project_required` means the package is not in a project. Move it into a project, or build one there.
> * For a `serving` deployment, a `400` also means the package's blueprint cannot be served, needs hardware or a capability the platform does not provide, or sets a setting the platform owns.
> * A `429` with the code `serving_limit_reached` means your organization already has as many `serving` deployments as it may. Stop one before you deploy another.
> * A `403` means you can see the package's project but cannot modify it. In a free trial, a `403` with the code `capability_locked` means the package's blueprint is not available in the free trial.
> * A `404` means the package does not exist, belongs to another organization, or is in a project you cannot see.
> * A `409` means the package is not `ready`. If it is still `building`, poll [Get Package](https://docs.archetypeai.app/api-reference/agents/packages/get-package.md) until it is `ready`.
> * A deployed package, and its project, cannot be deleted. [Stop](https://docs.archetypeai.app/api-reference/agents/deployments/stop-deployment.md) and [delete](https://docs.archetypeai.app/api-reference/agents/deployments/delete-deployment.md) the deployment first.


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