API Reference

const res = await fetch('http://localhost:3002/api/questions?grade=5');
const questions = await res.json();  // full Question[] for the grade (e.g. ~120 items)

// The adaptive engine then selects 10–40 of these client-side.
// You never need to call this per-question during the test.
console.log(`Loaded ${questions.length} questions for Grade 5`);

const res = await fetch('http://localhost:3002/api/sessions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grade: 5,
    startedAt: '2025-05-03T14:12:00.000Z',
    baseUrl: 'http://localhost:3002',
    webhookUrl: 'https://your-server.com/webhook',  // optional
    annotations: { studentId: 'S-1042' },           // optional
    result: {
      score: 620,
      correctAnswers: 15,
      totalQuestions: 20,
      timeTaken: 1143,
      topicBreakdown: [
        { topic: 'Fractions', correct: 7, total: 8, percentage: 88 }
      ],
      difficultyBreakdown: [
        { difficulty: 1, correct: 4, total: 4 },
        { difficulty: 2, correct: 5, total: 6 }
      ],
      answers: [
        { questionId: 'q_g5_001', selected: 'C', correct: 'C', isCorrect: true }
      ]
    }
  })
});
const data = await res.json();
// data.sessionId  → use to build report URL
// data.reportUrl  → redirect student here

const res = await fetch('http://localhost:3002/api/sessions', {
  credentials: 'include'   // sends the session cookie
});
const sessions = await res.json();

const id = 'a3f82c1d-9e4b-4f7a-b0c5-2d1e8f9a3c7b';

// Raw session
const raw = await fetch(`http://localhost:3002/api/sessions/${id}`).then(r => r.json());

// Webhook-shaped payload (same format POSTed to your webhook URL)
const payload = await fetch(`http://localhost:3002/api/sessions/${id}?payload=1`).then(r => r.json());

const id = 'a3f82c1d-9e4b-4f7a-b0c5-2d1e8f9a3c7b';
const res = await fetch(`http://localhost:3002/api/report/${id}/pdf`);
const blob = await res.blob();

// In browser — trigger download
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = `math-report-${id.slice(0,8)}.pdf`;
a.click();

const res = await fetch('http://localhost:3002/api/review/questions?grade=5', {
  credentials: 'include'
});
const { questions, reviews } = await res.json();

// questions → Question[]
// reviews   → Record<questionId, QuestionReview>

const res = await fetch('http://localhost:3002/api/review/submit', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    questionId: 'q_g5_001',
    grade: 5,
    status: 'approved',      // "approved" | "flagged" | "pending"
    note: 'Question is clear and answer is correct.'
  })
});
const data = await res.json();  // { ok: true }

const res = await fetch('http://localhost:3002/api/review/edit?grade=5', {
  credentials: 'include'
});
const { editLog } = await res.json();

const res = await fetch('http://localhost:3002/api/review/edit', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    questionId: 'q_g5_001',
    grade: 5,
    comment: 'Fixed typo in option C',
    updates: {
      // Only include fields you want to change
      question: 'What is 3/4 + 1/2?',
      answer: 'C',
      explanation: 'Convert 1/2 to 2/4: 3/4 + 2/4 = 5/4 = 1 1/4.',
      options: ['1', '5/4', '1 1/4', '7/4']
      // image, explanation can also be updated
    }
  })
});
const data = await res.json();  // { ok: true, editId: "edit_7f3a2b" }

const res = await fetch('http://localhost:3002/api/manager/stats', {
  credentials: 'include'
});
const { perGrade, totalQuestions, totalApproved,
        totalFlagged, totalPending, allowedGrades } = await res.json();
// allowedGrades: number[] for managers, null for admin (= all grades)

const res = await fetch('http://localhost:3002/api/manager/approvals', {
  credentials: 'include'
});
const { approvals } = await res.json();

const res = await fetch('http://localhost:3002/api/manager/approvals', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grade: 5,
    status: 'approved',                        // or "revision_requested"
    comment: 'All 120 questions reviewed.'     // optional
  })
});
const data = await res.json();  // { ok: true }

const res = await fetch('http://localhost:3002/api/admin/questions?grade=5', {
  credentials: 'include'
});
const questions = await res.json();  // Question[]

// Download for grade 5
const res = await fetch('http://localhost:3002/api/admin/export?grade=5', {
  credentials: 'include'
});
const blob = await res.blob();

// Trigger browser download
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'mathiq-questions-grade5.xlsx';
a.click();

// All grades
await fetch('http://localhost:3002/api/admin/export?grade=all', { credentials: 'include' });

const file = document.querySelector('input[type=file]').files[0];
const form = new FormData();
form.append('file', file);

const res = await fetch('http://localhost:3002/api/admin/import', {
  method: 'POST',
  credentials: 'include',
  body: form           // do NOT set Content-Type — browser adds multipart boundary
});
const { added, updated, errors } = await res.json();

const res = await fetch('http://localhost:3002/api/admin/users', {
  credentials: 'include'
});
const users = await res.json();  // User[]

const email = 'teacher@school.com';
const res = await fetch(
  `http://localhost:3002/api/admin/users/${encodeURIComponent(email)}`,
  {
    method: 'PATCH',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ role: 'manager' })
    // role: "student" | "reviewer" | "manager" | "admin"
  }
);
const user = await res.json();  // updated User object

const email = 'teacher@school.com';
const res = await fetch(
  `http://localhost:3002/api/admin/users/${encodeURIComponent(email)}`,
  { method: 'DELETE', credentials: 'include' }
);
const data = await res.json();  // { ok: true }

const res = await fetch('http://localhost:3002/api/admin/review/stats', {
  credentials: 'include'
});
const { perGrade, totalQuestions, totalApproved,
        totalFlagged, totalPending } = await res.json();

const res = await fetch('http://localhost:3002/api/admin/review/assignments', {
  credentials: 'include'
});
const { assignments, users } = await res.json();

const res = await fetch('http://localhost:3002/api/admin/review/assignments', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'teacher@school.com',
    name: 'Jane Smith',
    grades: [4, 5, 6]
  })
});
const data = await res.json();  // { ok: true }

const res = await fetch(
  `http://localhost:3002/api/admin/review/assignments/${encodeURIComponent('teacher@school.com')}`,
  { method: 'DELETE', credentials: 'include' }
);
const data = await res.json();  // { ok: true }

const res = await fetch('http://localhost:3002/api/admin/review/managers', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'manager@school.com',
    name: 'John Manager',
    grades: [4, 5, 6, 7, 8]
  })
});

const res = await fetch('http://localhost:3002/api/admin/review/log?grade=5', {
  credentials: 'include'
});
const { editLog } = await res.json();

// Called internally by ApiDataProvider — not from your frontend
GET https://your-api.example.com/v1/questions?grade=5
X-API-Key: your-secret-key

PUT https://your-api.example.com/v1/questions/override
X-API-Key: your-secret-key
Content-Type: application/json

{
  "id": "q_g5_001",
  "grade": 5,
  "topic": "Fractions",
  "answer": "C",
  ...full Question object...
}

POST https://your-api.example.com/v1/questions/import
X-API-Key: your-secret-key

{ "rows": [ /* Partial<Question>[] from the uploaded spreadsheet */ ] }

POST https://your-api.example.com/v1/users
X-API-Key: your-secret-key

{
  "email": "newuser@school.com",
  "name": "New User",
  "image": "https://lh3.googleusercontent.com/...",
  "role": "student"
}

// Update role
PATCH https://your-api.example.com/v1/users/teacher%40school.com
X-API-Key: your-secret-key

{ "role": "manager" }

// Or record last login
{ "lastLoginAt": "2025-05-03T14:00:00Z" }

PUT https://your-api.example.com/v1/sessions/a3f82c1d-...
X-API-Key: your-secret-key

{
  "sessionId": "a3f82c1d-9e4b-4f7a-b0c5-2d1e8f9a3c7b",
  "grade": 5,
  "timestamp": "2025-05-03T14:32:08.421Z",
  "startedAt": "2025-05-03T14:12:00.000Z",
  "completedAt": "2025-05-03T14:32:08.421Z",
  "webhookSent": false,
  "reportUrl": "https://app.example.com/report/a3f82c1d-...",
  "result": { ... }
}