API Reference

const res = await fetch('http://localhost:3000/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:3000/api/sessions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grade: 5,
    startedAt: '2025-05-03T14:12:00.000Z',
    baseUrl: 'http://localhost:3000',
    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:3000/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:3000/api/sessions/${id}`).then(r => r.json());

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

const id = 'a3f82c1d-9e4b-4f7a-b0c5-2d1e8f9a3c7b';
const res = await fetch(`http://localhost:3000/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:3000/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:3000/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:3000/api/review/edit?grade=5', {
  credentials: 'include'
});
const { editLog } = await res.json();

const res = await fetch('http://localhost:3000/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:3000/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:3000/api/manager/approvals', {
  credentials: 'include'
});
const { approvals } = await res.json();

const res = await fetch('http://localhost:3000/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:3000/api/admin/questions?grade=5', {
  credentials: 'include'
});
const questions = await res.json();  // Question[]

// Download for grade 5
const res = await fetch('http://localhost:3000/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:3000/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:3000/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:3000/api/admin/users', {
  credentials: 'include'
});
const users = await res.json();  // User[]

const email = 'teacher@school.com';
const res = await fetch(
  `http://localhost:3000/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:3000/api/admin/users/${encodeURIComponent(email)}`,
  { method: 'DELETE', credentials: 'include' }
);
const data = await res.json();  // { ok: true }

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

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

const res = await fetch('http://localhost:3000/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:3000/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:3000/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:3000/api/admin/review/log?grade=5', {
  credentials: 'include'
});
const { editLog } = await res.json();

const res = await fetch('http://localhost:3000/api/admin/test-templates', { credentials: 'include' });
const { templates } = await res.json();
// templates: Array<{
//   id, name, mode, grades, durationMinutes, createdAt, updatedAt, createdBy
// }>

// Adaptive template example
const res = await fetch('http://localhost:3000/api/admin/test-templates', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Grade 4 Mid-Year Adaptive',
    grades: [4],
    mode: 'adaptive',
    durationMinutes: 70,
    session1Targets:        { 1: 4, 2: 3, 3: 3, 4: 4, 5: 6 },
    session2TargetsByBand: {
      '90-100':   { 1: 0, 2: 0, 3: 4, 4: 6,  5: 10 },
      '80-90':    { 1: 0, 2: 0, 3: 6, 4: 6,  5: 8  },
      '70-80':    { 1: 0, 2: 0, 3: 7, 4: 7,  5: 6  },
      '60-70':    { 1: 0, 2: 4, 3: 6, 4: 6,  5: 4  },
      'below-60': { 1: 0, 2: 6, 3: 6, 4: 6,  5: 2  },
    },
  }),
});
const { template, shortfalls } = await res.json();
const shareLink = `${location.origin}/t/${template.id}`;

const res = await fetch('http://localhost:3000/api/admin/test-templates/8a1f3c2d-…', { credentials: 'include' });
const { template } = await res.json();

await fetch('http://localhost:3000/api/admin/test-templates/8a1f3c2d-…', {
  method: 'PUT',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Renamed Test',
    durationMinutes: 60,
    // ...any other TemplateConfig field
  }),
});

await fetch('http://localhost:3000/api/admin/test-templates/8a1f3c2d-…', {
  method: 'DELETE',
  credentials: 'include',
});

const res = await fetch(
  'http://localhost:3000/api/admin/test-templates/8a1f3c2d-…/generate',
  { method: 'POST', credentials: 'include' }
);
const { template, shortfalls } = await res.json();

// Session 1 swap candidates
const url = new URL('http://localhost:3000/api/admin/test-templates/8a1f3c2d-…/swap');
url.searchParams.set('bucket', 'session1');
url.searchParams.set('questionId', 'g3_293');
const { candidates } = await fetch(url, { credentials: 'include' }).then(r => r.json());

// Session 2 swap candidates (specify band)
url.searchParams.set('bucket', 'session2');
url.searchParams.set('band', '80-90');
url.searchParams.set('questionId', 'g3_141');

// Explicit replacement
await fetch('http://localhost:3000/api/admin/test-templates/8a1f3c2d-…/swap', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    bucket: { kind: 'session1' },           // or { kind: 'standard' }
                                            // or { kind: 'session2', band: '70-80' }
    questionId:    'g3_293',
    replacementId: 'g3_741',                // omit for random pick
  }),
});

const res = await fetch('http://localhost:3000/api/test-templates/8a1f3c2d-…');
const template = 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": { ... }
}