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:

sessions · array

Array of chat session objects

id · string

Unique session identifier (UUID)

title · string

Session title (auto-generated from first message or custom)

created_at · string

ISO 8601 timestamp of session creation

updated_at · string

ISO 8601 timestamp of last update

message_count · number

Number of messages in the session

ui_state · object

UI preferences for the session (model, mode, providers)

status · string

Session status: active, completed, or cancelled

Example Response:

{
  "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:

title · string

Custom session title. If not provided, auto-generated from first message (max 50 chars)

messages · array · default: "[]"

Initial messages for the session (usually empty for new sessions)

ui_state · object · default: "{}"

UI state including model, mode, and provider preferences

Example Request:

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

Response:

id · string

Unique session identifier

title · string

Session title

messages · array

Session messages

ui_state · object

UI state object

created_at · string

ISO 8601 creation timestamp

updated_at · string

ISO 8601 update timestamp

status · string

Session status (always “active” for new sessions)

---

GET /chat_api/sessions/:session_id

Retrieve a specific chat session with full message history.

Authentication: Required (X-User-ID header)

Parameters:

session_id · string · required

UUID of the session to retrieve

Response:

Same fields as POST response, plus:

messages · array

Full array of message objects

sender · string

Message sender: user or assistant

text · string

Message text content

images · array

Attached images (for multimodal messages)

displayData · string

Data URL for image display

type · string

MIME type (e.g., “image/png”)

data · string

Base64-encoded image data

name · string

Image filename

Example Response:

{
  "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:

session_id · string · required

UUID of the session to update

Request Body:

title · string

Updated session title

messages · array

Updated messages array

ui_state · object

Updated UI state

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:

session_id · string · required

UUID of the session to delete

Response:

{
  "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:

current_session_id · string

Session ID to preserve from deletion

Response:

{
  "message": "Successfully deleted 15 chat sessions (preserved current session)"
}

Example:

DELETE /chat_api/sessions/bulk-delete?current_session_id=550e8400-e29b-41d4-a716-446655440000

Error Responses

error · string

Error message describing what went wrong

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