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

> Open a session on a ready deployment to run its package over your input files or answer queries

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 opens a session on a deployment. The deployment must be `ready`, 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](https://docs.archetypeai.app/api-reference/agents/sessions/get-session.md) to follow it, then read what it produced
with [Get Session Results](https://docs.archetypeai.app/api-reference/agents/sessions/get-session-results.md).

A session on a `serving` deployment sends its inputs to the deployed agent with [Query
Session](https://docs.archetypeai.app/api-reference/agents/sessions/query-session.md), 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

**deployment\_id** `string` *required*

The `dpl_` id of the deployment to open the session on. It must be `ready`.

**connectors** `object`

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

**connectors.source** `array`

One or more input refs. Each entry is a data ref.

**connectors.sink** `object`

Optional output ref; omit it or send `null` for the default. It must not name a file that
already exists.

**values** `object`

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+](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-1)

### Data ref

**type** `string` *required*

Storage kind, for example `file`.

**id** `string` *required*

Identifier within that storage kind, for example `file_abc123`.

**format** `string`

Optional format hint, for example `csv`.

## Response

Returns `202 Accepted` with the created session.

**id** `string` *required*

The session's `ses_` id.

**deployment\_id** `string` *required*

The deployment the session runs in.

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

The deployment's package.

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

Owning organization.

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

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

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

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

**kind** `string` *required*

How the session runs: always its deployment's kind, `batch` or `serving`.

**status** `string` *required*

Where the session is in its lifecycle: `pending`, `running`, `completed`, `failed`, or
`cancelled`. The last three are terminal.

**connectors** `object`

A batch session's input files and optional output file; `null` for a serving session.

**job\_id** `string`

The job running a batch session, once it has been dispatched; `null` before that and for a
serving session.

**error** `string`

Why the session `failed`, or why the platform cancelled it; `null` otherwise.

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

When the session was created (date-time).

**started\_at** `string`

When it started running; `null` until then.

**completed\_at** `string`

When it reached a terminal status; `null` until then.

**values** `object`

The session's own `values`; `null` when it has none. [v2.0.1+](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-1)

```bash cURL theme={"system"}
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"}]
    }
  }'
```

```bash cURL - Serving theme={"system"}
curl -X POST "$ATAI_API_ENDPOINT/agents/sessions" \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deployment_id": "dpl_01jcg7r2t9xb5qw3m8n6kfzc4d"}'
```

```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/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']}")
```

```javascript JavaScript theme={"system"}
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);
}
```

```json 202 - Session created theme={"system"}
{
  "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

> [!NOTE]
>
> * A `400` means the body does not parse (`invalid_request_body`), a batch session has no `connectors`, no `file` among its sources, or a source file that does not exist or the project's creator cannot read, or a serving session gives `connectors`.
> * A `403` means you can see the deployment'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 deployment does not exist, belongs to another organization, or is in a project you cannot see.
> * A `409` means the deployment is not `ready` (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 `409` with the code `deployment_sessions_unsupported` means `values` were given and the deployment runs without sessions. Deploy the package again.
> * A `422` with the code `values_not_supported` means `values` were given for a batch session; `invalid_session_values` means the values cannot be applied, named in the message; `session_channel_collision` means the blueprint's WebSocket channel is not keyed per session.
> * A `429` with the code `session_limit_reached` means the deployment holds its `max` sessions. Cancel one, or wait for one to end.
> * A `500` with the code `internal_error` means the deployment cannot build a session. Retrying will not help.
> * A `502` with the code `worker_unavailable` means the session could not be opened and nothing was created. Retry.
> * A `503` with the code `unavailable` means the deployment cannot be reached just now. Retry.
> * A session that is `pending` or `running` can be cancelled with [Cancel Session](https://docs.archetypeai.app/api-reference/agents/sessions/cancel-session.md).


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