Academics API — Classes, Exams, Scores, and Tahfeez

The Academics module is the academic backbone of the Gobarau Academy platform. It covers the complete lifecycle of learning — from creating class instances and assigning teachers to subjects, through scheduling timetables and recording daily attendance, all the way to scoring assessments, generating termly report cards, and managing exam registrations. Uniquely, the module also includes a dedicated Tahfeez sub-system for tracking each student’s Qur’an memorization progress juz by juz, with recitation session records supervised by a teacher. All endpoints are prefixed with /api/academics/ and follow standard DRF router conventions, exposing GET (list), POST (create), GET /{id}/ (retrieve), PUT/PATCH (update), and DELETE (destroy) on every resource.

Class Structure

Classes

GET /api/academics/classes/

endpoint

List all class instances.

POST /api/academics/classes/

endpoint

Create a new class instance (e.g., JSS 1A — 2024/2025 Session).

A Class represents a concrete class group for a specific academic session. It links to a ClassLevel, an optional Wing (Regular, Islamiyyah, or Tahfeez), an optional Campus, and an AcademicSession.

Request Fields

name

string

required

Human-readable class name, e.g. "JSS 1A".

class_level

integer

required

Foreign key — ID of the ClassLevel record (from the Administration module).

wing

integer

Foreign key — ID of the Wing. Nullable. Values correspond to regular, islamiyyah, or tahfeez.

campus

integer

Foreign key — ID of the Campus. Nullable.

session

integer

required

Foreign key — ID of the AcademicSession.

capacity

integer

Maximum number of students. Defaults to 40.

is_active

boolean

Whether the class is currently active. Defaults to true.

Subjects

GET /api/academics/subjects/

endpoint

List all subjects offered at the school.

POST /api/academics/subjects/

endpoint

Create a new subject.

A Subject is an academic discipline taught at the school. Subject codes must be unique across the system.

Request Fields

name

string

required

Full subject name, e.g. "Mathematics".

code

string

required

Short unique code, e.g. "MTH101". Must be unique.

department

integer

Foreign key — ID of the Department. Nullable.

subject_type

string

Classification of the subject. One of:

Value	Label
`core`	Core (default)
`elective`	Elective
`vocational`	Vocational

description

string

Optional long-form description of the subject. Defaults to empty string.

Teacher Class Subjects

GET /api/academics/teacher-class-subjects/

endpoint

List all teacher-to-class-subject assignments.

POST /api/academics/teacher-class-subjects/

endpoint

Assign a teacher to teach a subject in a class for an academic year.

A TeacherClassSubject maps a TeacherProfile to a Class and Subject combination. The combination of (teacher, class_assigned, subject, academic_year) is unique, preventing duplicate assignments.

Request Fields

teacher

integer

required

Foreign key — ID of the TeacherProfile.

class_assigned

integer

required

Foreign key — ID of the Class the teacher is assigned to.

subject

integer

required

Foreign key — ID of the Subject being taught.

is_form_teacher

boolean

Whether this teacher is the form teacher for the class. Defaults to false.

academic_year

string

required

The academic year string, e.g. "2024/2025".

CA Configurations

GET /api/academics/ca-configurations/

endpoint

List all Continuous Assessment configurations.

POST /api/academics/ca-configurations/

endpoint

Create a CA configuration for a subject, class level, and term combination.

A CAConfiguration defines the weighting split between continuous assessment (CA) and exam scores for a given Subject + ClassLevel + Term combination. The combination of these three fields is unique.

Request Fields

subject

integer

required

Foreign key — ID of the Subject.

class_level

integer

required

Foreign key — ID of the ClassLevel.

term

integer

required

Foreign key — ID of the Term.

ca_weight

number

required

Weight (percentage) allocated to continuous assessment scores, e.g. 40.00.

exam_weight

number

required

Weight (percentage) allocated to the exam score, e.g. 60.00.

total_weight

number

Total combined weight. Defaults to 100.00.

Timetables

GET /api/academics/timetables/

endpoint

List all weekly timetable entries.

POST /api/academics/timetables/

endpoint

Create a new weekly timetable slot for a class.

A Timetable entry defines a single weekly lesson slot — which class, which subject, which teacher, on which day, and at what time.

Request Fields

class_assigned

integer

required

Foreign key — ID of the Class.

subject

integer

required

Foreign key — ID of the Subject.

teacher

integer

Foreign key — ID of the TeacherProfile. Nullable.

day

string

required

Day of the week. One of: monday, tuesday, wednesday, thursday, friday, saturday, sunday.

start_time

string

required

Lesson start time in HH:MM:SS format, e.g. "08:00:00".

end_time

string

required

Lesson end time in HH:MM:SS format, e.g. "09:00:00".

room

string

Optional room or venue label, e.g. "Room 12".

is_active

boolean

Whether this slot is currently active. Defaults to true.

Exam Timetables

GET /api/academics/exam-timetables/

endpoint

List all exam timetable entries.

POST /api/academics/exam-timetables/

endpoint

Schedule an exam for a class and subject.

An ExamTimetable entry represents a scheduled examination event, linking a Class, Subject, and Term to a specific date, time range, and venue.

Request Fields

class_assigned

integer

required

Foreign key — ID of the Class.

subject

integer

required

Foreign key — ID of the Subject.

term

integer

required

Foreign key — ID of the Term.

exam_date

string

required

Date of the exam in YYYY-MM-DD format.

start_time

string

required

Exam start time in HH:MM:SS format.

end_time

string

required

Exam end time in HH:MM:SS format.

venue

string

Optional exam venue label, e.g. "Main Hall".

Assessment

Scores

GET /api/academics/scores/

endpoint

List all student subject scores.

POST /api/academics/scores/

endpoint

Record a student’s CA and exam scores for a subject in a term.

A Score captures a student’s continuous assessment score, exam score, computed total, grade, and grade point for a specific subject and term. The unique constraint on (student, subject, term) ensures one record per student per subject per term.

Request Fields

student

integer

required

Foreign key — ID of the StudentProfile.

subject

integer

required

Foreign key — ID of the Subject.

term

integer

required

Foreign key — ID of the Term.

class_assigned

integer

required

Foreign key — ID of the Class.

ca_score

number

Continuous assessment score. Defaults to 0.

exam_score

number

Examination score. Defaults to 0.

total_score

number

Computed total score. Defaults to 0.

grade

string

Grade string, e.g. "A". Populated automatically or manually.

grade_point

number

Grade point value on a GPA scale. Nullable.

is_locked

boolean

When true, the score record is locked and cannot be edited. Defaults to false.

Example — Record a Score

curl -X POST https://api.gobarau.edu.ng/api/academics/scores/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "student": 42,
    "subject": 7,
    "term": 3,
    "class_assigned": 11,
    "ca_score": "35.50",
    "exam_score": "58.00",
    "total_score": "93.50",
    "grade": "A"
  }'

integer

Unique identifier for the created score record.

student

integer

ID of the StudentProfile.

subject

integer

ID of the Subject.

total_score

string

Computed total score as a decimal string.

grade

string

Grade awarded based on total score.

is_locked

boolean

Lock state of the score record.

Report Cards

GET /api/academics/report-cards/

endpoint

List all report cards.

POST /api/academics/report-cards/

endpoint

Generate or create a report card for a student in a term.

A ReportCard aggregates a student’s performance across all subjects in a term, computing a total score, average, and class position. The unique constraint on (student, term, class_assigned) ensures one report card per student per term.

Request Fields

student

integer

required

Foreign key — ID of the StudentProfile.

term

integer

required

Foreign key — ID of the Term.

class_assigned

integer

required

Foreign key — ID of the Class.

total_score

number

Aggregate total score across all subjects. Defaults to 0.

average

number

Term average score. Defaults to 0.

position

integer

Class position ranking. Nullable.

is_published

boolean

Whether the report card is published and visible to students/parents. Defaults to false.

Assignments

GET /api/academics/assignments/

endpoint

List all assignments.

POST /api/academics/assignments/

endpoint

Create a new assignment for a class and subject.

An Assignment is a task issued to a class for a specific subject, with a due date and maximum score.

Request Fields

subject

integer

required

Foreign key — ID of the Subject.

class_assigned

integer

required

Foreign key — ID of the Class.

title

string

required

Assignment title, e.g. "Chapter 4 Review Questions".

description

string

Detailed assignment instructions. Optional.

due_date

string

required

Submission deadline in YYYY-MM-DD format.

max_score

number

Maximum achievable score. Defaults to 100.

is_published

boolean

Whether the assignment is visible to students. Defaults to false.

Assignment Submissions

GET /api/academics/assignment-submissions/

endpoint

List all assignment submissions.

POST /api/academics/assignment-submissions/

endpoint

Record a student’s submission for an assignment.

An AssignmentSubmission tracks a student’s response to a specific assignment, including the submission date, score awarded, teacher feedback, and late/graded flags. The combination of (assignment, student) is unique.

Request Fields

assignment

integer

required

Foreign key — ID of the Assignment.

student

integer

required

Foreign key — ID of the StudentProfile.

submission_date

string

required

Date submitted in YYYY-MM-DD format.

score

number

Score awarded for the submission. Nullable until graded.

feedback

string

Teacher feedback on the submission. Optional.

is_late

boolean

Whether the submission was past the due date. Defaults to false.

is_graded

boolean

Whether the submission has been graded. Defaults to false.

Attendance

Attendance Records

GET /api/academics/attendance-records/

endpoint

List all daily attendance records.

POST /api/academics/attendance-records/

endpoint

Mark attendance for a student on a given date.

An AttendanceRecord logs a student’s presence status for a single school day. The unique constraint on (student, date, class_assigned) prevents duplicate entries for the same student on the same date.

Attendance Status Values

Value	Description
`present`	Student was present (default)
`absent`	Student was absent
`late`	Student arrived late
`excused`	Student was absent with an approved excuse

Request Fields

student

integer

required

Foreign key — ID of the StudentProfile.

class_assigned

integer

required

Foreign key — ID of the Class the student belongs to.

date

string

required

Attendance date in YYYY-MM-DD format.

status

string

One of present, absent, late, or excused. Defaults to present.

remarks

string

Optional notes about the attendance, e.g. reason for absence.

marked_by

integer

Foreign key — ID of the TeacherProfile who marked attendance. Nullable.

Example — Mark Attendance

curl -X POST https://api.gobarau.edu.ng/api/academics/attendance-records/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "student": 42,
    "class_assigned": 11,
    "date": "2025-01-20",
    "status": "present",
    "marked_by": 5
  }'

Example — List Attendance for a Student

curl -X GET "https://api.gobarau.edu.ng/api/academics/attendance-records/?student=42" \
  -H "Authorization: Bearer <token>"

Attendance Summaries

GET /api/academics/attendance-summaries/

endpoint

List all termly attendance summaries.

POST /api/academics/attendance-summaries/

endpoint

Create or update a termly attendance summary for a student.

An AttendanceSummary aggregates a student’s attendance counts over an entire term, computing a final attendance percentage. The unique constraint on (student, term, class_assigned) ensures one summary per student per term.

Request Fields

student

integer

required

Foreign key — ID of the StudentProfile.

term

integer

required

Foreign key — ID of the Term.

class_assigned

integer

required

Foreign key — ID of the Class.

total_present

integer

Total days the student was present. Defaults to 0.

total_absent

integer

Total days the student was absent. Defaults to 0.

total_late

integer

Total days the student arrived late. Defaults to 0.

total_excused

integer

Total excused absences. Defaults to 0.

attendance_percentage

number

Computed attendance percentage as a decimal, e.g. "92.50". Defaults to 0.

Exams

Exam Registrations

GET /api/academics/exam-registrations/

endpoint

List all exam registrations.

POST /api/academics/exam-registrations/

endpoint

An ExamRegistration records a student’s eligibility to sit the exam for a particular subject in a given term. The unique constraint on (student, subject, term) prevents duplicate registrations.

Request Fields

student

integer

required

Foreign key — ID of the StudentProfile.

subject

integer

required

Foreign key — ID of the Subject.

term

integer

required

Foreign key — ID of the Term.

class_assigned

integer

required

Foreign key — ID of the Class.

is_registered

boolean

Whether the student is actively registered. Defaults to true.

Exam Results

GET /api/academics/exam-results/

endpoint

List all exam results.

POST /api/academics/exam-results/

endpoint

Record an exam result for a student in a subject.

An ExamResult stores the final examination outcome — score, grade, and remark — for a student’s subject in a term. The unique constraint on (student, subject, term) ensures one result per student per subject per term.

Request Fields

student

integer

required

Foreign key — ID of the StudentProfile.

subject

integer

required

Foreign key — ID of the Subject.

term

integer

required

Foreign key — ID of the Term.

class_assigned

integer

required

Foreign key — ID of the Class.

score

number

required

Exam score as a decimal, e.g. "72.50".

grade

string

Grade letter derived from the score, e.g. "B".

remark

string

Short remark on performance, e.g. "Good".

Tahfeez (Qur’an Memorization)

The Tahfeez wing is a specialist academic division of Gobarau Academy dedicated to Qur’an memorization. Students in this wing have a dedicated tracking system comprising JuzProgress — one record per student per Juz — and RecitationSession records that log live sessions between a student and their Tahfeez teacher. These two endpoints are exclusive to the Tahfeez workflow and have no equivalent in the regular or Islamiyyah wings.

Juz Progresses

GET /api/academics/juz-progresses/

endpoint

List all Juz memorization progress records.

POST /api/academics/juz-progresses/

endpoint

Create a Juz progress record for a student.

A JuzProgress record tracks a student’s memorization status for a single Juz of the Qur’an, specifying the start and end Surah and Ayat, the current status, and optional start/completion dates. The unique constraint on (student, juz_number) ensures only one progress record per Juz per student.

Juz Status Values

Value	Description
`not_started`	Memorization has not begun (default)
`in_progress`	Student is actively memorizing this Juz
`memorized`	Student has completed memorizing this Juz
`reviewed`	Student has revised and consolidated this Juz

Request Fields

student

integer

required

Foreign key — ID of the StudentProfile.

juz_number

integer

required

The Juz number (1–30).

surah_start

string

required

Name of the starting Surah in this Juz, e.g. "Al-Baqarah".

surah_end

string

required

Name of the ending Surah in this Juz, e.g. "Al-Baqarah".

ayat_start

integer

required

Ayat number where this Juz begins.

ayat_end

integer

required

Ayat number where this Juz ends.

status

string

Current memorization status. One of not_started, in_progress, memorized, reviewed. Defaults to not_started.

started_date

string

Date the student began memorizing this Juz, in YYYY-MM-DD format. Nullable.

completed_date

string

Date the student completed memorization of this Juz, in YYYY-MM-DD format. Nullable.

Example — Create a Juz Progress Record

curl -X POST https://api.gobarau.edu.ng/api/academics/juz-progresses/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "student": 88,
    "juz_number": 1,
    "surah_start": "Al-Fatihah",
    "surah_end": "Al-Baqarah",
    "ayat_start": 1,
    "ayat_end": 141,
    "status": "in_progress",
    "started_date": "2025-01-15"
  }'

Example — Mark a Juz as Memorized

curl -X PATCH https://api.gobarau.edu.ng/api/academics/juz-progresses/12/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "memorized",
    "completed_date": "2025-03-10"
  }'

Recitation Sessions

GET /api/academics/recitation-sessions/

endpoint

List all recitation session records.

POST /api/academics/recitation-sessions/

endpoint

Log a recitation session between a student and a Tahfeez teacher.

A RecitationSession records the outcome of a one-to-one recitation sitting, capturing which Juz and Surah were covered, a quality rating on a 1–5 scale, and any remarks from the teacher.

Request Fields

student

integer

required

Foreign key — ID of the StudentProfile.

teacher

integer

Foreign key — ID of the TeacherProfile supervising the session. Nullable.

date

string

required

Date of the recitation session in YYYY-MM-DD format.

juz_covered

string

required

Description of the Juz covered in this session, e.g. "Juz 2".

surah_covered

string

required

Surah(s) recited in this session, e.g. "Al-Baqarah 142–252".

quality_rating

integer

Teacher’s rating of recitation quality on a scale of 1 (poor) to 5 (excellent). Defaults to 5.

remarks

string

Optional teacher notes on pronunciation, fluency, or areas needing improvement.

Example — Log a Recitation Session

curl -X POST https://api.gobarau.edu.ng/api/academics/recitation-sessions/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "student": 88,
    "teacher": 5,
    "date": "2025-03-12",
    "juz_covered": "Juz 1",
    "surah_covered": "Al-Fatihah and Al-Baqarah 1-20",
    "quality_rating": 4,
    "remarks": "Good tajweed, needs to work on madd rules"
  }'

Query recitation sessions by student to see a full history of their Tahfeez progress over time: GET /api/academics/recitation-sessions/?student=88

Administration

People & Admissions

Academics

Finance & Services

Communication & Content

Documentation Index

​Class Structure

​Classes

​Request Fields

​Subjects

​Request Fields

​Teacher Class Subjects

​Request Fields

​CA Configurations

​Request Fields

​Timetables

​Timetables

​Request Fields

​Exam Timetables

​Request Fields

​Assessment

​Scores

​Request Fields

​Example — Record a Score

​Report Cards

​Request Fields

​Assignments

​Request Fields

​Assignment Submissions

​Request Fields

​Attendance

​Attendance Records

​Attendance Status Values

​Request Fields

​Example — Mark Attendance

​Example — List Attendance for a Student

​Attendance Summaries

​Request Fields

​Exams

​Exam Registrations

​Request Fields

​Exam Results

​Request Fields

​Tahfeez (Qur’an Memorization)

​Juz Progresses

​Juz Status Values

​Request Fields

​Example — Create a Juz Progress Record

​Example — Mark a Juz as Memorized

​Recitation Sessions

​Request Fields

​Example — Log a Recitation Session

Build docs developers (and LLMs) love

Class Structure

Classes

Request Fields

Subjects

Request Fields

Teacher Class Subjects

Request Fields

CA Configurations

Request Fields

Timetables

Timetables

Request Fields

Exam Timetables

Request Fields

Assessment

Scores

Request Fields

Example — Record a Score

Report Cards

Request Fields

Assignments

Request Fields

Assignment Submissions

Request Fields

Attendance

Attendance Records

Attendance Status Values

Request Fields

Example — Mark Attendance

Example — List Attendance for a Student

Attendance Summaries

Request Fields

Exams

Exam Registrations

Request Fields

Exam Results

Request Fields

Tahfeez (Qur’an Memorization)

Juz Progresses

Juz Status Values

Request Fields

Example — Create a Juz Progress Record

Example — Mark a Juz as Memorized

Recitation Sessions

Request Fields

Example — Log a Recitation Session