creat-batches.md

Create Quiz Batches API – README

This endpoint allows you to create multiple batches of quiz questions for a specific module in a single request. Each batch can contain its own set of questions and difficulty level, along with global quiz settings.

---

Endpoint

POST https://app.realxeducation.io/api/quiz/create-batches

---

Purpose

Use this endpoint to:

• Create multiple quiz batches at once
• Associate all batches with a single module
• Define quiz settings (time limits, shuffling, max students, etc.)
• Track batch creation via returned batch IDs

---

Input Interface

export interface CreateQuizBatchesInput {
  moduleId: string;
  bookerId: string;
  bookerName: string;
  bookerEmail?: string;
  deliverer: string;
  moduleName: string;
  batches: {
    batchNumber: number;
    questions: QuizQuestion[];
    difficulty?: string;
  }[];
  settings?: {
    allowRetakes?: boolean;
    passingScore?: number;
    timeLimit?: number;
    shuffleQuestions?: boolean;
    shuffleOptions?: boolean;
    maxStudents?: number; // default: 10
  };
}

---

Required Notes ⚠️

• moduleId must be "10"
• bookerId must be "1"
• batchNumber must be unique per batch
• Each batch must include at least one question

---

Quiz Question Structure

Each question inside a batch must follow this structure:

QuizQuestion {
  id: string;
  question_text: string;
  options: {
    id: string;
    label: string;
    text: string;
  }[];
  correct_options: string[];
  explanation?: string;
  difficulty?: "easy" | "medium" | "hard";
  source_fact_id?: string;
}

---

Example Request Payload

{
  "moduleId": "10",
  "bookerId": "1",
  "bookerName": "Izaak",
  "deliverer": "1exisLyxm7JNVbAga7JLzA4WdGdWRVbWtgA6FmimsShdiDB",
  "moduleName": "Privacy, Surveillance & Digital Control",
  "settings": {
    "shuffleQuestions": true,
    "shuffleOptions": true,
    "timeLimit": 300, // 5min should be in seconds 
    "maxStudents": 10
  },
  "batches": [
    {
      "batchNumber": 1,
      "difficulty": "easy",
      "questions": [
        {
          "id": "a1c2b3f0-1f6c-4f39-9e94-2a5c7b8d9e01",
          "question_text": "What is the main concern discussed regarding the future of privacy in a digitally controlled world?",
          "options": [
            { "id": "o1", "label": "A", "text": "Lack of internet access" },
            { "id": "o2", "label": "B", "text": "Increasing government and corporate surveillance" },
            { "id": "o3", "label": "C", "text": "Slow financial transactions" },
            { "id": "o4", "label": "D", "text": "Outdated banking systems" }
          ],
          "correct_options": ["o2"],
          "explanation": "The content emphasizes growing government and corporate surveillance as the main privacy concern.",
          "difficulty": "easy",
          "source_fact_id": "slide-1-introduction"
        }
      ]
    }
  ]
}

---

Example Success Response

{
  "success": true,
  "message": "Quiz batches created successfully",
  "data": {
    "moduleId": "10",
    "bookerId": "1",
    "totalBatches": 5,
    "totalQuestions": 25,
    "batchIds": [
      "1770036724594-ui8cdhwxy",
      "1770036724594-h6gg07r0g",
      "1770036724594-jfoyzsch5",
      "1770036724594-8eyute43b",
      "1770036724594-k4ub65qsq"
    ],
    "metadata": {
      "allowRetakes": true,
      "timeLimit": "7",
      "maxStudents": 10
    }
  }
}

---

Response Fields Explained

Field	Description
totalBatches	Number of batches created
totalQuestions	Total questions across all batches
batchIds	Unique IDs for each created batch
metadata	Applied quiz settings

---

Common Validation Errors

• Missing moduleId or bookerId
• Invalid question structure
• Empty batches array
• Duplicate batchNumber values

---

Best Practices 💡

• Keep batch sizes consistent (e.g. 5 questions per batch)
• Use mixed difficulty levels across batches
• Enable shuffleQuestions and shuffleOptions for fairness
• Use source_fact_id for traceability to learning material

---

If you want, I can also:

• Add error response examples
• Convert this into Swagger / OpenAPI
• Create a Postman collection
• Validate your payload automatically before sending

Just say the word.