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"
}'
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}
}'
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']}")
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);
}
{
"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
}
{
"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}
}
Deployments
Create Deployment
Deploy a ready package as a batch or serving deployment so you can open sessions on it
POST
/
api
/
agents
/
deployments
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"
}'
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}
}'
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']}")
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);
}
{
"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
}
{
"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}
}
Requires version 2.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 isready, you open sessions on it with Create
Session. 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.
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
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
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.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.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.The most sessions the deployment holds open at once, per running copy of the deployment.
Minimum
1, maximum 1000.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
Returns202 Accepted with the created deployment.
Who created the deployment: a user’s
usr_ id, or the key_ id of the service-account API key
it was created with.Where the deployment is in its lifecycle:
deploying, ready, stopped, or
failed. Sessions can be opened only on a ready deployment.The session settings stored for a
serving deployment: max and idle_timeout_secs. null
for a batch deployment.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"
}'
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}
}'
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']}")
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);
}
{
"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
}
{
"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
- A
400means the body does not parse (invalid_request_body), asessionsvalue is outside its limits (out_of_range),sessionsis given for abatchdeployment oridle_timeout_secsis0where idle deployments are stopped (bad_request), or the package was built for a target other thanplatformor holds more than one blueprint. - A
400with the codeproject_requiredmeans the package is not in a project. Move it into a project, or build one there. - For a
servingdeployment, a400also 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
429with the codeserving_limit_reachedmeans your organization already has as manyservingdeployments as it may. Stop one before you deploy another. - A
403means you can see the package’s project but cannot modify it. In a free trial, a403with the codecapability_lockedmeans the package’s blueprint is not available in the free trial. - A
404means the package does not exist, belongs to another organization, or is in a project you cannot see. - A
409means the package is notready. If it is stillbuilding, poll Get Package until it isready. - A deployed package, and its project, cannot be deleted. Stop and delete the deployment first.
Was this page helpful?