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

> Open a session on a platform-hosted model, with its own values and state

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 one of the [available models](https://docs.archetypeai.app/api-reference/inference/about#available-models).
A session gets its own `values` and its own state, on a copy of the model it shares with other
callers' sessions. Queries you send to the session use them. Queries sent straight to
`/api/inference/query`, `/chat/completions`, or `/responses` share one stream on the model instead.

The session belongs to you. Any role can open one. The call returns `201` once the session can be
queried, which can take up to 60 seconds. Don't retry before the call returns.

A session runs until you [cancel](https://docs.archetypeai.app/api-reference/inference/sessions/cancel-session.md) it, until it
sits idle for 30 minutes, or until the copy of the model holding it goes away. That last case
happens when the copy is replaced or lost, for example during a platform release. The session then
reads `failed` or `cancelled`, and it doesn't come back. When a call on a session returns `409`
with code `session_not_running`, open a new session. You don't need to read `error` first.

> [!NOTE]
>
> Each model limits how many sessions are open at once: 16 per organization and 32 per copy of the
> model. The organization limit counts each model separately, so your sessions on other models don't
> count toward it.

## Request

**model** `string` *required*

The model to open the session on: its name or any of its other names, 1 to 128 characters. See
[Available Models](https://docs.archetypeai.app/api-reference/inference/about#available-models).

**values** `object`

Values the session runs with, by name, in place of the model's own. Each must be a value the model
declares for sessions; any other key returns `422` with code `invalid_session_values`, naming the
key. Values are fixed for the life of the session. Omitted, `null`, and `{}` all mean none.

## Response

Returns `201` with the [session object](https://docs.archetypeai.app/api-reference/inference/sessions/get-session.md#response).

```bash cURL theme={"system"}
curl -X POST "$ATAI_API_ENDPOINT/inference/sessions" \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omega-embedding",
    "values": {"window_size": 1024, "step_size": 512}
  }'
```

```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}/inference/sessions",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "omega-embedding",
        "values": {"window_size": 1024, "step_size": 512},
    },
)

if response.status_code == 201:
    print(f"Session opened: {response.json()['id']}")
else:
    print(f"Error: {response.json()['errors']}")
```

```javascript JavaScript theme={"system"}
const response = await fetch(`${process.env.ATAI_API_ENDPOINT}/inference/sessions`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'omega-embedding',
    values: { window_size: 1024, step_size: 512 }
  })
});

const body = await response.json();
if (response.status === 201) {
  console.log(`Session opened: ${body.id}`);
} else {
  console.error('Error:', body.errors);
}
```

```json 201 - Session opened theme={"system"}
{
  "id": "ses_01jcx4m8t2vq6xn3r7k5hbzw9e",
  "model": "omega-embedding",
  "status": "running",
  "values": {"window_size": 1024, "step_size": 512},
  "error": null,
  "created_at": "2026-11-11T09:12:44Z",
  "started_at": "2026-11-11T09:12:51Z",
  "completed_at": null
}
```

```json 429 - Session limit reached theme={"system"}
{
  "errors": [
    {
      "code": "session_limit_reached",
      "message": "<message>",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

## Important Notes

> [!NOTE]
>
> * `400` means `model` is missing, empty, or not a string, or the body doesn't parse.
> * `404` means no model has that name.
> * `422` with `invalid_session_values` means a key in `values` can't be set on a session. Nothing was created.
> * `429` with `session_limit_reached` means your organization already holds as many open sessions on this
>   model as it may, or every copy of the model is full. Cancel a session or wait for an idle one to end.
>   Nothing was created.
> * `502` with `worker_unavailable` means the session couldn't be opened. Nothing was created; retry.
> * `503` with `unavailable` means no copy of the model can take a session right now, for example while
>   a new copy is starting. Retry. Queries that don't use a session may still work meanwhile.


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