Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us