API Reference
SA3 exposes 66 API route files across 8 domains. All routes are Next.js App Router API routes under src/app/api/.
info
The /api/admin/ prefix is a naming artifact from early development. It does not act as a permission gate. All handlers enforce access via resolvePermissionsForResource for data-level access control.
Authentication
POST /api/auth/[...nextauth] -- next-auth v4 endpoints (sign in, sign out, session, CSRF)
Academic Systems (12 routes)
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /api/admin/academic-systems | List / create |
| GET, PATCH, DELETE | /api/admin/academic-systems/[id] | Detail / update / delete |
| GET, POST | /api/admin/academic-systems/[id]/sections | Sections |
| GET, PATCH, DELETE | /api/admin/academic-systems/[id]/sections/[sectionId] | Section CRUD |
| GET, POST | /api/admin/academic-systems/[id]/sections/[sectionId]/year-groups | Year groups |
| GET, PATCH, DELETE | /api/admin/academic-systems/[id]/sections/[sectionId]/year-groups/[ygId] | Year group CRUD |
| GET, POST | /api/admin/academic-systems/[id]/grade-scales | Grade scales |
| GET, PATCH, DELETE | /api/admin/academic-systems/[id]/grade-scales/[scaleId] | Grade scale CRUD |
| GET | /api/admin/academic-systems/[id]/grade-scales/[scaleId]/boundaries | Boundaries |
| GET, POST | /api/admin/academic-systems/[id]/assessment-types | Assessment types |
| GET, PATCH, DELETE | /api/admin/academic-systems/[id]/assessment-types/[typeId] | Type CRUD |
| GET, PUT | /api/admin/academic-systems/[id]/weighting-rules | Weighting rules |
Academic Years (4 routes)
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /api/admin/academic-years | List / create |
| GET, PATCH, DELETE | /api/admin/academic-years/[id] | Detail / update / delete |
| GET, POST | /api/admin/academic-years/[id]/periods | Periods |
| GET, PATCH, DELETE | /api/admin/academic-years/[id]/periods/[periodId] | Period CRUD |
Subjects (5 routes)
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /api/admin/subjects | List / create |
| GET, PATCH, DELETE | /api/admin/subjects/[id] | Detail / update / delete |
| GET, POST | /api/admin/subjects/[id]/documents | Documents |
| GET, DELETE | /api/admin/subjects/[id]/documents/[docId] | Document CRUD |
| GET | /api/admin/subjects/[id]/documents/[docId]/download-url | Presigned download |
Staff (6 routes)
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /api/admin/staff | List / create |
| GET, PATCH, DELETE | /api/admin/staff/[id] | Detail / update / soft delete |
| POST | /api/admin/staff/[id]/roles | Assign role |
| DELETE | /api/admin/staff/[id]/roles/[staffRoleId] | Revoke role (sets revokedAt) |
| POST | /api/admin/staff/[id]/departments | Assign department |
| DELETE | /api/admin/staff/[id]/departments/[departmentId] | Remove department |
Roles & Departments (4 routes)
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /api/admin/roles | List / create |
| GET, PATCH, DELETE | /api/admin/roles/[id] | Role CRUD |
| GET, POST | /api/admin/departments | List / create |
| PATCH, DELETE | /api/admin/departments/[id] | Department CRUD |
Students (4 routes)
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /api/admin/students | List / create (PII encrypted) |
| GET, PATCH, DELETE | /api/admin/students/[id] | Detail / update / soft delete |
| POST | /api/admin/students/[id]/photo | Presigned PUT URL for upload |
| GET | /api/admin/students/[id]/photo | Presigned GET URL for download |
Classes (11 routes)
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /api/admin/classes | List / create |
| GET, PATCH, DELETE | /api/admin/classes/[id] | Detail / update / archive |
| GET, POST | /api/admin/classes/[id]/students | Enroll students |
| DELETE | /api/admin/classes/[id]/students/[studentId] | Unenrol |
| GET, POST | /api/admin/classes/[id]/teachers | Assign teachers |
| DELETE | /api/admin/classes/[id]/teachers/[staffId] | Remove teacher |
| GET, POST | /api/admin/classes/[id]/subjects | Add subjects |
| PATCH, DELETE | /api/admin/classes/[id]/subjects/[csId] | Update / remove subject |
| GET, POST | /api/admin/classes/[id]/materials | Upload materials |
| DELETE | /api/admin/classes/[id]/materials/[materialId] | Remove material |
| GET | /api/admin/classes/[id]/materials/[materialId]/download-url | Download URL |
Assessments (8 routes)
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /api/admin/assessments | List / create |
| GET, PATCH, DELETE | /api/admin/assessments/[id] | CRUD + status transitions |
| POST | /api/admin/assessments/[id]/document | Upload document |
| POST | /api/admin/assessments/[id]/marking-scheme | Upload marking scheme |
| POST | /api/admin/assessments/[id]/rubric | Upload rubric |
| GET | /api/admin/assessments/[id]/scores | List scores |
| PUT | /api/admin/assessments/[id]/scores/[studentId] | Enter/update score |
| POST | /api/admin/assessments/[id]/sync-scores | Offline batch sync |
Reports (6 routes)
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /api/admin/report-groups | List / create |
| GET, PATCH | /api/admin/report-groups/[id] | Detail / update |
| POST | /api/admin/report-groups/[id]/finalize | Finalize report group |
| POST | /api/admin/report-groups/[id]/generate | Trigger PDF generation |
| GET | /api/admin/report-groups/[id]/preview/[studentId] | Preview single report |
| GET, PUT | /api/admin/teacher-remarks | List / upsert remarks |
Dashboard (6 routes)
| Method | Path | Purpose |
|---|---|---|
| GET | /api/dashboard/class-performance | Class performance by subject |
| GET | /api/dashboard/student-progress | Student score trends |
| GET | /api/dashboard/completion-rate | Score entry completion |
| GET | /api/dashboard/grade-distribution | Grade distribution |
| GET | /api/dashboard/staff-workload | Staff workload |
| GET | /api/admin/dashboard/grade-distribution | Admin-scoped grades |