curl -X POST "$ATAI_API_ENDPOINT/agents/sessions" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"deployment_id": "dpl_01jcf3n8q5vx2mt7r4k6hbzd9a",
"connectors": {
"source": [{"type": "file", "id": "file_abc123", "format": "csv"}]
}
}'
curl -X POST "$ATAI_API_ENDPOINT/agents/sessions" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"deployment_id": "dpl_01jcg7r2t9xb5qw3m8n6kfzc4d"}'
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/sessions",
headers={"Authorization": f"Bearer {api_key}"},
json={
"deployment_id": "dpl_01jcf3n8q5vx2mt7r4k6hbzd9a",
"connectors": {
"source": [{"type": "file", "id": "file_abc123", "format": "csv"}],
},
},
)
if response.status_code == 202:
session = response.json()
print(session["id"], session["status"])
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(`${process.env.ATAI_API_ENDPOINT}/agents/sessions`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
deployment_id: 'dpl_01jcf3n8q5vx2mt7r4k6hbzd9a',
connectors: {
source: [{ type: 'file', id: 'file_abc123', format: 'csv' }]
}
})
});
const body = await response.json();
if (response.status === 202) {
console.log(body.id, body.status);
} else {
console.error('Error:', body.errors);
}
{
"id": "ses_01jcf4p9r6wy3nv8s5m7jcae0b",
"deployment_id": "dpl_01jcf3n8q5vx2mt7r4k6hbzd9a",
"package_id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"project_id": "prj_01jcd4m8t2vq6xn3r7k5hbzw9e",
"created_by": "usr_01jc8m6t3wr0yv5cp8j4mezt7x",
"kind": "batch",
"status": "pending",
"connectors": {
"source": [{"type": "file", "id": "file_abc123", "format": "csv"}]
},
"job_id": null,
"error": null,
"created_at": "2026-10-29T16:05:00Z",
"started_at": null,
"completed_at": null
}
Sessions
Create Session
Open a session on a ready deployment to run its package over your input files or answer queries
POST
/
api
/
agents
/
sessions
curl -X POST "$ATAI_API_ENDPOINT/agents/sessions" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"deployment_id": "dpl_01jcf3n8q5vx2mt7r4k6hbzd9a",
"connectors": {
"source": [{"type": "file", "id": "file_abc123", "format": "csv"}]
}
}'
curl -X POST "$ATAI_API_ENDPOINT/agents/sessions" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"deployment_id": "dpl_01jcg7r2t9xb5qw3m8n6kfzc4d"}'
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/sessions",
headers={"Authorization": f"Bearer {api_key}"},
json={
"deployment_id": "dpl_01jcf3n8q5vx2mt7r4k6hbzd9a",
"connectors": {
"source": [{"type": "file", "id": "file_abc123", "format": "csv"}],
},
},
)
if response.status_code == 202:
session = response.json()
print(session["id"], session["status"])
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(`${process.env.ATAI_API_ENDPOINT}/agents/sessions`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
deployment_id: 'dpl_01jcf3n8q5vx2mt7r4k6hbzd9a',
connectors: {
source: [{ type: 'file', id: 'file_abc123', format: 'csv' }]
}
})
});
const body = await response.json();
if (response.status === 202) {
console.log(body.id, body.status);
} else {
console.error('Error:', body.errors);
}
{
"id": "ses_01jcf4p9r6wy3nv8s5m7jcae0b",
"deployment_id": "dpl_01jcf3n8q5vx2mt7r4k6hbzd9a",
"package_id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"project_id": "prj_01jcd4m8t2vq6xn3r7k5hbzw9e",
"created_by": "usr_01jc8m6t3wr0yv5cp8j4mezt7x",
"kind": "batch",
"status": "pending",
"connectors": {
"source": [{"type": "file", "id": "file_abc123", "format": "csv"}]
},
"job_id": null,
"error": null,
"created_at": "2026-10-29T16:05:00Z",
"started_at": null,
"completed_at": null
}
Requires version 2.0.1 or later of the Archetype platform.
Overview
This endpoint opens a session on a deployment. The deployment must beready, and the session
runs the deployment’s package.
A session on a batch deployment is one run over its own input files, given in connectors.
The platform submits one job for it, and the session moves from pending to running, then ends
as completed, failed, or cancelled. Poll Get
Session to follow it, then read what it produced
with Get Session Results.
A session on a serving deployment sends its inputs to the deployed agent with Query
Session, so it takes no connectors. It can run
with values of its own. It runs until you cancel it, its deployment ends, or it ends on its own,
for example after its idle timeout; its error says why. Opening a serving session can take up to
60 seconds, so do not retry before the call returns.
The session is in its deployment’s project, and opening it requires being able to modify that
project. A batch session’s job runs as the project’s creator, so its source files must be files the
project’s creator can read.
The endpoint returns 202 Accepted with the session in its initial status, which may be pending
or already running. Query a serving session once it is running.
Request
The session’s input files and optional output file. Required for a batch session, which reads
its input from them, so
source must list at least one file ref. A serving session must omit
connectors.Optional output ref; omit it or send
null for the default. It must not name a file that
already exists.Values a
serving session runs with, by name, over its deployment’s. Each must be one the
blueprint declares, and reach only a node’s session fields. Omitted, null and {} mean none.
A batch session refuses non-empty values with 422. v2.0.1+Data ref
Response
Returns202 Accepted with the created session.
Who opened the session: a user’s
usr_ id, or the key_ id of the service-account API key it
was opened with.Where the session is in its lifecycle:
pending, running, completed, failed, or
cancelled. The last three are terminal.The job running a batch session, once it has been dispatched;
null before that and for a
serving session.The session’s own
values; null when it has none. v2.0.1+curl -X POST "$ATAI_API_ENDPOINT/agents/sessions" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"deployment_id": "dpl_01jcf3n8q5vx2mt7r4k6hbzd9a",
"connectors": {
"source": [{"type": "file", "id": "file_abc123", "format": "csv"}]
}
}'
curl -X POST "$ATAI_API_ENDPOINT/agents/sessions" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"deployment_id": "dpl_01jcg7r2t9xb5qw3m8n6kfzc4d"}'
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/sessions",
headers={"Authorization": f"Bearer {api_key}"},
json={
"deployment_id": "dpl_01jcf3n8q5vx2mt7r4k6hbzd9a",
"connectors": {
"source": [{"type": "file", "id": "file_abc123", "format": "csv"}],
},
},
)
if response.status_code == 202:
session = response.json()
print(session["id"], session["status"])
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(`${process.env.ATAI_API_ENDPOINT}/agents/sessions`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
deployment_id: 'dpl_01jcf3n8q5vx2mt7r4k6hbzd9a',
connectors: {
source: [{ type: 'file', id: 'file_abc123', format: 'csv' }]
}
})
});
const body = await response.json();
if (response.status === 202) {
console.log(body.id, body.status);
} else {
console.error('Error:', body.errors);
}
{
"id": "ses_01jcf4p9r6wy3nv8s5m7jcae0b",
"deployment_id": "dpl_01jcf3n8q5vx2mt7r4k6hbzd9a",
"package_id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
"org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
"project_id": "prj_01jcd4m8t2vq6xn3r7k5hbzw9e",
"created_by": "usr_01jc8m6t3wr0yv5cp8j4mezt7x",
"kind": "batch",
"status": "pending",
"connectors": {
"source": [{"type": "file", "id": "file_abc123", "format": "csv"}]
},
"job_id": null,
"error": null,
"created_at": "2026-10-29T16:05:00Z",
"started_at": null,
"completed_at": null
}
Important Notes
- A
400means the body does not parse (invalid_request_body), a batch session has noconnectors, nofileamong its sources, or a source file that does not exist or the project’s creator cannot read, or a serving session givesconnectors. - A
403means you can see the deployment’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 deployment does not exist, belongs to another organization, or is in a project you cannot see. - A
409means the deployment is notready(for example, it was stopped) or its agent has stopped, with the reason in the message, or the sink names a file that already exists. - A
409with the codedeployment_sessions_unsupportedmeansvalueswere given and the deployment runs without sessions. Deploy the package again. - A
422with the codevalues_not_supportedmeansvalueswere given for a batch session;invalid_session_valuesmeans the values cannot be applied, named in the message;session_channel_collisionmeans the blueprint’s WebSocket channel is not keyed per session. - A
429with the codesession_limit_reachedmeans the deployment holds itsmaxsessions. Cancel one, or wait for one to end. - A
500with the codeinternal_errormeans the deployment cannot build a session. Retrying will not help. - A
502with the codeworker_unavailablemeans the session could not be opened and nothing was created. Retry. - A
503with the codeunavailablemeans the deployment cannot be reached just now. Retry. - A session that is
pendingorrunningcan be cancelled with Cancel Session.
Was this page helpful?