Quizzes API

The Quizzes API allows users to generate AI-powered quizzes from course materials and notes, and manage quiz interactions. Quizzes are automatically created from your study content to help with assessment and learning.

Quiz Model

id: Unique quiz identifier (string)
title: Quiz title (string)
description: Quiz description (string, optional)
difficulty: Difficulty level (string: "EASY" | "MEDIUM" | "HARD")
courseId: Associated course ID (string)
createdAt: ISO datetime when created (string)
updatedAt: ISO datetime when last updated (string)
userId: Owner user ID (string)
questions: Array of question objects

Question Model

id: Unique question identifier (string)
question: Question text (string)
type: Question type (string: "multiple_choice" | "true_false" | "short_answer")
options: Array of answer options (for multiple choice questions)
correctAnswer: Correct answer (string)
explanation: Answer explanation (string, optional)
order: Display order in quiz (number)
quizId: Parent quiz ID (string)

Endpoints

All quiz endpoints require authentication and are scoped to the authenticated user.

Get All Quizzes

Retrieve all quizzes for the authenticated user with optional filtering.

GET /api/quizzes

# Filter by course
GET /api/quizzes?courseId=course_abc123

Query Parameters

courseId: Filter quizzes by specific course ID (optional)

Get Quizzes for Note

Retrieve all quizzes associated with a specific note.

GET /api/notes/{noteId}/quizzes

Path Parameters

noteId: ID of the note to get quizzes for (required, string)

Response (200)

{
  "success": true,
  "data": [
    {
      "id": "quiz_abc123",
      "title": "Biology Chapter 1 Quiz",
      "description": "Assessment on cell structure and function",
      "difficulty": "MEDIUM",
      "courseId": "course_abc123",
      "noteId": "note_abc123",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "userId": "user_123",
      "course": {
        "id": "course_abc123",
        "name": "Biology 101"
      },
      "note": {
        "id": "note_abc123",
        "title": "Biology Lecture: Cell Structure"
      },
      "questions": [
        {
          "id": "question_abc123",
          "question": "What is the basic unit of life?",
          "type": "multiple_choice",
          "options": ["Cell", "Tissue", "Organ", "Organism"],
          "correctAnswer": "Cell",
          "explanation": "The cell is the basic structural and functional unit of all living organisms.",
          "order": 1,
          "quizId": "quiz_abc123"
        }
      ]
    }
  ],
  "message": "Note quizzes retrieved successfully"
}

Errors:

401: Authentication required
404: Note not found or access denied

Generate Quiz with AI

Generate a new quiz using AI based on course materials and notes.

POST /api/quizzes/generate
Content-Type: application/json

{
  "courseId": "course_abc123",
  "noteIds": ["note_123", "note_456", "note_789"]
}

Request Body Parameters

courseId: ID of the course to generate the quiz for (required, string)
noteIds: Array of specific note IDs to use for quiz generation (required, array of strings)

Response (201)

{
  "success": true,
  "data": {
    "quiz": {
      "id": "quiz_abc123",
      "title": "Generated Quiz: Biology Fundamentals",
      "description": "AI-generated quiz from course notes",
      "difficulty": "MEDIUM",
      "courseId": "course_abc123",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "userId": "user_123"
    },
    "questions": [
      {
        "id": "question_abc123",
        "question": "What is the primary function of the nucleus?",
        "type": "multiple_choice",
        "options": ["Energy production", "Protein synthesis", "Controlling cell activities", "Waste removal"],
        "correctAnswer": "Controlling cell activities",
        "explanation": "The nucleus contains the cell's DNA and controls all cellular activities.",
        "order": 1,
        "quizId": "quiz_abc123"
      },
      {
        "id": "question_def456",
        "question": "Mitochondria are known as the powerhouse of the cell.",
        "type": "true_false",
        "options": ["True", "False"],
        "correctAnswer": "True",
        "explanation": "Mitochondria produce ATP, which provides energy for cellular processes.",
        "order": 2,
        "quizId": "quiz_abc123"
      }
    ]
  },
  "message": "Quiz generated successfully"
}

Errors:

400: Invalid input data, missing course, or invalid note IDs
401: Authentication required
404: Course or notes not found

Get Quiz by ID

Retrieve a specific quiz by its ID with all questions.

GET /api/quizzes/{id}

Path Parameters

id: ID of the quiz to retrieve (required, string)

Response (200)

{
  "success": true,
  "data": {
    "id": "quiz_abc123",
    "title": "Biology Chapter 1 Quiz",
    "description": "Assessment on cell structure and function",
    "difficulty": "MEDIUM",
    "courseId": "course_abc123",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "userId": "user_123",
    "questions": [
      {
        "id": "question_abc123",
        "question": "What is the basic unit of life?",
        "type": "multiple_choice",
        "options": ["Cell", "Tissue", "Organ", "Organism"],
        "correctAnswer": "Cell",
        "explanation": "The cell is the basic structural and functional unit of all living organisms.",
        "order": 1,
        "quizId": "quiz_abc123"
      }
    ]
  },
  "message": "Quiz retrieved successfully"
}

Errors:

401: Authentication required
404: Quiz not found

Validate Quiz Response

Validate and score a quiz response from a user.

POST /api/quizzes/validate
Content-Type: application/json

{
  "quizId": "quiz_abc123",
  "responses": [
    {
      "questionId": "question_abc123",
      "answer": "Cell"
    },
    {
      "questionId": "question_def456",
      "answer": "True"
    }
  ]
}

Request Body Parameters

quizId: ID of the quiz being validated (required, string)
responses: Array of user responses (required, array of objects)
- questionId: ID of the question (required, string)
- answer: User's answer (required, string)

Response (200)

{
  "success": true,
  "data": {
    "quizId": "quiz_abc123",
    "totalQuestions": 2,
    "correctAnswers": 2,
    "score": 100,
    "percentage": 100,
    "results": [
      {
        "questionId": "question_abc123",
        "userAnswer": "Cell",
        "correctAnswer": "Cell",
        "isCorrect": true,
        "explanation": "The cell is the basic structural and functional unit of all living organisms."
      },
      {
        "questionId": "question_def456",
        "userAnswer": "True",
        "correctAnswer": "True",
        "isCorrect": true,
        "explanation": "Mitochondria produce ATP, which provides energy for cellular processes."
      }
    ]
  },
  "message": "Quiz responses validated successfully"
}

Errors:

400: Invalid quiz ID or responses format
401: Authentication required
404: Quiz not found

Usage Examples

Generate Quiz from Notes

// Generate a quiz from specific notes in a course
const response = await fetch('/api/quizzes/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({
    courseId: 'course_abc123',
    noteIds: ['note_123', 'note_456']
  })
});

const result = await response.json();
console.log('Generated quiz:', result.data.quiz.id);
console.log('Number of questions:', result.data.questions.length);

Take and Validate Quiz

// Get quiz questions
const quizResponse = await fetch('/api/quizzes/quiz_abc123', {
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

const quiz = await quizResponse.json();

// Submit answers for validation
const answers = [
  { questionId: 'question_abc123', answer: 'Cell' },
  { questionId: 'question_def456', answer: 'True' }
];

const validateResponse = await fetch('/api/quizzes/validate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({
    quizId: 'quiz_abc123',
    responses: answers
  })
});

const results = await validateResponse.json();
console.log('Score:', results.data.percentage + '%');

Get All Quizzes for a Course

// Retrieve all quizzes for a specific course
const response = await fetch('/api/quizzes?courseId=course_abc123', {
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

const data = await response.json();
console.log('Course quizzes:', data.data.length);

AI Generation Features

Question Types

Multiple Choice: 4-option questions with single correct answer
True/False: Binary choice questions with explanations
Short Answer: Open-ended questions (future feature)

Content Analysis

Key Concept Extraction: Identifies important topics from notes
Question Difficulty: Automatically adjusts complexity based on content
Answer Validation: Ensures questions have clear, correct answers
Explanation Generation: Provides educational explanations for answers

Quality Assurance

Relevance Scoring: Questions directly relate to source material
Clarity Optimization: Questions are unambiguous and well-formed
Duplicate Prevention: Avoids similar or redundant questions
Educational Value: Focuses on learning objectives and key concepts

Integration Notes

Quizzes are automatically organized by course
Generated questions include educational explanations
Quiz data integrates with the universal search system
AI generation respects course context and difficulty level
All quiz operations are scoped to the authenticated user
Validation results can be used for progress tracking

Quizzes API

On this page