Skip to main content

​
Overview

The AI Workspace API provides a general-purpose AI assistant for students to discuss study topics, get help with assignments, and organize their learning. Unlike the AI Tutor which focuses on conversational tutoring, the Workspace is designed for managing multiple study sessions and maintaining context across conversations.
All endpoints require authentication. Users must be logged in to access these APIs.

​
Chat

​
POST /api/ai-workspace/chat

Send a message to the AI workspace assistant and receive a response. Messages are automatically saved to the database along with the conversation history.
​
sessionId
string
required
The chat session ID to associate this message with
​
message
string
required
The user’s message or question
​
messages
array
Optional conversation history. Each message should have:
  • role: “user” or “assistant”
  • content: The message text
Request Example 
{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "What are the main themes in To Kill a Mockingbird?",
  "messages": [
    {
      "role": "user",
      "content": "I'm studying To Kill a Mockingbird for my English class"
    },
    {
      "role": "assistant",
      "content": "Great! To Kill a Mockingbird is a classic American novel. What would you like to know about it?"
    }
  ]
}
Response
​
response
string
The AI assistant’s response
Response Example 
{
  "response": "To Kill a Mockingbird explores several powerful themes:\n\n1. **Racial Injustice** - The trial of Tom Robinson highlights the deep-seated racism in the American South during the 1930s.\n\n2. **Moral Education** - Scout and Jem's coming-of-age journey as they learn about empathy and justice from their father, Atticus.\n\n3. **The Coexistence of Good and Evil** - The novel examines how people can be both good and bad, as seen through various characters.\n\nWould you like me to elaborate on any of these themes?"
}

​
Session Management

​
GET /api/ai-workspace/sessions

Retrieve all AI workspace chat sessions for the authenticated user, ordered by most recent activity. Query Parameters None required. Returns up to 50 most recent sessions. Response Returns an array of session objects:
​
id
string
Unique session identifier
​
session_name
string
Display name for the session
​
created_at
string
ISO 8601 timestamp when session was created
​
updated_at
string
ISO 8601 timestamp of last update
​
last_message_at
string
ISO 8601 timestamp of last message
​
message_count
number
Total number of messages in the session
Response Example 
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "session_name": "To Kill a Mockingbird Analysis",
    "created_at": "2026-03-05T14:30:00Z",
    "updated_at": "2026-03-07T10:15:00Z",
    "last_message_at": "2026-03-07T10:15:00Z",
    "message_count": 12
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "session_name": "Calculus Problem Set",
    "created_at": "2026-03-04T09:00:00Z",
    "updated_at": "2026-03-06T16:45:00Z",
    "last_message_at": "2026-03-06T16:45:00Z",
    "message_count": 8
  }
]

​
POST /api/ai-workspace/sessions

Create a new AI workspace chat session.
​
sessionName
string
Optional name for the session (defaults to “New Study Session”)
Request Example 
{
  "sessionName": "Chemistry Exam Review"
}
Response
​
id
string
The new session’s unique identifier
​
session_name
string
The session name
​
created_at
string
ISO 8601 timestamp
​
updated_at
string
ISO 8601 timestamp
​
last_message_at
string
ISO 8601 timestamp
Response Example 
{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "session_name": "Chemistry Exam Review",
  "created_at": "2026-03-07T11:30:00Z",
  "updated_at": "2026-03-07T11:30:00Z",
  "last_message_at": "2026-03-07T11:30:00Z"
}

​
Session Details

​
GET /api/ai-workspace/sessions/[id]

Retrieve a specific session and all its messages. Path Parameters
​
id
string
required
The session ID
Response
​
session
object
The session object with all metadata
​
messages
array
Array of message objects in chronological order
​
id
string
Message ID
​
role
string
Either “user” or “assistant”
​
content
string
The message text
​
created_at
string
ISO 8601 timestamp
Response Example 
{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "session_name": "To Kill a Mockingbird Analysis",
    "created_at": "2026-03-05T14:30:00Z",
    "updated_at": "2026-03-07T10:15:00Z",
    "last_message_at": "2026-03-07T10:15:00Z"
  },
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "I'm studying To Kill a Mockingbird for my English class",
      "created_at": "2026-03-05T14:30:00Z"
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "Great! To Kill a Mockingbird is a classic American novel. What would you like to know about it?",
      "created_at": "2026-03-05T14:30:15Z"
    }
  ]
}

​
PATCH /api/ai-workspace/sessions/[id]

Update a session’s name. Path Parameters
​
id
string
required
The session ID
Request Body
​
sessionName
string
required
The new session name
Request Example 
{
  "sessionName": "TKAM - Themes & Symbolism"
}
Response Returns the updated session object.

​
DELETE /api/ai-workspace/sessions/[id]

Delete a session and all its messages. Path Parameters
​
id
string
required
The session ID to delete
Response
​
success
boolean
Returns true if deletion was successful
Response Example 
{
  "success": true
}

​
System Prompt

The AI Workspace assistant uses the following system prompt to guide its behavior: 
You are an intelligent AI study assistant for Quizlix. Your role is to help students learn effectively by:

1. Explaining concepts clearly and concisely
2. Creating study materials (quizzes, flashcards, notes)
3. Answering questions with accurate information
4. Breaking down complex topics into manageable parts
5. Providing examples and analogies to aid understanding
6. Encouraging active learning and critical thinking

Keep responses focused, educational, and supportive. Use markdown formatting when appropriate.

​
Technical Details

The AI Workspace uses Groq’s LLaMA 3.3 70B Versatile model with the following parameters:
  • Temperature: 0.7
  • Max tokens: 2048

​
Message Persistence

All messages are automatically saved to the database:
  • User messages are saved before calling the AI
  • Assistant responses are saved after generation
  • The session’s last_message_at and updated_at timestamps are updated with each message

​
Conversation History

The chat endpoint accepts a messages array to maintain context. For best results:
  • Include the most recent 10-20 messages
  • Each message must have role and content fields
  • The system automatically appends the new message to the history

​
Error Responses

All endpoints return standard error responses: 
{
  "error": "Error message describing what went wrong"
}

​
Common Error Codes

Status CodeDescription
400Bad request - Missing required fields (sessionId, message, etc.)
401Unauthorized - User not authenticated
404Not found - Session doesn’t exist or doesn’t belong to user
500Internal server error - AI service error or database failure

​
Example Error Response

{
  "error": "Session ID and message are required"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us