> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Sessions

> Manage chat sessions with the Aurora API

# Chat Sessions

Chat sessions store conversation history and state for Aurora's AI agent. Each session maintains messages, UI state, and metadata.

## Endpoints

### GET /chat\_api/sessions

Retrieve all chat sessions for the authenticated user.

**Authentication:** Required (X-User-ID header)

**Response:**

<ResponseField name="sessions" type="array">
  Array of chat session objects

  <ResponseField name="id" type="string">
    Unique session identifier (UUID)
  </ResponseField>

  <ResponseField name="title" type="string">
    Session title (auto-generated from first message or custom)
  </ResponseField>

  <ResponseField name="created_at" type="string">
    ISO 8601 timestamp of session creation
  </ResponseField>

  <ResponseField name="updated_at" type="string">
    ISO 8601 timestamp of last update
  </ResponseField>

  <ResponseField name="message_count" type="number">
    Number of messages in the session
  </ResponseField>

  <ResponseField name="ui_state" type="object">
    UI preferences for the session (model, mode, providers)
  </ResponseField>

  <ResponseField name="status" type="string">
    Session status: `active`, `completed`, or `cancelled`
  </ResponseField>
</ResponseField>

**Example Response:**

```json theme={null}
{
  "sessions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Deploy Kubernetes cluster",
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T10:45:00Z",
      "message_count": 12,
      "ui_state": {
        "selectedModel": "gpt-4",
        "selectedMode": "agent",
        "selectedProviders": ["gcp", "aws"]
      },
      "status": "active"
    }
  ]
}
```

***

### POST /chat\_api/sessions

Create a new chat session.

**Authentication:** Required (X-User-ID header)

**Request Body:**

<ParamField path="title" type="string" optional>
  Custom session title. If not provided, auto-generated from first message (max 50 chars)
</ParamField>

<ParamField path="messages" type="array" default="[]">
  Initial messages for the session (usually empty for new sessions)
</ParamField>

<ParamField path="ui_state" type="object" default="{}">
  UI state including model, mode, and provider preferences
</ParamField>

**Example Request:**

```json theme={null}
{
  "title": "Infrastructure Setup",
  "messages": [],
  "ui_state": {
    "selectedModel": "gpt-4",
    "selectedMode": "agent",
    "selectedProviders": ["gcp"]
  }
}
```

**Response:**

<ResponseField name="id" type="string">
  Unique session identifier
</ResponseField>

<ResponseField name="title" type="string">
  Session title
</ResponseField>

<ResponseField name="messages" type="array">
  Session messages
</ResponseField>

<ResponseField name="ui_state" type="object">
  UI state object
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 update timestamp
</ResponseField>

<ResponseField name="status" type="string">
  Session status (always "active" for new sessions)
</ResponseField>

***

### GET /chat\_api/sessions/:session\_id

Retrieve a specific chat session with full message history.

**Authentication:** Required (X-User-ID header)

**Parameters:**

<ParamField path="session_id" type="string" required>
  UUID of the session to retrieve
</ParamField>

**Response:**

Same fields as POST response, plus:

<ResponseField name="messages" type="array">
  Full array of message objects

  <ResponseField name="sender" type="string">
    Message sender: `user` or `assistant`
  </ResponseField>

  <ResponseField name="text" type="string">
    Message text content
  </ResponseField>

  <ResponseField name="images" type="array" optional>
    Attached images (for multimodal messages)

    <ResponseField name="displayData" type="string">
      Data URL for image display
    </ResponseField>

    <ResponseField name="type" type="string">
      MIME type (e.g., "image/png")
    </ResponseField>

    <ResponseField name="data" type="string">
      Base64-encoded image data
    </ResponseField>

    <ResponseField name="name" type="string">
      Image filename
    </ResponseField>
  </ResponseField>
</ResponseField>

**Example Response:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Deploy Kubernetes cluster",
  "messages": [
    {
      "sender": "user",
      "text": "Create a GKE cluster in us-central1"
    },
    {
      "sender": "assistant",
      "text": "I'll create a GKE cluster for you..."
    }
  ],
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": "2024-03-15T10:45:00Z",
  "ui_state": {...},
  "status": "active"
}
```

***

### PUT /chat\_api/sessions/:session\_id

Update an existing chat session.

**Authentication:** Required (X-User-ID header)

**Parameters:**

<ParamField path="session_id" type="string" required>
  UUID of the session to update
</ParamField>

**Request Body:**

<ParamField path="title" type="string" optional>
  Updated session title
</ParamField>

<ParamField path="messages" type="array" optional>
  Updated messages array
</ParamField>

<ParamField path="ui_state" type="object" optional>
  Updated UI state
</ParamField>

**Behavior:**

* Only provided fields are updated
* Cannot update `cancelled` or `completed` sessions
* Title auto-generates from messages if not provided and current title is "New Chat"
* `updated_at` is automatically set to current timestamp

**Response:**

Updated session object with same structure as GET response.

***

### DELETE /chat\_api/sessions/:session\_id

Delete a chat session (soft delete).

**Authentication:** Required (X-User-ID header)

**Parameters:**

<ParamField path="session_id" type="string" required>
  UUID of the session to delete
</ParamField>

**Response:**

```json theme={null}
{
  "message": "Chat session deleted successfully"
}
```

**Notes:**

* Sessions are soft-deleted (marked as inactive, not removed from database)
* Associated storage files (Terraform state, etc.) are also deleted
* Deleted sessions cannot be recovered

***

### DELETE /chat\_api/sessions/bulk-delete

Delete all chat sessions for a user, optionally preserving the current session.

**Authentication:** Required (X-User-ID header)

**Query Parameters:**

<ParamField query="current_session_id" type="string" optional>
  Session ID to preserve from deletion
</ParamField>

**Response:**

```json theme={null}
{
  "message": "Successfully deleted 15 chat sessions (preserved current session)"
}
```

**Example:**

```bash theme={null}
DELETE /chat_api/sessions/bulk-delete?current_session_id=550e8400-e29b-41d4-a716-446655440000
```

## Error Responses

<ResponseField name="error" type="string">
  Error message describing what went wrong
</ResponseField>

**Common Error Codes:**

* `401 Unauthorized` - Missing or invalid authentication
* `403 Forbidden` - Cannot update cancelled/completed session
* `404 Not Found` - Session not found
* `500 Internal Server Error` - Server error

## Session Lifecycle

1. **Created** - New session with `status: "active"`
2. **Updated** - Messages added/modified via PUT requests
3. **Completed** - Agent workflow finishes successfully
4. **Cancelled** - User cancels ongoing workflow
5. **Deleted** - Soft-deleted by user (marked inactive)

## Best Practices

* Always check `status` before updating sessions
* Use `bulk-delete` with `current_session_id` to clear history while preserving active chat
* Store `session_id` on the client to maintain conversation continuity
* Title auto-generation uses first 50 characters of first user message
* Sessions automatically update `updated_at` on any modification