Skip to main content

​
Overview

The AI Tutor API provides conversational tutoring capabilities and generates various types of study materials including quizzes, flashcards, summaries, and practice questions.

​
Chat with AI Tutor

The AI Tutor uses Groq’s LLaMA 3.3 70B model for conversational responses.

​
POST /api/ai-tutor/chat

Send a message to the AI tutor and receive an intelligent response. The tutor can explain concepts, answer questions, and generate study materials.
​
sessionId
string
The chat session ID (optional)
​
message
string
required
The user’s message or question
​
messages
array
Conversation history array. Each message should have role (user/assistant) and content fields.
​
generateContent
boolean
Set to true to enable automatic generation of study materials (quizzes, flashcards, etc.)
​
firstName
string
User’s first name for personalized responses
Request Example 
{
  "sessionId": "abc123",
  "message": "Can you create a quiz about photosynthesis?",
  "messages": [
    {
      "role": "user",
      "content": "Hi, I need help studying biology"
    },
    {
      "role": "assistant",
      "content": "Hi! I'd be happy to help you with biology. What topic would you like to study?"
    }
  ],
  "generateContent": true,
  "firstName": "Sarah"
}
Response
​
message
string
The AI tutor’s response message
​
response
string
Same as message (for backwards compatibility)
​
generatedContent
object
Generated study material (quiz, flashcards, etc.) if requested
​
contentMetadata
object
Metadata about the generated content
​
type
string
Content type: quiz, flashcards, writing-prompts, etc.
​
topic
string
The detected or extracted topic
​
hasMaterialToGenerate
boolean
Whether study material was successfully generated
Response Example 
{
  "message": "I've created a quiz about photosynthesis! The interactive quiz will open now. Good luck!",
  "response": "I've created a quiz about photosynthesis! The interactive quiz will open now. Good luck!",
  "generatedContent": {
    "type": "quiz",
    "title": "photosynthesis",
    "questions": [
      {
        "question": "What is the primary function of chlorophyll in photosynthesis?",
        "options": [
          "Absorb light energy",
          "Store glucose",
          "Release oxygen",
          "Break down water"
        ],
        "correctIndex": 0,
        "explanation": "Chlorophyll absorbs light energy from the sun, which is essential for the photosynthesis process."
      }
    ]
  },
  "contentMetadata": {
    "type": "quiz",
    "topic": "photosynthesis",
    "hasMaterialToGenerate": true
  }
}

​
Session Management

​
GET /api/ai-tutor/sessions

Retrieve all AI tutor chat sessions for the authenticated user. Response
​
sessions
array
Array of session objects
​
id
string
Session ID
​
session_name
string
Display name for the session
​
created_at
string
ISO 8601 timestamp
​
last_message_at
string
ISO 8601 timestamp of last message
Response Example 
{
  "sessions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "session_name": "Photosynthesis Study",
      "created_at": "2026-03-07T10:30:00Z",
      "last_message_at": "2026-03-07T11:15:00Z"
    }
  ]
}

​
POST /api/ai-tutor/sessions

Create a new AI tutor chat session.
​
sessionName
string
Name for the new session (defaults to “New Chat”)
Request Example 
{
  "sessionName": "Biology Exam Prep"
}
Response
​
session
object
The created session object with id, session_name, created_at, and last_message_at

​
Session Messages

​
GET /api/ai-tutor/sessions/[sessionId]/messages

Retrieve all messages in a specific chat session. Path Parameters
​
sessionId
string
required
The session ID
Response
​
messages
array
Array of message objects
​
id
string
Message ID
​
role
string
Either “user” or “assistant”
​
content
string
Message content
​
timestamp
string
ISO 8601 timestamp

​
Generate Study Materials

​
POST /api/ai-tutor/generate

Generate specific types of study materials on demand.
​
type
string
required
Type of content to generate: quiz, flashcards, summary, or practice
​
topic
string
required
The topic for the study material
​
sessionId
string
Optional session ID to associate the content with
Request Example 
{
  "type": "flashcards",
  "topic": "World War II",
  "sessionId": "abc123"
}
Response
​
content
object|array
The generated content structure varies by type:
  • quiz: Array of question objects
  • flashcards: Array of card objects with front/back
  • summary: Text content with markdown formatting
  • practice: Text content with practice questions

​
Analyze Quiz Results

​
POST /api/ai-tutor/analyze-quiz-results

Get personalized feedback and explanations for quiz results.
​
quizTitle
string
required
The title of the completed quiz
​
score
number
required
The score as a percentage (0-100)
​
breakdown
string
required
JSON string containing question-by-question breakdown with:
  • question: The question text
  • userAnswer: The student’s answer
  • correctAnswer: The correct answer
  • isCorrect: Boolean indicating if answer was correct
​
firstName
string
Student’s first name for personalized feedback
Request Example 
{
  "quizTitle": "Photosynthesis Quiz",
  "score": 80,
  "breakdown": "[{\"question\":\"What is the primary function of chlorophyll?\",\"userAnswer\":\"Absorb light energy\",\"correctAnswer\":\"Absorb light energy\",\"isCorrect\":true}]",
  "firstName": "Sarah"
}
Response
​
analysis
string
Personalized feedback and explanations from the AI tutor
Response Example 
{
  "analysis": "Great job, Sarah! You scored 80% on the Photosynthesis Quiz. Let's review your answers...\n\nFor the questions you got right, you clearly understand the role of chlorophyll...\n\nDo you have any questions about photosynthesis?"
}

​
Detect Topic from Conversation

​
POST /api/ai-tutor/detect-topic

Analyze a conversation to detect the main study topic and validate if there’s sufficient information to create study materials.
​
messages
array
required
Array of conversation messages with role and content fields
​
type
string
Optional content type being requested
Request Example 
{
  "messages": [
    {
      "role": "user",
      "content": "I need help understanding how plants make food"
    },
    {
      "role": "assistant",
      "content": "I'd be happy to help you understand photosynthesis!"
    }
  ]
}
Response
​
topic
string
The detected topic (null if insufficient information)
​
sufficient
boolean
Whether there’s enough context to create study materials
​
legitimate
boolean
Whether the detected topic is a real educational subject
​
type
string
The content type (if provided in request)
Response Example 
{
  "topic": "Photosynthesis",
  "sufficient": true,
  "legitimate": true,
  "type": null
}

​
Generate Session Name

​
POST /api/ai-tutor/generate-session-name

Generate a short, descriptive name for a chat session based on the first message.
​
message
string
required
The first message in the session
Request Example 
{
  "message": "Can you help me understand DNA replication?"
}
Response
​
sessionName
string
A 2-4 word session title
Response Example 
{
  "sessionName": "DNA Replication"
}

​
Error Responses

All endpoints return standard error responses: 
{
  "error": "Error message describing what went wrong"
}
Common error status codes:
  • 400 - Bad request (missing or invalid parameters)
  • 401 - Unauthorized (authentication required)
  • 500 - Internal server error

Build docs developers (and LLMs) love

Get started for freeTalk to us