Administration API — Sessions, Campuses, and Grading

The Administration API provides full control over the structural and academic configuration of Gobarau Academy. It covers everything from the singleton school identity record through the entire academic calendar hierarchy (sessions → terms), physical infrastructure (campuses, wings), academic organisation (departments, class levels), and grading policy (grading scales and bands). All nine endpoint groups require an authenticated user whose role is super_admin, principal, or vice_principal.

Authentication Requirements

Every endpoint in this API requires two permission checks to pass:

IsAuthenticated — the request must carry a valid session or token.
IsAdminLevel — the authenticated user’s role must be one of super_admin, principal, or vice_principal.

Any other role (including teacher, bursar, student, etc.) will receive 403 Forbidden.

School Settings

Singleton endpoint for the school’s global identity record. Only one SchoolSettings instance may exist; attempting to POST a second record raises a validation error. Use PATCH to update individual fields without replacing the whole object. SchoolSettings inherits from AuditMixin, which adds public_id (UUID), created_at, updated_at, created_by, and updated_by to every response.

Method	URL
`GET`	`/api/administration/school-settings/`
`POST`	`/api/administration/school-settings/`
`GET`	`/api/administration/school-settings/{id}/`
`PUT`	`/api/administration/school-settings/{id}/`
`PATCH`	`/api/administration/school-settings/{id}/`
`DELETE`	`/api/administration/school-settings/{id}/`

Request Fields

name

string

required

The full official name of the school (max 200 characters).

motto

string

School motto (max 200 characters). Defaults to an empty string.

logo

file

School logo image. Uploaded to the school/ media path.

address

string

Physical address of the school. Defaults to an empty string.

string

Official contact email address.

phone

string

Official contact phone number (max 20 characters).

academic_year

string

Current academic year label, e.g. "2025/2026" (max 20 characters).

Response Fields

integer

Database primary key.

public_id

string (UUID)

Stable public identifier for this record.

name

string

Full official school name.

motto

string

School motto.

logo

string | null

Relative URL of the uploaded logo image, or null if not set.

address

string

Physical address.

string

Official email address.

phone

string

Official phone number.

academic_year

string

Current academic year label.

created_at

string (ISO 8601)

Timestamp of record creation.

updated_at

string (ISO 8601)

Timestamp of last update.

created_by

integer | null

Primary key of the user who created this record.

updated_by

integer | null

Primary key of the user who last modified this record.

Example

# Retrieve the school settings record
curl -X GET https://api.gobarau.edu.ng/api/administration/school-settings/ \
  -H "Authorization: Bearer <token>"

# Update the academic year only
curl -X PATCH https://api.gobarau.edu.ng/api/administration/school-settings/1/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"academic_year": "2025/2026"}'

Academic Sessions

Academic sessions represent a full school year, e.g. 2025/2026. Terms belong to a session via a foreign key. Only one session should have is_current set to true at a time. AcademicSession inherits BaseModel, providing public_id, created_at, and updated_at on every response.

Method	URL
`GET`	`/api/administration/academic-sessions/`
`POST`	`/api/administration/academic-sessions/`
`GET`	`/api/administration/academic-sessions/{id}/`
`PUT`	`/api/administration/academic-sessions/{id}/`
`PATCH`	`/api/administration/academic-sessions/{id}/`
`DELETE`	`/api/administration/academic-sessions/{id}/`

Request Fields

name

string

required

Human-readable session label, e.g. "2025/2026" (max 50 characters).

start_date

string (date)

required

Session start date in YYYY-MM-DD format.

end_date

string (date)

required

Session end date in YYYY-MM-DD format.

is_current

boolean

Marks this session as the active one. Defaults to false.

Response Fields

integer

Database primary key.

public_id

string (UUID)

Stable public identifier.

name

string

Session label.

start_date

string (date)

Start date of the session.

end_date

string (date)

End date of the session.

is_current

boolean

Whether this is the currently active session.

created_at

string (ISO 8601)

Timestamp of record creation.

updated_at

string (ISO 8601)

Timestamp of last update.

Example

# List all academic sessions
curl -X GET https://api.gobarau.edu.ng/api/administration/academic-sessions/ \
  -H "Authorization: Bearer <token>"

# Create a new academic session
curl -X POST https://api.gobarau.edu.ng/api/administration/academic-sessions/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "2025/2026",
    "start_date": "2025-09-01",
    "end_date": "2026-07-31",
    "is_current": true
  }'

Response Example

{
  "id": 3,
  "public_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "2025/2026",
  "start_date": "2025-09-01",
  "end_date": "2026-07-31",
  "is_current": true,
  "created_at": "2025-08-15T10:30:00Z",
  "updated_at": "2025-08-15T10:30:00Z"
}

Terms

A term is one of three divisions within an academic session: First, Second, or Third. The combination of session + name must be unique — you cannot create duplicate terms for the same session.

Method	URL
`GET`	`/api/administration/terms/`
`POST`	`/api/administration/terms/`
`GET`	`/api/administration/terms/{id}/`
`PUT`	`/api/administration/terms/{id}/`
`PATCH`	`/api/administration/terms/{id}/`
`DELETE`	`/api/administration/terms/{id}/`

Request Fields

session

integer

required

Primary key of the parent AcademicSession.

name

string

required

Term identifier. Must be one of:

Value	Label
`first`	First Term
`second`	Second Term
`third`	Third Term

start_date

string (date)

required

Term start date in YYYY-MM-DD format.

end_date

string (date)

required

Term end date in YYYY-MM-DD format.

is_current

boolean

Marks this term as currently active. Defaults to false.

Response Fields

integer

Database primary key.

public_id

string (UUID)

Stable public identifier.

session

integer

Primary key of the parent academic session.

name

string

Term value (first, second, or third).

start_date

string (date)

Term start date.

end_date

string (date)

Term end date.

is_current

boolean

Whether this term is currently active.

created_at

string (ISO 8601)

Timestamp of record creation.

updated_at

string (ISO 8601)

Timestamp of last update.

Example

# Create the First Term for session ID 3
curl -X POST https://api.gobarau.edu.ng/api/administration/terms/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "session": 3,
    "name": "first",
    "start_date": "2025-09-01",
    "end_date": "2025-12-15",
    "is_current": true
  }'

Wings

Wings represent organisational divisions within the school: Regular, Islamiyyah, and Tahfeez. Users are assigned to a wing; this model defines the wings themselves with optional visual and descriptive metadata.

Method	URL
`GET`	`/api/administration/wings/`
`POST`	`/api/administration/wings/`
`GET`	`/api/administration/wings/{id}/`
`PUT`	`/api/administration/wings/{id}/`
`PATCH`	`/api/administration/wings/{id}/`
`DELETE`	`/api/administration/wings/{id}/`

Request Fields

name

string

required

Wing identifier. Must be one of:

Value	Label
`regular`	Regular
`islamiyyah`	Islamiyyah
`tahfeez`	Tahfeez

color_code

string

Hex colour code for UI theming, e.g. "#3B82F6" (max 7 characters). Defaults to an empty string.

description

string

Optional text describing the wing’s purpose.

Response Fields

integer

Database primary key.

public_id

string (UUID)

Stable public identifier.

name

string

Wing value (regular, islamiyyah, or tahfeez).

color_code

string

Hex colour code string.

description

string

Descriptive text for the wing.

created_at

string (ISO 8601)

Timestamp of record creation.

updated_at

string (ISO 8601)

Timestamp of last update.

Example

# Create the Tahfeez wing
curl -X POST https://api.gobarau.edu.ng/api/administration/wings/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tahfeez",
    "color_code": "#10B981",
    "description": "Quran memorisation wing"
  }'

Campuses

Campuses represent physical branch locations of the school. Each campus may have a designated principal (a User foreign key). One campus can be flagged as the main campus via is_main.

Method	URL
`GET`	`/api/administration/campuses/`
`POST`	`/api/administration/campuses/`
`GET`	`/api/administration/campuses/{id}/`
`PUT`	`/api/administration/campuses/{id}/`
`PATCH`	`/api/administration/campuses/{id}/`
`DELETE`	`/api/administration/campuses/{id}/`

Request Fields

name

string

required

Campus name (max 200 characters).

address

string

Physical address of the campus.

phone

string

Campus contact phone number (max 20 characters).

principal

integer | null

Primary key of the User record assigned as campus principal. Nullable.

is_main

boolean

Whether this is the school’s main campus. Defaults to false.

is_active

boolean

Whether this campus is currently operational. Defaults to true.

Response Fields

integer

Database primary key.

public_id

string (UUID)

Stable public identifier.

name

string

Campus name.

address

string

Physical address.

phone

string

Contact phone number.

principal

integer | null

User PK of the assigned principal.

is_main

boolean

Main campus flag.

is_active

boolean

Active status of the campus.

created_at

string (ISO 8601)

Timestamp of record creation.

updated_at

string (ISO 8601)

Timestamp of last update.

Example

# Create a campus and assign a principal
curl -X POST https://api.gobarau.edu.ng/api/administration/campuses/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Campus",
    "address": "1 School Road, Kano",
    "phone": "+2348012345678",
    "principal": 7,
    "is_main": true,
    "is_active": true
  }'

Departments

Departments organise academic subjects and staff. Each department has a unique short code and an optional head user reference.

Method	URL
`GET`	`/api/administration/departments/`
`POST`	`/api/administration/departments/`
`GET`	`/api/administration/departments/{id}/`
`PUT`	`/api/administration/departments/{id}/`
`PATCH`	`/api/administration/departments/{id}/`
`DELETE`	`/api/administration/departments/{id}/`

Request Fields

name

string

required

Department name (max 200 characters).

code

string

required

Unique short code for the department, e.g. "MATH" (max 20 characters). Must be unique across all departments.

head

integer | null

Primary key of the User record assigned as department head. Nullable.

Response Fields

integer

Database primary key.

public_id

string (UUID)

Stable public identifier.

name

string

Department name.

code

string

Unique department code.

head

integer | null

User PK of the department head.

created_at

string (ISO 8601)

Timestamp of record creation.

updated_at

string (ISO 8601)

Timestamp of last update.

Example

# Create a Mathematics department
curl -X POST https://api.gobarau.edu.ng/api/administration/departments/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mathematics",
    "code": "MATH",
    "head": 12
  }'

Class Levels

Class levels define the academic grades within the school (e.g. JSS 1, SS 2). Each level belongs to an education_tier and carries an order_index for display ordering.

Method	URL
`GET`	`/api/administration/class-levels/`
`POST`	`/api/administration/class-levels/`
`GET`	`/api/administration/class-levels/{id}/`
`PUT`	`/api/administration/class-levels/{id}/`
`PATCH`	`/api/administration/class-levels/{id}/`
`DELETE`	`/api/administration/class-levels/{id}/`

Request Fields

name

string

required

Display name of the class level, e.g. "JSS 1" (max 100 characters).

code

string

required

Unique short code, e.g. "JSS1" (max 20 characters). Must be unique across all class levels.

order_index

integer

Integer used to sort class levels in the correct progression. Defaults to 0.

education_tier

string

Tier this class level belongs to. Must be one of:

Value	Label
`primary`	Primary
`jss`	JSS
`sss`	SSS

Defaults to primary.

Response Fields

integer

Database primary key.

public_id

string (UUID)

Stable public identifier.

name

string

Display name of the class level.

code

string

Unique class level code.

order_index

integer

Sort order index.

education_tier

string

Tier value: primary, jss, or sss.

created_at

string (ISO 8601)

Timestamp of record creation.

updated_at

string (ISO 8601)

Timestamp of last update.

Example

# Create the JSS 1 class level
curl -X POST https://api.gobarau.edu.ng/api/administration/class-levels/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "JSS 1",
    "code": "JSS1",
    "order_index": 4,
    "education_tier": "jss"
  }'

Grading Scales

A grading scale is a named policy that groups grading bands and is optionally tied to a specific academic session. Mark one scale as is_active to designate it as the currently applied policy. GradingScale inherits from AuditMixin, adding created_by and updated_by to the response.

Method	URL
`GET`	`/api/administration/grading-scales/`
`POST`	`/api/administration/grading-scales/`
`GET`	`/api/administration/grading-scales/{id}/`
`PUT`	`/api/administration/grading-scales/{id}/`
`PATCH`	`/api/administration/grading-scales/{id}/`
`DELETE`	`/api/administration/grading-scales/{id}/`

Request Fields

name

string

required

Grading scale name, e.g. "Standard 100-Point Scale" (max 200 characters).

session

integer | null

Primary key of the AcademicSession this scale applies to. Nullable — a scale may be session-agnostic.

is_active

boolean

Marks this scale as the currently active grading policy. Defaults to false.

Response Fields

integer

Database primary key.

public_id

string (UUID)

Stable public identifier.

name

string

Grading scale name.

session

integer | null

FK to the associated academic session, or null.

is_active

boolean

Whether this is the active grading scale.

created_at

string (ISO 8601)

Timestamp of record creation.

updated_at

string (ISO 8601)

Timestamp of last update.

created_by

integer | null

User PK of the creator.

updated_by

integer | null

User PK of the last editor.

Example

# Create a grading scale tied to session 3
curl -X POST https://api.gobarau.edu.ng/api/administration/grading-scales/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "2025/2026 Grading Policy",
    "session": 3,
    "is_active": true
  }'

Grading Bands

Grading bands define the score ranges within a grading scale. Each band maps a numeric score range to a grade letter, optional grade point, and a descriptive remark. A band’s min_score must not exceed its max_score.

The model enforces min_score <= max_score at the Django model validation layer (clean()). Bands are ordered by max_score descending in all list responses.

Method	URL
`GET`	`/api/administration/grading-bands/`
`POST`	`/api/administration/grading-bands/`
`GET`	`/api/administration/grading-bands/{id}/`
`PUT`	`/api/administration/grading-bands/{id}/`
`PATCH`	`/api/administration/grading-bands/{id}/`
`DELETE`	`/api/administration/grading-bands/{id}/`

Request Fields

grading_scale

integer

required

Primary key of the parent GradingScale.

min_score

number

required

Lower bound of the score range (decimal, max 5 digits with 2 decimal places). Must not be greater than max_score.

max_score

number

required

Upper bound of the score range (decimal, max 5 digits with 2 decimal places).

grade

string

required

Grade letter or symbol awarded in this range, e.g. "A", "B+" (max 5 characters).

grade_point

number | null

GPA-equivalent point value for this grade (decimal, max 3 digits with 2 decimal places). Nullable.

remark

string

Descriptive label for the grade band, e.g. "Distinction" (max 200 characters). Defaults to an empty string.

Response Fields

integer

Database primary key.

public_id

string (UUID)

Stable public identifier.

grading_scale

integer

FK to the parent grading scale.

min_score

string (decimal)

Lower bound of the score range.

max_score

string (decimal)

Upper bound of the score range.

grade

string

Grade letter for this band.

grade_point

string (decimal) | null

GPA equivalent, or null if not set.

remark

string

Descriptive remark for this grade band.

created_at

string (ISO 8601)

Timestamp of record creation.

updated_at

string (ISO 8601)

Timestamp of last update.

Example

# Create an "A" grade band (70–100) under grading scale ID 1
curl -X POST https://api.gobarau.edu.ng/api/administration/grading-bands/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "grading_scale": 1,
    "min_score": "70.00",
    "max_score": "100.00",
    "grade": "A",
    "grade_point": "4.00",
    "remark": "Distinction"
  }'

# Create a "B" grade band (60–69)
curl -X POST https://api.gobarau.edu.ng/api/administration/grading-bands/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "grading_scale": 1,
    "min_score": "60.00",
    "max_score": "69.99",
    "grade": "B",
    "grade_point": "3.00",
    "remark": "Credit"
  }'

Endpoint Summary

Resource	Base URL	Inherits
School Settings	`/api/administration/school-settings/`	`AuditMixin` (singleton)
Academic Sessions	`/api/administration/academic-sessions/`	`BaseModel`
Terms	`/api/administration/terms/`	`BaseModel`
Wings	`/api/administration/wings/`	`BaseModel`
Campuses	`/api/administration/campuses/`	`BaseModel`
Departments	`/api/administration/departments/`	`BaseModel`
Class Levels	`/api/administration/class-levels/`	`BaseModel`
Grading Scales	`/api/administration/grading-scales/`	`AuditMixin`
Grading Bands	`/api/administration/grading-bands/`	`BaseModel`

All resources that inherit BaseModel include public_id (UUID), created_at, and updated_at in every response. Resources inheriting AuditMixin additionally include created_by and updated_by user FKs.

Administration

People & Admissions

Academics

Finance & Services

Communication & Content

Documentation Index

​Authentication Requirements

​School Settings

​Request Fields

​Response Fields

​Example

​Academic Sessions

​Request Fields

​Response Fields

​Example

​Response Example

​Terms

​Request Fields

​Response Fields

​Example

​Wings

​Request Fields

​Response Fields

​Example

​Campuses

​Request Fields

​Response Fields

​Example

​Departments

​Request Fields

​Response Fields

​Example

​Class Levels

​Request Fields

​Response Fields

​Example

​Grading Scales

​Request Fields

​Response Fields

​Example

​Grading Bands

​Request Fields

​Response Fields

​Example

​Endpoint Summary

Build docs developers (and LLMs) love

Authentication Requirements

School Settings

Request Fields

Response Fields

Example

Academic Sessions

Request Fields

Response Fields

Example

Response Example

Terms

Request Fields

Response Fields

Example

Wings

Request Fields

Response Fields

Example

Campuses

Request Fields

Response Fields

Example

Departments

Request Fields

Response Fields

Example

Class Levels

Request Fields

Response Fields

Example

Grading Scales

Request Fields

Response Fields

Example

Grading Bands

Request Fields

Response Fields

Example

Endpoint Summary