# API Reference: Sessions

## POST `/sessions/`

**Summary:** Create a New Chat Session

**Description:** Create a New Chat Session

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `SessionCreate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/sessions/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## GET `/sessions/`

**Summary:** Get All Chat Sessions

**Description:** Get All Chat Sessions

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `user_id` | query | Yes | string |  |
| `feature_name` | query | No | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/sessions/?user_id=<user_id>&feature_name=<feature_name>' \
  -H 'accept: application/json'
```

---

## DELETE `/sessions/`

**Summary:** Delete All Sessions for Feature

**Description:** Delete All Sessions for Feature

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `user_id` | query | Yes | string |  |
| `feature_name` | query | No | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'DELETE' \
  'http://localhost:8000/api/v1/sessions/?user_id=<user_id>&feature_name=<feature_name>' \
  -H 'accept: application/json'
```

---

## POST `/sessions/{session_id}/chat`

**Summary:** Send a Message in a Session (Streaming)

**Description:** Streams AI response using Server-Sent Events (SSE).
Yields tokens, reasoning, and tool executions in real-time.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `session_id` | path | Yes | integer |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `ChatRequest` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/sessions/{session_id}/chat' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## GET `/sessions/{session_id}/messages`

**Summary:** Get Session Chat History

**Description:** Get Session Chat History

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `session_id` | path | Yes | integer |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/sessions/{session_id}/messages' \
  -H 'accept: application/json'
```

---

## POST `/sessions/{session_id}/clear-history`

**Summary:** Clear Chat History (Preserve Session)

**Description:** Deletes all messages for a session but preserves the session itself
(node attachments, workspace ID, sync config, title all remain intact).
Useful in Swarm Control to start a fresh chat without losing the file sync workspace.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `session_id` | path | Yes | integer |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/sessions/{session_id}/clear-history' \
  -H 'accept: application/json'
```

---

## GET `/sessions/{session_id}/tokens`

**Summary:** Get Session Token Usage

**Description:** Get Session Token Usage

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `session_id` | path | Yes | integer |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/sessions/{session_id}/tokens' \
  -H 'accept: application/json'
```

---

## GET `/sessions/{session_id}`

**Summary:** Get a Single Session

**Description:** Get a Single Session

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `session_id` | path | Yes | integer |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/sessions/{session_id}' \
  -H 'accept: application/json'
```

---

## PATCH `/sessions/{session_id}`

**Summary:** Update a Chat Session

**Description:** Update a Chat Session

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `session_id` | path | Yes | integer |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `SessionUpdate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'PATCH' \
  'http://localhost:8000/api/v1/sessions/{session_id}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## DELETE `/sessions/{session_id}`

**Summary:** Delete a Chat Session

**Description:** Delete a Chat Session

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `session_id` | path | Yes | integer |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'DELETE' \
  'http://localhost:8000/api/v1/sessions/{session_id}' \
  -H 'accept: application/json'
```

---

## POST `/sessions/messages/{message_id}/audio`

**Summary:** Upload audio for a specific message

**Description:** Upload audio for a specific message

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `message_id` | path | Yes | integer |  |

#### Request Body

**Required:** Yes

- **Media Type:** `multipart/form-data`
- **Schema:** `Body_upload_message_audio_sessions_messages__message_id__audio_post` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/sessions/messages/{message_id}/audio' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/file'
```

---

## GET `/sessions/messages/{message_id}/audio`

**Summary:** Get audio for a specific message

**Description:** Get audio for a specific message

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `message_id` | path | Yes | integer |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/sessions/messages/{message_id}/audio' \
  -H 'accept: application/json'
```

---

## POST `/sessions/{session_id}/nodes`

**Summary:** Attach Nodes to Session

**Description:** Attach one or more Agent Nodes to a chat session.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `session_id` | path | Yes | integer |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `NodeAttachRequest` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/sessions/{session_id}/nodes' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## GET `/sessions/{session_id}/nodes`

**Summary:** Get Session Node Status

**Description:** Returns all nodes attached to a session and their current sync status.
Merges persisted sync_status with live connection state from the registry.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `session_id` | path | Yes | integer |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/sessions/{session_id}/nodes' \
  -H 'accept: application/json'
```

---

## DELETE `/sessions/{session_id}/nodes/{node_id}`

**Summary:** Detach Node from Session

**Description:** Detach Node from Session

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `session_id` | path | Yes | integer |  |
| `node_id` | path | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'DELETE' \
  'http://localhost:8000/api/v1/sessions/{session_id}/nodes/{node_id}' \
  -H 'accept: application/json'
```

---

## POST `/sessions/{session_id}/cancel`

**Summary:** Cancel Running AI Task

**Description:** Cancel Running AI Task

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `session_id` | path | Yes | integer |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/sessions/{session_id}/cancel' \
  -H 'accept: application/json'
```

---

