> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nokia.atlas.arenaphysica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Create and manage interactive AI conversation threads.

A session is an interactive conversation with Atlas for exploratory and open-ended analysis. Upload files into a session to give Atlas context.

## Endpoints

| Method   | Path                                                 | Description                         |
| -------- | ---------------------------------------------------- | ----------------------------------- |
| `POST`   | `/sessions`                                          | Create a session                    |
| `GET`    | `/sessions`                                          | List sessions                       |
| `GET`    | `/sessions/{session_id}`                             | Get a session                       |
| `PUT`    | `/sessions/{session_id}`                             | Update a session                    |
| `DELETE` | `/sessions/{session_id}`                             | Delete a session                    |
| `POST`   | `/sessions/{session_id}/upload-files`                | Upload files to a session           |
| `DELETE` | `/sessions/{session_id}/attachments/{attachment_id}` | Remove an attachment from a session |

***

## Create a session

`POST /sessions`

**Request body:**

| Field         | Required | Type   | Description                                             |
| ------------- | -------- | ------ | ------------------------------------------------------- |
| `title`       | No       | string | Session display name. Defaults to `"New Atlas session"` |
| `attachments` | No       | array  | List of `{attachment_id}` objects to pre-associate      |

**Example request:**

```bash theme={null}
curl -X POST "https://nokia.atlas.arenaphysica.com/api/v1/sessions" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Motor anomaly investigation"}'
```

**Response fields:**

| Field                 | Type    | Nullable | Description                                             |
| --------------------- | ------- | -------- | ------------------------------------------------------- |
| `session_id`          | UUID    | No       | Session identifier                                      |
| `session_title`       | string  | Yes      | Display name                                            |
| `session_description` | string  | Yes      | Session description                                     |
| `session_created_by`  | string  | No       | Creator email                                           |
| `session_created_at`  | string  | No       | ISO 8601 creation timestamp                             |
| `attachments`         | array   | No       | List of attachment objects associated with this session |
| `imported_projects`   | array   | No       | UUIDs of imported projects                              |
| `is_starred`          | boolean | No       | Whether the session is starred                          |
| `starred_at`          | string  | Yes      | ISO 8601 timestamp of when starred                      |

**Example response:**

```json theme={null}
{
  "session_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "session_title": "Motor anomaly investigation",
  "session_description": null,
  "session_created_by": "engineer@example.com",
  "session_created_at": "2026-04-13T10:20:00.000000",
  "attachments": [],
  "imported_projects": [],
  "is_starred": false,
  "starred_at": null
}
```

***

## List sessions

`GET /sessions`

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/sessions" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns `{"items": [...], "count": N}` where each item is a session object with the same fields as the [create response](#create-a-session) (except `attachments`, which is only included on the single-session GET).

***

## Get a session

`GET /sessions/{session_id}`

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns a single session object with the same fields as the [create response](#create-a-session).

***

## Update a session

`PUT /sessions/{session_id}`

All fields are optional.

| Field         | Type    | Description                       |
| ------------- | ------- | --------------------------------- |
| `title`       | string  | New display name                  |
| `description` | string  | Session description               |
| `starred`     | boolean | Set to `true` to star the session |

**Example request:**

```bash theme={null}
curl -X PUT "https://nokia.atlas.arenaphysica.com/api/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Motor anomaly – root cause confirmed", "starred": true}'
```

Returns the updated session object with the same fields as the [create response](#create-a-session).

***

## Delete a session

`DELETE /sessions/{session_id}`

**Example request:**

```bash theme={null}
curl -X DELETE "https://nokia.atlas.arenaphysica.com/api/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns **204 No Content**.

***

## Upload files

`POST /sessions/{session_id}/upload-files`

Upload one or more files as `multipart/form-data`. Each uploaded file becomes an attachment in the session.

**Form fields:**

| Field   | Required | Description                                                               |
| ------- | -------- | ------------------------------------------------------------------------- |
| `files` | Yes      | One or more file binaries (repeat the `files` field for multiple uploads) |

**Example request:**

```bash theme={null}
curl -X POST "https://nokia.atlas.arenaphysica.com/api/v1/sessions/$SESSION_ID/upload-files" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -F "files=@telemetry.bin" \
  -F "files=@config.json"
```

**Response fields (array):**

| Field                          | Type    | Nullable | Description                               |
| ------------------------------ | ------- | -------- | ----------------------------------------- |
| `attachment_id`                | UUID    | Yes      | Attachment identifier                     |
| `attachment_name`              | string  | No       | Original filename                         |
| `attachment_type`              | string  | No       | File type                                 |
| `attachment_title`             | string  | Yes      | Display title                             |
| `attachment_description`       | string  | Yes      | Description                               |
| `attachment_citation`          | string  | Yes      | Source citation                           |
| `attachment_source_session_id` | UUID    | Yes      | Session this attachment belongs to        |
| `attachment_created_by`        | string  | No       | Creator (email or `"atlas"`)              |
| `attachment_created_at`        | string  | No       | ISO 8601 creation timestamp               |
| `is_visible`                   | boolean | No       | Whether the attachment is shown in the UI |

**Example response:**

```json theme={null}
[
  {
    "attachment_id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
    "attachment_name": "telemetry.bin",
    "attachment_type": "bin",
    "attachment_title": null,
    "attachment_description": null,
    "attachment_citation": null,
    "attachment_source_session_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "attachment_created_by": "engineer@example.com",
    "attachment_created_at": "2026-04-13T10:21:00.000000",
    "is_visible": true
  }
]
```

Returns an array of attachment objects, one per uploaded file.

***

## Remove an attachment

`DELETE /sessions/{session_id}/attachments/{attachment_id}`

Removes an attachment from a session.

**Example request:**

```bash theme={null}
curl -X DELETE "https://nokia.atlas.arenaphysica.com/api/v1/sessions/$SESSION_ID/attachments/$ATTACHMENT_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns **204 No Content**.