{ "openapi": "3.1.0", "info": { "title": "Hilfsverein ACAKORO Talent school", "version": "1.0.0", "description": "Backend API for **Acakoro School's** CBC (Competency-Based Curriculum)\nexam and results management system.\n\nIt replaces the school's manual Excel marksheets \u2014 one workbook per\ngrade band (e.g. `Marksheet_G3-G6`, `Marksheet_G7-10`), one sheet per\ngrade per assessment (e.g. `G6_A1`, `G6_A2`, `G7_A1`) \u2014 with a single\nbackend that captures the same data and computes the same derived\nvalues, consistently, for every grade and every term.\n\n---\n\n## 1. Academic structure\n\nThe system is organized as:\n\n```\nTerm\n \u2514\u2500\u2500 Assessment (Opener \/ Mid Term \/ End Term)\n \u2514\u2500\u2500 Grade (3, 5, 6, 7, 8, 9, 10, ...)\n \u2514\u2500\u2500 Learning Area (subject, fixed per grade)\n \u2514\u2500\u2500 Student Mark (by admission number)\n```\n\n**Terms & Assessments**\nA school year has terms (Term 1, 2, 3). Each term has exactly\n**3 assessments**, sat in this order:\n\n| Order | Assessment | Notes |\n|-------|------------|-------|\n| 1 | Opener | First assessment of the term |\n| 2 | Mid Term | Mid-term assessment |\n| 3 | End Term | Final assessment of the term |\n\n**Grades**\nGrades observed in the school's existing records: **3, 5, 6, 7, 8, 9, 10**.\n(Grade 4 sheets weren't present in the sampled files but the schema\nsupports any grade without code changes.)\n\n**Learning Areas (subjects) \u2014 fixed per grade**\nEach grade has its own subject list under CBC; lower grades and\nupper grades don't study the same subjects. From the source sheets:\n\n| Grade band | Learning Areas |\n|---|---|\n| Grade 3 | English, Mathematics, Integrated Activities, Kiswahili |\n| Grade 5 \u2013 6 | English, Mathematics, Kiswahili, Agriculture, Integrated Science, ICT, Social Studies, CRE, Creative Arts |\n| Grade 7 \u2013 9 | English, Mathematics, Kiswahili, Agriculture, Integrated Science, Social Studies, CRE, Pre-Technical Studies, Creative Arts |\n| Grade 10 | English, Mathematics, Kiswahili, Geography, CSL, Business Studies, Computer Studies |\n\nA Learning Area belongs to exactly one Grade in this system \u2014 the\nsame subject name (e.g. \"English\") appearing in two grades is two\nseparate Learning Area records, since the \"out of\" mark and the\nstudents sitting it differ per grade.\n\n---\n\n## 2. Marks capture workflow\n\nMirrors how staff currently fill the Excel sheets:\n\n1. Pick the **Assessment** (Opener \/ Mid Term \/ End Term) and **Term**.\n2. Pick the **Grade**.\n3. Pick the **Learning Area** (subject) for that grade.\n4. Set the **\"out of\"** \u2014 maximum obtainable mark for that\n assessment + grade + learning area combination (this varied\n per subject in the source sheets, e.g. out of 30, out of 40,\n out of 50 \u2014 it is not fixed school-wide).\n5. Enter the **raw mark** for each student, matched by\n **admission number** (not just name \u2014 the source sheets used\n name only, which doesn't scale or disambiguate students\n reliably; the backend uses admission number as the key).\n\n---\n\n## 3. Derived values (computed automatically, not entered manually)\n\n**Performance Level** \u2014 CBC 4-band scale, computed from the\n**percentage** scored (`mark \u00f7 out_of \u00d7 100`), not a hardcoded raw\nmark cutoff. This fixes an inconsistency in the original sheets,\nwhere each sheet hardcoded its own raw-mark thresholds per subject\n(e.g. `>= 23` out of 30) instead of deriving them from percentage \u2014\nmeaning the same percentage could land in different bands on\ndifferent sheets purely due to copy-paste drift.\n\n| Level | Meaning | Default cutoff |\n|---|---|---|\n| E.E. | Exceeding Expectation | \u2265 75% |\n| M.E. | Meeting Expectation | \u2265 50% and < 75% |\n| A.E. | Approaching Expectation | \u2265 30% and < 50% |\n| B.E. | Below Expectation | < 30% |\n\n*(Cutoffs above are carried over from the observed sheet logic \u2014\ne.g. Grade 6 out of 30 used `>=23 \/ >=16 \/ >=9`, which is `~76.6% \/\n~53.3% \/ ~30%`. Confirm\/adjust exact percentages with the school\nbefore locking these as policy.)*\n\n**Points** \u2014 numeric weight attached to the performance level,\nused for ranking and aggregate reporting:\n\n| Level | Points |\n|---|---|\n| E.E. | 4 |\n| M.E. | 3 |\n| A.E. | 2 |\n| B.E. | 1 |\n\n**Per-student, per-assessment aggregates**\n- **Total Marks** \u2014 sum of raw subject scores across all Learning\n Areas the student sat for that grade\/assessment.\n- **Total Points** \u2014 sum of subject Points across the same set.\n- **Rank \/ Position** \u2014 student's position within their Grade for\n that Assessment, ordered by Total Marks (configurable to order\n by Total Points instead).\n- **Class Average** \u2014 per Learning Area, the mean raw mark across\n all students in that grade\/assessment (present in the original\n sheets as an \"AVERAGE\" row).\n\n**Per-student, per-term aggregates** (across Opener + Mid Term + End\nTerm)\n- **Term Total Points** \u2014 sum of Total Points across all 3\n assessments.\n- **Term Average Mark** \u2014 per Learning Area, mean of the student's\n marks across the 3 assessments.\n\n---\n\n## 4. Roles & access (role-based access control)\n\n| Role | Access |\n|------|--------|\n| **Admin** | Full control \u2014 manage terms, assessments, grades, learning areas, teacher & student accounts, assign teachers to grade\/subject combinations, view all results school-wide |\n| **Teacher** | Enter\/edit marks only for the grade(s) and subject(s) assigned to them; view class lists, mark sheets, and performance reports for their own classes only |\n\n\nAuthorization is enforced at the route\/policy level \u2014 e.g. a\nTeacher assigned to Grade 6 Mathematics cannot submit marks for\nGrade 7 English; a Parent can only view their own children's\nadmission numbers.\n\n---\n\n## 5. Conventions used across this API\n\n- **Auth**: Bearer token (see the Authorize button in this UI).\n- **Identifiers**: students are referenced by `admission_number`\n in request\/response bodies wherever practical, in addition to\n internal numeric IDs.\n- **Errors**: standard Laravel validation\/error JSON shape \u2014\n `{ \"message\": \"...\", \"errors\": { \"field\": [\"...\"] } }` for 422,\n `{ \"message\": \"...\" }` for 401\/403\/404\/500.\n- **Pagination**: list endpoints are paginated (`page`, `per_page`\n query params), returning Laravel's standard paginator shape.\n- **Dates**: ISO 8601 (`YYYY-MM-DD`).\n\n---\n\nThis API is consumed by the school's internal results dashboard." }, "servers": [ { "url": "https:\/\/acakoro.apelisoltech.co.ke\/api\/v1" } ], "tags": [ { "name": "Authentication", "description": "Staff authentication .\n\nCovers Admin and Teacher accounts only \u2014 students and parents are\nnot API users in this system (they're read via separate Student\/\nGuardian resources, not logged-in accounts). Administrators create\nstaff accounts directly; there is no self-registration endpoint.\n\nAll endpoints return a Sanctum bearer token on success, included\nas `Authorization: Bearer {token}` on every subsequent request.\n\n### Login\n\n| Endpoint | Auth required | Purpose |\n|---|---|---|\n| `POST \/auth\/login` | No | Authenticates with email + password. Returns a bearer token. |\n\n**Account lockout:** after 5 failed login attempts from the same\nemail + IP combination within a 15-minute window, further attempts\nare rejected until the window expires \u2014 regardless of whether the\ncredentials are correct. This protects staff accounts from\nbrute-force attempts without needing a CAPTCHA.\n\n**Deactivated accounts:** if an Administrator has set a staff\naccount's `is_active` to `false` (e.g. a teacher who has left the\nschool), login fails even with correct credentials.\n\n### Session & Token Management\n\nTokens are scoped by device name via the required `device_name`\nfield on `POST \/auth\/login` (e.g. `\"device_name\": \"office-pc\"` or\n`\"device_name\": \"teacher-app-android\"`). Logging in again from the\nsame `device_name` replaces that device's previous token \u2014 it does\nnot create unlimited tokens per device, but a user can hold one\nactive token per distinct device name simultaneously (e.g. laptop\n+ phone at the same time).\n\n| Endpoint | Auth required | Purpose |\n|---|---|---|\n| `GET \/auth\/profile` | Yes | Returns the current authenticated user with their assigned role(s) |\n| `POST \/auth\/logout` | Yes | Revokes only the token used for this request (this device) |\n| `POST \/auth\/logout-all` | Yes | Revokes every token for the user (all devices) |\n\n### Password Management\n\n| Endpoint | Auth required | Purpose |\n|---|---|---|\n| `POST \/auth\/forgot-password` | No | Sends a password reset link to the email, if registered. Always returns a generic success message \u2014 never reveals whether the email exists. |\n| `POST \/auth\/reset-password` | No | Validates the reset token and email, sets a new password. Revokes all existing sessions for that account. |\n\n> **All sessions revoked on reset:** after a successful password\n> reset, every bearer token previously issued to that account is\n> deleted. The user must log in again on every device.\n\n### Frontend Implementation Guide\n\n**Step 1 \u2014 On login**\nStore the returned bearer token securely. Include it as\n`Authorization: Bearer {token}` on every subsequent request.\n\n**Step 2 \u2014 Handle lockout responses**\nA `401` from `POST \/auth\/login` with a \"Too many login attempts\"\nmessage means the account\/IP is temporarily locked \u2014 surface the\nwait time to the user rather than retrying immediately.\n\n**Step 3 \u2014 Fetch profile**\nCall `GET \/auth\/profile` to load the user's role (Admin or\nTeacher) into app state, and use it to gate UI elements \u2014\ne.g. only Admins see grade\/subject management screens; Teachers\nonly see mark entry for their assigned classes." }, { "name": "Academic Years", "description": "Academic years for the Acakoro School CBC Exams API.\n\nAn AcademicYear (e.g. 2026) is the root of the entire academic\nstructure \u2014 Grades and Terms are both scoped to one via\n`academic_year_id`, and everything beneath them (Streams, Subjects,\nExams, Marks) traces back to it transitively. Creating an academic\nyear is typically the first setup step for a new school year,\nbefore any Grade or Term can be created.\n\nRestricted to Administrators.\n\n### Endpoints\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/academic-years` | List academic years, most recent first |\n| `POST \/academic-years` | Create an academic year |\n| `GET \/academic-years\/{academicYear}` | View a single academic year with its grades and terms |\n| `PUT \/academic-years\/{academicYear}` | Update the year number or start\/end dates |\n| `POST \/academic-years\/{academicYear}\/mark-current` | Designate this as the active academic year |\n| `DELETE \/academic-years\/{academicYear}` | Delete an academic year (cascades to everything scoped to it) |\n\n### `is_current` is not settable through create or update\n\nLike Term, `is_current` cannot be set through `POST \/academic-years`\nor `PUT \/academic-years\/{academicYear}` \u2014 every new academic year\nstarts with `is_current: false`. The only way to change it is\n`POST \/academic-years\/{academicYear}\/mark-current`, which\natomically demotes whichever other academic year currently holds\nthe flag before promoting this one \u2014 guaranteeing exactly one\nacademic year is ever current at a time, rather than leaving that\ninvariant to be accidentally violated by a plain field update.\n\n### Deleting cascades through the entire structure\n\nDeleting an academic year cascades, via foreign key constraints,\nthrough every Grade and Term scoped to it \u2014 and transitively\nthrough their Streams, Subjects, Exams, ExamSubjects, and Marks.\nThis is destructive and irreversible; there is no soft-delete or\narchive step before this takes effect." }, { "name": "Grades", "description": "Grade levels (e.g. \"Grade 1\", \"Grade 7\").\n\nA Grade is scoped to a single academic year \u2014 \"Grade 1\" in\n2026 and \"Grade 1\" in 2027 are different records, since\nstudents, streams, and marks differ between years even\nthough the level number repeats. A grade level can only\nexist once per academic year.\n\nRestricted to Administrators.\n\n### Endpoints\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/grades` | List grades, optionally filtered by `academic_year_id` |\n| `POST \/grades` | Create a single grade |\n| `POST \/grades\/bulk` | Create multiple grades in one request |\n| `GET \/grades\/{grade}` | View a single grade with its streams |\n| `PUT \/grades\/{grade}` | Update a grade's level, name, or academic year |\n| `DELETE \/grades\/{grade}` | Delete a grade (cascades to its streams and ClassSection) |\n\n### Streams are optional\n\nA grade may have zero or more Streams (sections) \u2014\ne.g. \"Grade 1 Blue\", \"Grade 1 Green\". A grade with no\nstreams is taught and assessed as a single unit.\n\n### Automatic ClassSection creation\n\nCreating a Grade automatically creates a streamless\n**ClassSection** behind the scenes \u2014 the entity that\nstudents and marks actually attach to. This happens via\na `GradeCreated` event and its listener, not inside the\nrequest\/response cycle directly, so it isn't a separate\nAPI call you need to make.\n\n> **Known gap:** if every Stream under a Grade is later\n> deleted, the grade's streamless ClassSection is not\n> currently recreated automatically. This is a\n> recognized limitation, not yet handled by a listener.\n\n### Bulk create behavior\n\n`POST \/grades\/bulk` accepts an array of grade rows and\nvalidates the whole batch before creating anything \u2014\nif any row duplicates an existing (academic_year_id,\nlevel) pair, either within the payload itself or already\nin the database, the entire request is rejected with a\n`422` and none of the rows are created. Each row created\nstill triggers its own ClassSection, exactly as a single\n`POST \/grades` would." }, { "name": "Streams", "description": "Streams (sections) within a Grade.\ne.g. \"Blue\", \"Green\", \"A\", \"East\". Stream\nnames are free text, set per school, with no fixed\nvocabulary enforced.\n\nA Stream always belongs to exactly one Grade. The same\nstream name can be reused across different grades (e.g.\nboth \"Grade 1 Blue\" and \"Grade 2 Blue\" are valid), but a\nname can only appear once within the same grade.\n\nRestricted to Administrators.\n\n### Endpoints\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/streams` | List streams, optionally filtered by `grade_id` |\n| `POST \/streams` | Create a single stream |\n| `POST \/streams\/bulk` | Create multiple streams in one request |\n| `GET \/streams\/{stream}` | View a single stream with its grade |\n| `PUT \/streams\/{stream}` | Update a stream's name or grade |\n| `DELETE \/streams\/{stream}` | Delete a stream (cascades to its ClassSection) |\n\n### Automatic ClassSection creation\n\nCreating a Stream automatically creates its own\n**ClassSection** \u2014 the entity students and marks attach\nto for that specific stream \u2014 via a `StreamCreated`\nevent and listener, same pattern as Grade.\n\n### Bulk create behavior\n\n`POST \/streams\/bulk` accepts an array of `{grade_id,\nname}` rows and validates the whole batch up front.\nDuplicate `(grade_id, name)` pairs \u2014 whether repeated\nwithin the payload or already existing in the database \u2014\nreject the entire request with a `422`; nothing is\ncreated if any row conflicts." }, { "name": "Terms", "description": "Academic terms (Term 1, 2, 3) within an academic year.\nEach term can carry optional `start_date` \/ `end_date` values,\nused for date-scoped reporting (e.g. \"results as of [date]\").\n\nA term number can only exist once per academic year \u2014\n\"Term 2\" in 2026 is a distinct record from \"Term 2\" in\n2027.\n\nRestricted to Administrators.\n\n### Endpoints\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/terms` | List terms, optionally filtered by `academic_year_id` |\n| `POST \/terms` | Create a single term |\n| `GET \/terms\/{term}` | View a single term with its academic year |\n| `PUT \/terms\/{term}` | Update a term's number or dates |\n| `DELETE \/terms\/{term}` | Delete a term |\n\nNo bulk endpoint \u2014 a school year only ever has 3 terms,\nso batching isn't necessary the way it is for Grades or\nStreams.\n\n### `is_current` is not settable here\n\n`is_current` cannot be set through `POST \/terms` or\n`PUT \/terms\/{term}`. Marking a term as the active one\nneeds to keep its parent AcademicYear's `is_current`\nflag in sync \u2014 that combined action is not yet exposed\nas an endpoint on this controller." }, { "name": "Subjects", "description": "Subjects (Learning Areas).\n\nSubjects are created per Grade, not globally \u2014 \"English\" in Grade 3\nand \"English\" in Grade 7 are separate records with their own code,\nband thresholds, and lifecycle. There is no shared\/global subject\nlist to choose from; every grade builds its own subject set from\nscratch.\n\nRestricted to Administrators.\n\n### Endpoints\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/subjects` | List subjects, optionally filtered by `grade_id` |\n| `POST \/subjects` | Create a subject within a grade |\n| `GET \/subjects\/{subject}` | View a single subject with its grade and bands |\n| `PUT \/subjects\/{subject}` | Update a subject's name or band thresholds |\n| `DELETE \/subjects\/{subject}` | Delete a subject |\n\n### Auto-generated code\n\n`code` is never accepted from the client \u2014 it's generated\nserver-side in the format `G{level}-{LETTERS}`, e.g. `G6-ENG` for\n\"English\" in Grade 6. The letters come from the subject name's\nfirst 3 alphabetic characters, uppercased. If that 3-letter code\nalready exists, the system automatically widens to 4, 5, or more\nletters until a unique code is found; as a last resort it falls\nback to a numeric suffix (e.g. `G6-CRE2`).\n\n`code` and `grade_id` cannot be changed after creation \u2014 delete and\nrecreate the subject if it was assigned to the wrong grade.\n\n### Performance-level bands are per-subject\n\nEach subject carries its own CBC band thresholds rather than using\none fixed system-wide rule:\n\n| Field | Meaning | Default |\n|---|---|---|\n| `ee_min_percentage` | Minimum % to score E.E. (Exceeding Expectation) | 75 |\n| `me_min_percentage` | Minimum % to score M.E. (Meeting Expectation) | 50 |\n| `ae_min_percentage` | Minimum % to score A.E. (Approaching Expectation) | 30 |\n\nB.E. (Below Expectation) has no stored threshold \u2014 it's simply\n\"below `ae_min_percentage`\" by definition. Thresholds must be in\ndescending order (EE \u2265 ME \u2265 AE); the API rejects payloads that\nviolate this with a `422`.\n\nDefaults apply automatically if band fields are omitted on create \u2014\nadmins only need to override them for subjects that should grade\nmore strictly or more leniently than the school-wide default.\n\n### Default enrollment (student side, not yet built)\n\nBy design, every student in a subject's grade is expected to sit\nthat subject by default. Per-student exclusions (a student who\ndoes not take a given subject) are modeled on the Student side of\nthe system, which is not yet implemented \u2014 Subjects themselves\nhave no awareness of individual students." }, { "name": "Students", "description": "Student records and class history\n\nRestricted to Administrators \u2014 enforced via `StudentPolicy`, not\nroute middleware. (Once Teacher-to-class assignment exists, view\naccess should widen so a Teacher can see students in their own\nassigned classes \u2014 not yet implemented.)\n\n### Endpoints\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/students` | List students, optionally filtered by `class_section_id` |\n| `POST \/students` | Create a student and enroll them into a class |\n| `GET \/students\/{student}` | View a student, their class, and subject exclusions |\n| `PUT \/students\/{student}` | Update bio\/guardian fields only |\n| `POST \/students\/{student}\/change-class` | Promote or transfer a student to a different class |\n| `POST \/students\/{student}\/subjects\/exclude` | Exclude the student from a subject |\n| `DELETE \/students\/{student}\/subjects\/{subject}\/exclude` | Re-include the student in a subject |\n| `DELETE \/students\/{student}` | Deactivate the student (soft, not a hard delete) |\n\n### Admission number is permanent\n\n`admission_number` (e.g. `AC001`) is generated automatically\non creation and can never be changed afterward \u2014 not through\n`PUT \/students\/{student}`, not through a class change, not through\nany other endpoint. This is enforced at three layers: the update\nrequest doesn't accept the field, no service method ever reassigns\nit after creation, and the `Student` model throws if a save attempt\never leaves it dirty. `admission_year` reflects the calendar year\nthe student first joined \u2014 it does not change when the student is\npromoted into later academic years.\n\n### Class history, not a single class field\n\nA student does not have a single \"current class\" column. Instead,\nevery placement is a row in `student_class_enrollments`, each\ntagged with a `status` (`active`, `promoted`, `transferred`,\n`graduated`, `withdrawn`) and an `is_current` flag. Exactly one\nenrollment per student should be current at a time \u2014 enforced at\nthe service layer, not by a database constraint, mirroring how\n`AcademicYear.is_current` and `Term.is_current` already work.\n\n`POST \/students\/{student}\/change-class` is the only way to move a\nstudent between classes. It closes the existing current enrollment\n(setting `status` and `left_on`) and opens a new one atomically \u2014\nused both for routine year-end promotion and for a mid-year stream\nchange within the same academic year (e.g. Grade 6 Blue \u2192 Grade 6\nGreen in March).\n\n### Subject exclusion: opt-out, not opt-in\n\nA student is automatically expected to sit every Subject belonging\nto their current grade \u2014 there is no \"enroll in a subject\" step.\nThe only thing ever stored is the **exception**: rows in\n`student_subject_exclusions` recording which subjects a specific\nstudent has been removed from (e.g. a medical exemption from a\npractical subject).\n\nA subject can only be excluded if it belongs to the student's\n*current* grade \u2014 excluding an unrelated subject is rejected with\na `422`. Excluding an already-excluded subject, or re-including a\nsubject that was never excluded, are both safe no-ops rather than\nerrors.\n\nThe student's actual effective subject list is never stored \u2014 it's\ncomputed on request as \"every subject in their current grade,\nminus their exclusions.\" Pass `?with_effective_subjects=1` on\n`GET \/students\/{student}` to include this computed list in the\nresponse; it's omitted by default since computing it requires\nextra queries beyond the student's base record.\n\n### Guardian contact\n\nEach student carries a single guardian's contact details\n(`guardian_name`, `guardian_phone`, `guardian_relationship`)\ndirectly on their own record. There is no separate Guardian model\nyet \u2014 a richer version supporting multiple guardians shared across\nsiblings is a future module, not this one." }, { "name": "Exams", "description": "Exams.\n\nAn Exam is a free-form assessment event within a Term, scoped to a\nsingle Grade \u2014 e.g. \"Opener\", \"CAT 1\", \"Mock\", \"End Term\". There is\nno fixed list of allowed exam names and no fixed count per term; a\nschool can run as many or as few exams as it wants. Because Exam\nbelongs to one grade only, the same conceptual exam needs a\nseparate record per grade \u2014 \"Opener\" for Grade 6 and \"Opener\" for\nGrade 7 are two different rows, each with their own subjects and\nmarks.\n\nRestricted to Administrators \u2014 enforced via `ExamPolicy`, not\nroute middleware.\n\n### Endpoints\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/exams` | List exams, optionally filtered by `term_id` and\/or `grade_id` |\n| `POST \/exams` | Create an exam within a term, for one grade |\n| `GET \/exams\/{exam}` | View an exam with its term, grade, and exam subjects |\n| `PUT \/exams\/{exam}` | Update an exam's name, report-card flag, or date |\n| `DELETE \/exams\/{exam}` | Delete an exam (cascades to its exam subjects and marks) |\n| `PUT \/exam-subjects\/{examSubject}\/out-of` | Set the maximum mark for one subject within this exam |\n\n### ExamSubject: a live snapshot, not a frozen one\n\nCreating an Exam automatically generates an **ExamSubject** row for\nevery Subject currently belonging to that exam's grade \u2014 there is\nno manual \"add subject to exam\" step. This snapshot stays live in\nboth directions:\n\n- If a new Subject is added to the grade **after** an exam already\nexists, the new Subject is automatically backfilled into every\nexisting exam for that grade.\n- `out_of` (the maximum mark for that subject within that exam) is\nleft `null` when an ExamSubject is created \u2014 there's no sensible\ndefault, unlike Subject's performance bands. An administrator\nmust set it explicitly via `PUT \/exam-subjects\/{examSubject}\/out-of`\nbefore any marks can be entered against it.\n\n### `include_in_report_card`\n\nEach Exam carries a boolean flag controlling whether its marks feed\ninto the term's report card computation. A school might run more\nexams than officially count \u2014 e.g. 4 internal tests, only 2 of\nwhich are designated as official results. (Report card computation\nitself is a separate module, built on top of this flag.)" }, { "name": "Marks", "description": "Mark entry and retrieval for the Acakoro School CBC Exams API.\n\nA Mark is one student's score against one ExamSubject (a specific\nsubject within a specific exam). Performance level (E.E.\/M.E.\/A.E.\/\nB.E.) and points are never stored \u2014 they're computed live on every\nread, from the mark's score, its exam_subject's `out_of`, and the\nSubject's own band thresholds. This avoids marks silently going\nstale if a subject's bands or an exam_subject's `out_of` are edited\nafter marks already exist.\n\nRestricted to Administrators \u2014 enforced via `MarkPolicy`, not\nroute middleware.\n\n> **Known gap:** in a real CBC school, Teachers enter marks\n> day-to-day, not Admins. `MarkPolicy` is admin-only for every\n> action right now because Teacher-to-class\/subject assignment\n> doesn't exist yet in this system. Once that assignment model is\n> built, mark creation\/updates should check whether the\n> authenticated user is the teacher assigned to the relevant grade\n> and subject \u2014 this is the most significant deferred item in the\n> exams system as it stands.\n\n### Endpoints\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/marks?exam_subject_id=` | List every mark recorded for one exam subject (a class list with scores) |\n| `GET \/marks\/roster\/{examSubject}` | Get the exam\/subject context + eligible student list, for rendering a mark-entry sheet |\n| `GET \/marks\/students\/{student}` | List every mark recorded for one student, across all exams they've sat |\n| `POST \/marks` | Record a single student's mark |\n| `POST \/marks\/bulk` | Record marks for many students against the SAME exam subject in one request |\n| `POST \/marks\/import` | Upload a filled spreadsheet (`.xlsx`\/`.xls`\/`.csv`) and bulk-create marks from it |\n| `PUT \/marks\/{mark}` | Correct an existing mark's score |\n| `DELETE \/marks\/{mark}` | Remove a recorded mark |\n\n### What blocks a mark from being recorded\n\nA `422` is returned, and nothing is created, if any of the\nfollowing are true:\n\n- The target ExamSubject has no `out_of` set yet \u2014 an administrator\nmust configure the maximum mark first.\n- The score exceeds that `out_of`.\n- The student is excluded from the subject (see the Students tag's\nsubject exclusion model) \u2014 excluded students cannot be given a\nmark for that subject at all.\n- A mark already exists for that student on that exam subject \u2014 use\n`PUT \/marks\/{mark}` to correct it instead of creating a duplicate.\n\nThese checks apply identically across `POST \/marks`,\n`POST \/marks\/bulk`, and `POST \/marks\/import` \u2014 there is no path\nthat bypasses them, including the spreadsheet import, which\ninternally delegates to the exact same bulk-creation logic.\n\n### Bulk entry is the realistic shape of classroom use\n\n`POST \/marks\/bulk` targets ONE exam subject and accepts an array of\n`{student_id, score}` rows \u2014 matching how a teacher actually works:\npick the exam and subject once, then key in scores for the whole\nclass in one sitting. The entire batch is validated up front using\nbatched queries (not one query per student) before anything is\ncreated; if any row fails a check above, the whole request is\nrejected and none of the marks are recorded.\n\n### Mark-entry roster: what a frontend needs to render a sheet\n\n`GET \/marks\/roster\/{examSubject}` is built specifically for\nspreadsheet-style mark entry \u2014 it returns everything needed to\nrender a complete entry sheet (or generate a real Excel file) from\na single call, without a second request to look up the exam or\nsubject's own details:\n\n```json\n{\n\"data\": {\n \"exam\": { \"id\": 5, \"name\": \"Opener\", \"term_id\": 3 },\n \"subject\": { \"id\": 21, \"name\": \"Mathematics\", \"code\": \"G6-MAT\" },\n \"out_of\": 100,\n \"students\": [\n { \"student_id\": 12, \"admission_number\": \"AC012\", \"full_name\": \"Jane Doe\", \"score\": null, \"mark_id\": null },\n { \"student_id\": 13, \"admission_number\": \"AC013\", \"full_name\": \"John Smith\", \"score\": 78, \"mark_id\": 204 }\n ]\n}\n}\n```\n\nThe `students` list is already filtered server-side to exactly who\nshould appear on the sheet \u2014 the frontend never has to reimplement\neligibility logic itself:\n\n- **Class match**: only students whose CURRENT enrollment's\nClassSection belongs to the exam's grade are included. A\nstudent's class is determined by their live enrollment record,\nnot just by any historical association with the grade.\n- **Exclusions respected**: students excluded from this subject\n(see the Students tag) never appear in the roster at all \u2014 they\ncannot be marked for it, so there's no reason to show them on\nthe entry sheet.\n- **Inactive students excluded**: deactivated students\n(`is_active: false`) are omitted.\n\nEach student row already carries `score`\/`mark_id` if a mark\nexists for them on this exam subject \u2014 `null` for students not yet\nmarked. This means the same endpoint serves both a fresh entry\nsession and reviewing\/correcting an in-progress one: a frontend\ndoesn't need a separate \"has this student been marked\" check.\n\n`out_of` is included so the frontend can validate scores\nclient-side before submitting (e.g. greying out the input or\nshowing a warning) \u2014 but it being `null` does not block the\nroster from rendering; only `POST \/marks` and `POST \/marks\/bulk`\nactually enforce it being set.\n\n### Importing marks from a spreadsheet\n\n`POST \/marks\/import` is the other half of the roster workflow: a\nteacher who prefers working in Excel offline can take the roster\nresponse above, fill in the `score` column in a spreadsheet, and\nupload it back here instead of typing scores into the app one row\nat a time.\n\n**Expected upload shape** \u2014 three columns, header row skipped\nautomatically:\n\n| Column A | Column B | Column C |\n|---|---|---|\n| `admission_number` | `full_name` (display only \u2014 ignored on import) | `score` |\n| AC012 | Jane Doe | 78 |\n| AC013 | John Smith | 45 |\n\nThis mirrors the roster's own student fields exactly, so the\nintended round trip is: fetch the roster \u2192 build\/export a\nspreadsheet from it client-side \u2192 teacher fills in `score` \u2192\nre-upload the same file unchanged.\n\nThe upload is matched to students by `admission_number`, not by\nrow position \u2014 a reordered or partially filled sheet still imports\ncorrectly. A row whose `admission_number` doesn't match any\nstudent is **skipped with a warning**, not treated as a failure of\nthe whole import \u2014 one typo or a row for a student who's since\ntransferred out shouldn't discard every other valid row in the\nsheet:\n\n```json\n{\n\"data\": {\n \"marks\": [ \/* MarkResource entries for every row that succeeded *\/ ],\n \"warnings\": [\"No student found with admission number \\\\\"AC999\\\\\" \u2014 row skipped.\"]\n}\n}\n```\n\nEvery row that does resolve to a real student still passes through\nthe identical `out_of`\/score-ceiling\/exclusion\/duplicate checks\nlisted above \u2014 the spreadsheet path has no relaxed validation\ncompared to entering marks directly in the UI." }, { "name": "Results", "description": "Exam and term results computation for the Acakoro School CBC Exams\nAPI.\n\nResults are never stored automatically when marks are entered \u2014\nthey must be explicitly computed by an Administrator. This is\nintentional: marks can be corrected or added after initial entry,\nand a result computed too early would be stale. The workflow is:\nenter all marks \u2192 compute results \u2192 generate report cards.\n\nRestricted to Administrators \u2014 enforced via policy, not route\nmiddleware.\n\n### Two levels of results\n\n**Exam results** \u2014 how every student in a grade performed in ONE\nspecific exam, across all subjects they sat for it.\n\n**Term results** \u2014 the averaged summary across every exam in a term\nthat has `include_in_report_card: true`. A term can have many exams\n(Opener, CAT 1, Mock, End Term) but only the ones flagged as\n\"counts toward the report card\" feed into term results. Subject\nscores are averaged across those exams \u2014 e.g. if Opener and End\nTerm both count, a student's Mathematics term result is the average\nof their Opener and End Term Mathematics scores.\n\n### What gets computed and stored\n\nBoth exam results and term results are **stored snapshots** (not\ncomputed live on every read) \u2014 once computed, they persist in the\ndatabase until recomputed. This makes results list views and report\ncard generation fast, since they read pre-aggregated rows rather\nthan recalculating across the marks table each time.\n\nEach result stores:\n\n- **Per-subject breakdown**: score (or average score), out_of,\npercentage, performance level (E.E.\/M.E.\/A.E.\/B.E.), and points\n\u2014 computed using the Subject's own band thresholds, not a global\nrule.\n- **Aggregates**: total marks, total points, average percentage\nacross all subjects.\n- **Two ranks**: `stream_rank` (position within the student's own\nstream, e.g. 3rd in Grade 6 Blue) and `grade_rank` (position\nacross the whole grade, e.g. 11th in all Grade 6). Both are\nassigned after all students' totals are known \u2014 you can't rank\nuntil everyone's score is computed.\n\n### Endpoints\n\n| Endpoint | Purpose |\n|---|---|\n| `POST \/results\/exams\/{exam}\/compute` | Compute (or recompute) results for every student in this exam |\n| `POST \/results\/terms\/{term}\/compute` | Aggregate term results across all include_in_report_card exams |\n| `GET \/results\/exams\/{exam}` | List all students' exam results, ordered by grade rank |\n| `GET \/results\/terms\/{term}` | List all students' term results, ordered by grade rank |\n| `GET \/results\/exams\/{exam}\/students\/{student}` | One student's full exam result with per-subject breakdown |\n| `GET \/results\/terms\/{term}\/students\/{student}` | One student's full term result with per-subject breakdown |\n\n### Filtering by stream\n\n`GET \/results\/exams\/{exam}` and `GET \/results\/terms\/{term}` both\naccept an optional `class_section_id` query parameter. Omit it to\nsee the full grade-wide leaderboard; pass it to narrow to one\nstream (e.g. Grade 6 Blue only).\n\n### Recomputing after mark corrections\n\nBoth compute endpoints are idempotent \u2014 calling them again after\nmarks have been corrected or added simply overwrites the stale\nresult with fresh data. Ranks are reassigned from scratch on each\ncall. There is no \"stale\" flag on results yet \u2014 the frontend can\ninfer a result may be out of date by comparing the result's\n`computed_at` timestamp against the latest mark's `updated_at`, if\nneeded.\n\n### Compute order matters\n\nTerm results are derived from exam results \u2014 `computeTermResults`\nreads the already-computed `exam_result_subjects` rows to average\nthem, rather than going back to raw marks. This means:\n\n1. Run `POST \/results\/exams\/{exam}\/compute` for **every**\ninclude_in_report_card exam in the term.\n2. Then run `POST \/results\/terms\/{term}\/compute`.\n\nIf you skip step 1 (or run step 2 before step 1), the term result\nwill average across whatever exam results already exist \u2014 which\nmay be stale, partial, or missing entirely.\n\nThe bulk report card generation endpoint (`POST \/report-cards\/exams\/{exam}\/bulk`)\nruns both compute steps automatically before dispatching PDF jobs,\nso you only need to call them manually if you want to view results\nwithout also generating PDFs." }, { "name": "Report Cards", "description": "Report card generation and retrieval for the Acakoro School CBC\nExams API.\n\nA Report Card is a **frozen snapshot** of one student's term\nresults at a specific point in time \u2014 once generated, it does not\nchange even if marks are later corrected. If marks change, you\nregenerate; the old snapshot is overwritten by the new one.\n\nReport cards are generated asynchronously via Laravel's job queue.\nThe HTTP request returns immediately with a `pending` status and\n(for bulk operations) a `batch_id` \u2014 the actual PDF is produced in\nthe background. The frontend should poll for progress rather than\nwaiting on the initial request.\n\nRestricted to Administrators \u2014 enforced via policy, not route\nmiddleware.\n\n### Status lifecycle\n\nEvery report card row passes through this lifecycle:\n\n```\npending \u2192 processing \u2192 done\n \u2198 failed (with failure_reason explaining why)\n```\n\n- **`pending`**: queued, not yet picked up by a worker.\n- **`processing`**: a queue worker has started generating the PDF.\n- **`done`**: PDF generated and stored. Download is available.\n- **`failed`**: PDF generation failed. `failure_reason` explains\nwhy (most commonly: term results haven't been computed yet for\nthis student). Failed cards can be retried by triggering\ngeneration again \u2014 the row resets to `pending`.\n\n### Endpoints\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/report-cards` | List report cards, filterable by `term_id`, `class_section_id`, `status` |\n| `POST \/report-cards\/students\/{student}\/terms\/{term}` | Generate one student's report card |\n| `POST \/report-cards\/exams\/{exam}\/bulk` | Bulk generate for every student in an exam's grade |\n| `POST \/report-cards\/terms\/{term}\/bulk` | Bulk generate for every student across a whole term |\n| `GET \/report-cards\/batch\/{batchId}` | Poll a bulk generation's progress |\n| `GET \/report-cards\/{reportCard}` | View a report card's status and frozen snapshot data |\n| `GET \/report-cards\/{reportCard}\/download` | Download the generated PDF |\n\n### \"One click\" bulk generation\n\n`POST \/report-cards\/exams\/{exam}\/bulk` is the primary action a\nschool administrator will use day-to-day. Passing one exam ID\ntriggers the full pipeline for every eligible student in that\nexam's grade:\n\n1. Recomputes exam results (catches any last-minute mark\ncorrections).\n2. Recomputes term results (averages across include_in_report_card\nexams).\n3. Creates\/resets a `ReportCard` row per student to `pending`.\n4. Dispatches one `GenerateReportCardJob` per student as a\nLaravel batch.\n5. Returns immediately with a `batch_id` and total count.\n\n```json\n{\n\"data\": { \"batch_id\": \"abc-123\", \"total\": 42 },\n\"meta\": { \"poll_url\": \"\/api\/v1\/report-cards\/batch\/abc-123\" }\n}\n```\n\nThe frontend should then poll `GET \/report-cards\/batch\/{batchId}`\nuntil `finished: true`:\n\n```json\n{\n\"data\": {\n \"total\": 42,\n \"pending\": 10,\n \"processed\": 30,\n \"failed\": 2,\n \"finished\": false\n}\n}\n```\n\n### The frozen snapshot\n\nWhen a report card is generated, every subject line is stored as\nfully denormalized strings \u2014 `subject_name` and `subject_code` are\ncopied at generation time, not referenced as foreign keys. This\nmeans the report card remains historically accurate even if a\nsubject is renamed or deleted from the system afterward. A report\ncard is a legal\/historical document, not a live view.\n\nThe snapshot captures:\n- Per-subject: average score, out_of, percentage, performance\nlevel, points.\n- Aggregates: average marks, average percentage, total points.\n- Rankings: stream_rank, grade_rank.\n- Metadata: which term, which class, generated_at timestamp.\n\n### PDF layout\n\nPDFs are generated server-side using DomPDF from the Blade\ntemplate at `resources\/views\/report-cards\/template.blade.php`.\nThe template uses the frozen snapshot data \u2014 not live database\njoins \u2014 so the PDF is consistent with what was stored at generation\ntime.\n\nDownloaded via `GET \/report-cards\/{reportCard}\/download`, which\nstreams the stored file with a descriptive filename (e.g.\n`report-card-AC012-term-3.pdf`). Returns `404` if the card's\nstatus is not yet `done`.\n\n### Prerequisites\n\nReport cards depend on term results, which depend on exam results.\nThe bulk generate endpoints auto-compute both \u2014 but if you call\nthe single-student generate endpoint (`POST \/report-cards\/students\/\n{student}\/terms\/{term}`), you must have already computed term\nresults for that student manually first, or the job will fail with:\n\n> `\"No term result found. Run computeTermResults() before\n> generating report cards.\"`" } ], "security": [ { "http": [] } ], "paths": { "\/academic-years": { "get": { "operationId": "academicYear.index", "description": "Returns every academic year, most recent first.\n\nRestricted to Administrators.", "summary": "List academic years", "tags": [ "Academic Years" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AcademicYearResource" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "academicYear.store", "description": "Creates an academic year (e.g. 2026), with optional start\/end\ndates. Every other piece of the academic structure \u2014 Grades,\nTerms \u2014 is scoped to one of these years via `academic_year_id`,\nso this is typically the first thing set up before anything\nelse.\n\n`is_current` cannot be set here \u2014 it always starts `false`. Use\n`POST \/academic-years\/{academicYear}\/mark-current` to designate\nthe active year.\n\nRestricted to Administrators.", "summary": "Create an academic year", "tags": [ "Academic Years" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreAcademicYearRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AcademicYearResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Academic year created successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/academic-years\/{academicYear}": { "get": { "operationId": "academicYear.show", "description": "Returns a single academic year with its grades and terms.\n\nRestricted to Administrators.", "summary": "View an academic year", "tags": [ "Academic Years" ], "parameters": [ { "name": "academicYear", "in": "path", "required": true, "description": "The academic year ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AcademicYearResource" }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "academicYear.update", "description": "Updates the year number or its start\/end dates. `is_current`\ncannot be changed through this endpoint.\n\nRestricted to Administrators.", "summary": "Update an academic year", "tags": [ "Academic Years" ], "parameters": [ { "name": "academicYear", "in": "path", "required": true, "description": "The academic year ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateAcademicYearRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AcademicYearResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Academic year updated successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "academicYear.destroy", "description": "Deletes the academic year along with every Grade and Term scoped\nto it, which cascade-delete via foreign key constraints \u2014 and,\ntransitively, every Subject, Exam, and Mark beneath those.\n\nRestricted to Administrators.", "summary": "Delete an academic year", "tags": [ "Academic Years" ], "parameters": [ { "name": "academicYear", "in": "path", "required": true, "description": "The academic year ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Academic year deleted successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/academic-years\/{academicYear}\/mark-current": { "post": { "operationId": "academicYear.markCurrent", "description": "Designates this academic year as the active one, demoting any\nother academic year that currently holds that flag. This is the\nonly way `is_current` can change \u2014 it cannot be set directly\nthrough `POST`\/`PUT`.\n\nRestricted to Administrators.", "summary": "Mark an academic year as current", "tags": [ "Academic Years" ], "parameters": [ { "name": "academicYear", "in": "path", "required": true, "description": "The academic year ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AcademicYearResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Academic year marked as current." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/analytics\/grades": { "get": { "operationId": "analytics.grades", "summary": "Compare every grade in the selected exam or term", "tags": [ "Analytics" ], "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "exam", "term" ] } }, { "name": "exam_id", "in": "query", "schema": { "type": "integer" } }, { "name": "term_id", "in": "query", "schema": { "type": "integer" } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "class_section_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "readiness": { "type": "object", "properties": { "computed_at": { "type": [ "string", "null" ] }, "exams_in_scope": { "type": "integer", "minimum": 0 }, "exams_pending_compute": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "exam_subjects_missing_out_of": { "type": "integer" }, "students_without_results": { "type": "integer" } }, "required": [ "computed_at", "exams_in_scope", "exams_pending_compute", "exam_subjects_missing_out_of", "students_without_results" ] } }, "required": [ "readiness" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/analytics\/teachers": { "get": { "operationId": "analytics.teachers", "summary": "Rank active teachers by the results in marks they recorded.\nThe response names this attribution because teaching assignments\nare not represented in the current school schema", "tags": [ "Analytics" ], "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "exam", "term" ] } }, { "name": "exam_id", "in": "query", "schema": { "type": "integer" } }, { "name": "term_id", "in": "query", "schema": { "type": "integer" } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "class_section_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "scope": { "type": "object", "properties": { "type": { "type": "string" }, "exam_id": { "type": [ "integer", "null" ] }, "term_id": { "type": [ "integer", "null" ] }, "grade_id": { "type": [ "integer", "null" ] }, "class_section_id": { "type": [ "integer", "null" ] }, "score_label": { "type": "string", "enum": [ "Total marks", "Average marks" ] } }, "required": [ "type", "exam_id", "term_id", "grade_id", "class_section_id", "score_label" ] }, "attribution": { "type": "string", "const": "Marks recorded by teacher" }, "teachers": { "type": "string" } }, "required": [ "scope", "attribution", "teachers" ] }, { "type": "object", "properties": { "scope": { "type": "object", "properties": { "type": { "type": "string" }, "exam_id": { "type": [ "integer", "null" ] }, "term_id": { "type": [ "integer", "null" ] }, "grade_id": { "type": [ "integer", "null" ] }, "class_section_id": { "type": [ "integer", "null" ] }, "score_label": { "type": "string", "enum": [ "Total marks", "Average marks" ] } }, "required": [ "type", "exam_id", "term_id", "grade_id", "class_section_id", "score_label" ] }, "attribution": { "type": "string", "const": "Marks recorded by teacher" }, "teachers": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "scope", "attribution", "teachers" ] } ] }, "meta": { "type": "object", "properties": { "readiness": { "type": "object", "properties": { "computed_at": { "type": [ "string", "null" ] }, "exams_in_scope": { "type": "integer", "minimum": 0 }, "exams_pending_compute": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "exam_subjects_missing_out_of": { "type": "integer" }, "students_without_results": { "type": "integer" } }, "required": [ "computed_at", "exams_in_scope", "exams_pending_compute", "exam_subjects_missing_out_of", "students_without_results" ] } }, "required": [ "readiness" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/analytics\/options": { "get": { "operationId": "analytics.options", "description": "Management list endpoints stay paginated for their tables. This\nendpoint deliberately returns the bounded option sets needed by\nselectors: all terms, grades for the selected term's academic\nyear, and exams for the selected term\/grade. That prevents valid\nhistorical records disappearing after page 15 without loading\nunrelated full management pages into the browser.", "summary": "Complete, compact filter data for the analytics workspace", "tags": [ "Analytics" ], "parameters": [ { "name": "term_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "terms": { "type": "array", "items": {} }, "grades": { "type": "array", "items": {} }, "exams": { "type": "array", "items": {} } }, "required": [ "terms", "grades", "exams" ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/analytics\/classes": { "get": { "operationId": "analytics.classes", "description": "Rolls up computed results for a whole grade and for each class\nsection within it, so \"how is Grade 6 doing?\" and \"which stream\n * is ahead?\" are answered by one request.\n\nScope the request with `?scope=exam&exam_id=X` for a single\nassessment, or `?scope=term&term_id=X` for the term summary,\nplus an optional `grade_id`. For a term scope `grade_id` is\nstrongly recommended \u2014 a term spans every grade in the school.\n\n`overall` is the grade-wide aggregate; `classes` is one row per\nclass section, ordered strongest first. `distribution` counts\nSUBJECT ENTRIES per CBC level (one learner in one subject), not\nlearners, and uses the levels stored at compute time \u2014 so a\nsubject with custom thresholds is honoured.\n\nNote `meta.readiness`: analytics reads computed results only, so\nan empty response usually means results have not been computed\nyet rather than that nothing was recorded.\n\nAvailable to Administrators and Teachers.", "summary": "Compare classes and streams", "tags": [ "Analytics" ], "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "exam", "term" ] } }, { "name": "exam_id", "in": "query", "schema": { "type": "integer" } }, { "name": "term_id", "in": "query", "schema": { "type": "integer" } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "class_section_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "readiness": { "type": "object", "properties": { "computed_at": { "type": [ "string", "null" ] }, "exams_in_scope": { "type": "integer", "minimum": 0 }, "exams_pending_compute": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "exam_subjects_missing_out_of": { "type": "integer" }, "students_without_results": { "type": "integer" } }, "required": [ "computed_at", "exams_in_scope", "exams_pending_compute", "exam_subjects_missing_out_of", "students_without_results" ] } }, "required": [ "readiness" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/analytics\/classes\/{classSection}": { "get": { "operationId": "analytics.classDetail", "description": "One class section in depth: its summary, its performance in each\nlearning area ordered strongest to weakest, and the five highest\nand five lowest performing learners.\n\nTakes the same scope query parameters as `GET \/analytics\/classes`.\n\nAvailable to Administrators and Teachers.", "summary": "Analyse a single class", "tags": [ "Analytics" ], "parameters": [ { "name": "classSection", "in": "path", "required": true, "description": "The class section ID", "schema": { "type": "integer" } }, { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "exam", "term" ] } }, { "name": "exam_id", "in": "query", "schema": { "type": "integer" } }, { "name": "term_id", "in": "query", "schema": { "type": "integer" } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "class_section_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "readiness": { "type": "object", "properties": { "computed_at": { "type": [ "string", "null" ] }, "exams_in_scope": { "type": "integer", "minimum": 0 }, "exams_pending_compute": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "exam_subjects_missing_out_of": { "type": "integer" }, "students_without_results": { "type": "integer" } }, "required": [ "computed_at", "exams_in_scope", "exams_pending_compute", "exam_subjects_missing_out_of", "students_without_results" ] } }, "required": [ "readiness" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/analytics\/subjects": { "get": { "operationId": "analytics.subjects", "description": "Ranks every subject in scope from strongest to weakest by mean\npercentage, with its level distribution and spread, and returns a\nsubject-by-class matrix so the same learning area can be compared\nacross streams.\n\nTakes the same scope query parameters as `GET \/analytics\/classes`.\n\nAvailable to Administrators and Teachers.", "summary": "Analyse learning areas", "tags": [ "Analytics" ], "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "exam", "term" ] } }, { "name": "exam_id", "in": "query", "schema": { "type": "integer" } }, { "name": "term_id", "in": "query", "schema": { "type": "integer" } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "class_section_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "readiness": { "type": "object", "properties": { "computed_at": { "type": [ "string", "null" ] }, "exams_in_scope": { "type": "integer", "minimum": 0 }, "exams_pending_compute": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "exam_subjects_missing_out_of": { "type": "integer" }, "students_without_results": { "type": "integer" } }, "required": [ "computed_at", "exams_in_scope", "exams_pending_compute", "exam_subjects_missing_out_of", "students_without_results" ] } }, "required": [ "readiness" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/analytics\/learners": { "get": { "operationId": "analytics.learners", "description": "Every learner with a computed result for the current scope,\nordered by grade rank, with their headline figures and class.\n\nThis is the learner picker for the analytics page \u2014 `\/students`\nis restricted to Administrators, so teachers need a roster they\ncan actually reach. It returns only learners who already have a\ncomputed result, which is exactly the set that has a profile\nworth opening.\n\nTakes the same scope query parameters as `GET \/analytics\/classes`.\n\nAvailable to Administrators and Teachers.", "summary": "List learners in scope", "tags": [ "Analytics" ], "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "exam", "term" ] } }, { "name": "exam_id", "in": "query", "schema": { "type": "integer" } }, { "name": "term_id", "in": "query", "schema": { "type": "integer" } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "class_section_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "readiness": { "type": "object", "properties": { "computed_at": { "type": [ "string", "null" ] }, "exams_in_scope": { "type": "integer", "minimum": 0 }, "exams_pending_compute": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "exam_subjects_missing_out_of": { "type": "integer" }, "students_without_results": { "type": "integer" } }, "required": [ "computed_at", "exams_in_scope", "exams_pending_compute", "exam_subjects_missing_out_of", "students_without_results" ] } }, "required": [ "readiness" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/analytics\/merit-list": { "get": { "operationId": "analytics.meritList", "description": "The rank-order sheet schools print and post: every learner from\nfirst to last, with a mark and CBC level per learning area, their\ntotals, and both class and grade position.\n\nWorks at either granularity from the same scope parameters \u2014 omit\n`class_section_id` for the whole grade, pass it for one class.\nPosition follows the stored rank for that granularity (class rank\nwithin a class, grade rank across a grade), so the sheet always\nmatches the position printed on the learner's report card.\n\n`subjects` is the column set; each learner's `subjects` map is\nkeyed by `subject_id`, and a learner excluded from a learning area\nsimply has no entry for it.\n\nAvailable to Administrators and Teachers.", "summary": "Class or grade merit list", "tags": [ "Analytics" ], "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "exam", "term" ] } }, { "name": "exam_id", "in": "query", "schema": { "type": "integer" } }, { "name": "term_id", "in": "query", "schema": { "type": "integer" } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "class_section_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "readiness": { "type": "object", "properties": { "computed_at": { "type": [ "string", "null" ] }, "exams_in_scope": { "type": "integer", "minimum": 0 }, "exams_pending_compute": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "exam_subjects_missing_out_of": { "type": "integer" }, "students_without_results": { "type": "integer" } }, "required": [ "computed_at", "exams_in_scope", "exams_pending_compute", "exam_subjects_missing_out_of", "students_without_results" ] } }, "required": [ "readiness" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/analytics\/progress": { "get": { "operationId": "analytics.progress", "description": "Every other analytics endpoint answers \"how did this term go?\".\nThis one answers \"is it improving?\", charting the same measure\nacross every term of one academic year for a grade or a single\nclass, plus per-class and per-learning-area movement.\n\nPass any `term_id` in the year to select the year, then\n`grade_id` and optionally `class_section_id` to choose the level.\n\nUses TERM results only. A term percentage is the mean of a\nlearner's subject percentages, whereas an exam percentage is\ntotal marks over total possible \u2014 mixing them on one axis would\nbe comparing two different measures.\n\nTerms with nothing computed are still returned, with\n`has_results: false`, so a gap in the year is visible rather than\nsilently closed up.\n\nAvailable to Administrators and Teachers.", "summary": "Term-over-term progression", "tags": [ "Analytics" ], "parameters": [ { "name": "term_id", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "class_section_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "context": { "type": "object", "properties": { "academic_year": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "id", "year" ] }, "grade": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "display_name" ] }, "class": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "display_name" ] }, "label": { "type": "string" }, "is_class_scoped": { "type": "boolean" }, "measure": { "type": "string", "description": "Named so a chart axis can say what it is plotting.", "const": "Term average percentage" } }, "required": [ "academic_year", "grade", "class", "label", "is_class_scoped", "measure" ] }, "terms": { "type": "array", "items": { "type": "object", "properties": { "term_id": { "type": "string" }, "number": { "type": "string" }, "label": { "type": "string" }, "has_results": { "type": "boolean" }, "learners": { "type": "string" }, "mean_percentage": { "type": [ "string", "null" ] }, "median_percentage": { "type": [ "string", "null" ] }, "mean_points": { "type": [ "string", "null" ] }, "highest_percentage": { "type": [ "string", "null" ] }, "lowest_percentage": { "type": [ "string", "null" ] }, "distribution": { "type": "string" }, "change": { "type": [ "number", "null" ], "description": "Movement against the previous term that actually has\nresults, so an uncomputed term does not read as a drop." } }, "required": [ "term_id", "number", "label", "has_results", "learners", "mean_percentage", "median_percentage", "mean_points", "highest_percentage", "lowest_percentage", "distribution", "change" ] } }, "classes": { "type": "array", "items": {} }, "subjects": { "type": "array", "items": {} } }, "required": [ "context", "terms", "classes", "subjects" ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/analytics\/export\/pdf": { "get": { "operationId": "analytics.exportPdf", "description": "Renders whichever view the `view` parameter names \u2014 `classes`\n(default), `subjects`, `class`, or `student` \u2014 for the scope given\nby the usual scope parameters. `class` and `student` additionally\nneed `target_id`: the class section or learner to render.\n\nThe document is built from the same service calls that back the\nJSON endpoints, so an exported PDF cannot disagree with what was\non screen. It renders synchronously \u2014 one analysis is a small\ndocument, unlike a bulk report card run.\n\nAvailable to Administrators and Teachers.", "summary": "Download the current analysis as a PDF", "tags": [ "Analytics" ], "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "exam", "term" ] } }, { "name": "exam_id", "in": "query", "schema": { "type": "integer" } }, { "name": "term_id", "in": "query", "schema": { "type": "integer" } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "class_section_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "view", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object" } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/analytics\/students\/{student}": { "get": { "operationId": "analytics.student", "description": "A learner's subject-by-subject profile for the chosen scope, each\nsubject shown against the class mean, plus their rank and how\nthey compare with the class and grade averages.\n\n`trends` holds two deliberately separate series: `exams` (this\nlearner across the exams of the term) and `terms` (across the\nterms of the academic year). They are NOT interchangeable \u2014 an\nexam percentage is total marks over total possible, while a term\npercentage is the mean of that learner's subject percentages \u2014 so\nthey should not be plotted on one shared axis.\n\nTakes the same scope query parameters as `GET \/analytics\/classes`.\n\nAvailable to Administrators and Teachers.", "summary": "Analyse a single learner", "tags": [ "Analytics" ], "parameters": [ { "name": "student", "in": "path", "required": true, "description": "The student ID", "schema": { "type": "integer" } }, { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "exam", "term" ] } }, { "name": "exam_id", "in": "query", "schema": { "type": "integer" } }, { "name": "term_id", "in": "query", "schema": { "type": "integer" } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "class_section_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "readiness": { "type": "object", "properties": { "computed_at": { "type": [ "string", "null" ] }, "exams_in_scope": { "type": "integer", "minimum": 0 }, "exams_pending_compute": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "exam_subjects_missing_out_of": { "type": "integer" }, "students_without_results": { "type": "integer" } }, "required": [ "computed_at", "exams_in_scope", "exams_pending_compute", "exam_subjects_missing_out_of", "students_without_results" ] } }, "required": [ "readiness" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/auth\/login": { "post": { "operationId": "auth.login", "description": "Authenticates a staff account (Admin or Teacher) with email and\npassword. Staff accounts are created by an Administrator \u2014 there\nis no self-registration endpoint.\n\nReturns a Sanctum bearer token scoped to `device_name`, so the same\nuser can hold separate, independently revocable tokens per device\n(e.g. one for the office PC, one for a mobile app).\n\nLocked out after 5 failed attempts from the same email\/IP within\n15 minutes.", "summary": "Login", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/LoginRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "$ref": "#\/components\/schemas\/UserResource" }, "token": { "type": "string" }, "token_type": { "type": "string", "const": "Bearer" } }, "required": [ "user", "token", "token_type" ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Login successful." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "401": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "errors": { "type": "string" } }, "required": [ "data", "meta", "errors" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [] } }, "\/auth\/forgot-password": { "post": { "operationId": "auth.forgotPassword", "description": "Sends a password reset link to the given email address, if it\nbelongs to a registered staff account. Always returns a generic\nsuccess response regardless of whether the email exists, so the\nAPI never reveals which emails are registered.", "summary": "Request password reset link", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EmailRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "If that email is registered, a password reset link has been sent." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [] } }, "\/auth\/reset-password": { "post": { "operationId": "auth.resetPassword", "description": "Sets a new password using the token from the reset link sent via\n`POST \/auth\/forgot-password`. On success, every existing session\nfor the account is revoked \u2014 the user must log in again on all\ndevices with the new password.", "summary": "Reset password", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ResetPasswordRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Password has been reset successfully. Please log in with your new password." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [] } }, "\/auth\/logout": { "post": { "operationId": "auth.logout", "description": "Revokes only the Sanctum token used to authenticate the current\nrequest, ending this device's session. Other devices the user is\nlogged in on remain active \u2014 use `POST \/auth\/logout-all` to revoke\nevery session at once.", "summary": "Logout", "tags": [ "Authentication" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Logged out successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/auth\/logout-all": { "post": { "operationId": "auth.logoutAllDevices", "description": "Revokes every Sanctum token belonging to the authenticated user,\nending all active sessions across every device.", "summary": "Logout of all devices", "tags": [ "Authentication" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Logged out of all devices." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/auth\/profile": { "get": { "operationId": "auth.profile", "description": "Returns the full record for the currently authenticated staff\nuser, including their assigned role(s) (Admin \/ Teacher).", "summary": "Authenticated user profile", "tags": [ "Authentication" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/UserResource" }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/dashboard": { "get": { "operationId": "dashboard.index", "description": "Returns three combined sections in one response: `snapshot`\n(point-in-time counts \u2014 students, staff, grades, current term),\n`activity` (the 10 most recent enrollments, marks, and report\ncard completions, merged and sorted by recency), and `progress`\n(operational health \u2014 exam subjects missing `out_of`, exams\nwith zero marks recorded, report card status breakdown).\n\nCached for 60 seconds to avoid recomputing aggregate queries\nacross most of the system on every dashboard load. Use\n`POST \/dashboard\/refresh` to force an immediate recompute after\nmaking a change you want reflected right away.\n\nRestricted to Administrators.", "summary": "Get the admin dashboard overview", "tags": [ "Dashboard" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "snapshot": { "type": "object", "properties": { "current_academic_year": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "id", "year" ] }, "current_term": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "number": { "type": "integer" } }, "required": [ "id", "number" ] }, "total_students": { "type": "integer", "minimum": 0 }, "total_staff": { "type": "integer", "minimum": 0 }, "total_active_classes": { "type": "integer", "minimum": 0 }, "total_grades": { "type": "integer", "minimum": 0 }, "total_streams": { "type": "integer", "minimum": 0 }, "total_subjects": { "type": "integer", "minimum": 0 }, "total_exams": { "type": "integer", "minimum": 0 }, "students_by_grade": { "type": "array", "items": { "type": "object", "properties": { "grade_id": { "type": "string" }, "grade_level": { "type": "string" }, "student_count": { "type": "string" } }, "required": [ "grade_id", "grade_level", "student_count" ] } } }, "required": [ "current_academic_year", "current_term", "total_students", "total_staff", "total_active_classes", "total_grades", "total_streams", "total_subjects", "total_exams", "students_by_grade" ] }, "activity": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "enrollment" }, "message": { "type": "string" }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "type", "message", "occurred_at" ] }, { "type": "string" } ] } }, "progress": { "type": "object", "properties": { "exam_subjects_missing_out_of": { "type": "integer", "minimum": 0 }, "exams_without_any_marks": { "type": "integer", "minimum": 0 }, "report_cards_pending": { "type": "integer", "minimum": 0 }, "report_cards_processing": { "type": "integer", "minimum": 0 }, "report_cards_failed": { "type": "integer", "minimum": 0 }, "report_cards_done": { "type": "integer", "minimum": 0 } }, "required": [ "exam_subjects_missing_out_of", "exams_without_any_marks", "report_cards_pending", "report_cards_processing", "report_cards_failed", "report_cards_done" ] }, "term_context": { "anyOf": [ { "type": "object", "properties": { "academic_year": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "id", "year" ] }, "term": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "display_name": { "type": "string" }, "start_date": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "display_name", "start_date", "end_date" ] }, "days_total": { "type": [ "string", "null" ] }, "days_elapsed": { "type": [ "object", "null" ] }, "days_remaining": { "type": [ "object", "null" ] }, "percent_elapsed": { "type": [ "number", "null" ] } }, "required": [ "academic_year", "term", "days_total", "days_elapsed", "days_remaining", "percent_elapsed" ] }, { "type": "object", "properties": { "academic_year": { "type": "null" }, "term": { "type": "null" }, "days_total": { "type": "null" }, "days_elapsed": { "type": "null" }, "days_remaining": { "type": "null" }, "percent_elapsed": { "type": "null" } }, "required": [ "academic_year", "term", "days_total", "days_elapsed", "days_remaining", "percent_elapsed" ] } ] }, "workflow": { "anyOf": [ { "type": "object", "properties": { "term_id": { "type": "integer" }, "steps": { "type": "array", "prefixItems": [ { "type": "array", "items": {} }, { "type": "array", "items": {} }, { "type": "array", "items": {} }, { "type": "array", "items": {} } ], "minItems": 4, "maxItems": 4, "additionalItems": false }, "percent_complete": { "type": [ "number", "null" ] } }, "required": [ "term_id", "steps", "percent_complete" ] }, { "type": "object", "properties": { "term_id": { "type": "null" }, "steps": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "percent_complete": { "type": "null" } }, "required": [ "term_id", "steps", "percent_complete" ] } ] }, "attention": { "type": "array", "items": {} }, "performance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean" }, "term_id": { "type": "integer" }, "mean_percentage": { "type": "string" }, "mean_score": { "type": "string" }, "median_percentage": { "type": "string" }, "learners": { "type": "string" }, "distribution": { "type": "string" }, "strongest_grade": { "type": [ "object", "null" ], "description": "gradeBreakdown already sorts strongest first.", "properties": { "grade_id": { "type": "string" }, "display_name": { "type": "string" }, "mean_percentage": { "type": "string" }, "learners": { "type": "string" } }, "required": [ "grade_id", "display_name", "mean_percentage", "learners" ] }, "weakest_grade": { "type": [ "object", "null" ], "properties": { "grade_id": { "type": "string" }, "display_name": { "type": "string" }, "mean_percentage": { "type": "string" }, "learners": { "type": "string" } }, "required": [ "grade_id", "display_name", "mean_percentage", "learners" ] }, "highest_learner": { "type": [ "object", "null" ], "properties": { "student_id": { "type": "string" }, "full_name": { "type": "string" }, "percentage": { "type": "string" }, "class_display_name": { "type": "string" } }, "required": [ "student_id", "full_name", "percentage", "class_display_name" ] }, "strongest_class": { "type": [ "object", "null" ], "properties": { "class_section_id": { "type": "string" }, "display_name": { "type": "string" }, "mean_percentage": { "type": "string" }, "learners": { "type": "string" } }, "required": [ "class_section_id", "display_name", "mean_percentage", "learners" ] }, "most_improved_grade": { "type": [ "array", "null" ], "items": {} }, "most_improved_class": { "type": [ "array", "null" ], "items": {} }, "grade_performance": { "type": "array", "items": {} }, "subject_performance": { "type": "array", "items": {} } }, "required": [ "available", "term_id", "mean_percentage", "mean_score", "median_percentage", "learners", "distribution", "strongest_grade", "weakest_grade", "highest_learner", "strongest_class", "most_improved_grade", "most_improved_class", "grade_performance", "subject_performance" ] }, { "type": "object", "properties": { "available": { "type": "boolean" }, "term_id": { "type": "integer" }, "mean_percentage": { "type": "null" }, "mean_score": { "type": "null" }, "median_percentage": { "type": "null" }, "learners": { "type": "integer" }, "distribution": { "type": "null" }, "strongest_grade": { "type": "null" }, "weakest_grade": { "type": "null" }, "highest_learner": { "type": "null" }, "strongest_class": { "type": "null" }, "most_improved_grade": { "type": "null" }, "most_improved_class": { "type": "null" }, "grade_performance": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "subject_performance": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "term_id", "mean_percentage", "mean_score", "median_percentage", "learners", "distribution", "strongest_grade", "weakest_grade", "highest_learner", "strongest_class", "most_improved_grade", "most_improved_class", "grade_performance", "subject_performance" ] } ] } }, "required": [ "snapshot", "activity", "progress", "term_context", "workflow", "attention", "performance" ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/dashboard\/activity": { "get": { "operationId": "dashboard.activity", "summary": "Full recent activity feed for its dedicated page", "tags": [ "Dashboard" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "enrollment" }, "message": { "type": "string" }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "type", "message", "occurred_at" ] }, { "type": "string" } ] } }, "meta": { "type": "object", "properties": { "limit": { "type": "integer", "const": 50 } }, "required": [ "limit" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/dashboard\/refresh": { "post": { "operationId": "dashboard.refresh", "description": "Clears the 60-second cache and recomputes immediately, returning\nthe fresh data. Call this after an action you want reflected on\nthe dashboard without waiting for the cache to naturally expire\n(e.g. right after bulk-generating report cards).\n\nRestricted to Administrators.", "summary": "Force-refresh the dashboard cache", "tags": [ "Dashboard" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "snapshot": { "type": "object", "properties": { "current_academic_year": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "id", "year" ] }, "current_term": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "number": { "type": "integer" } }, "required": [ "id", "number" ] }, "total_students": { "type": "integer", "minimum": 0 }, "total_staff": { "type": "integer", "minimum": 0 }, "total_active_classes": { "type": "integer", "minimum": 0 }, "total_grades": { "type": "integer", "minimum": 0 }, "total_streams": { "type": "integer", "minimum": 0 }, "total_subjects": { "type": "integer", "minimum": 0 }, "total_exams": { "type": "integer", "minimum": 0 }, "students_by_grade": { "type": "array", "items": { "type": "object", "properties": { "grade_id": { "type": "string" }, "grade_level": { "type": "string" }, "student_count": { "type": "string" } }, "required": [ "grade_id", "grade_level", "student_count" ] } } }, "required": [ "current_academic_year", "current_term", "total_students", "total_staff", "total_active_classes", "total_grades", "total_streams", "total_subjects", "total_exams", "students_by_grade" ] }, "activity": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "enrollment" }, "message": { "type": "string" }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "type", "message", "occurred_at" ] }, { "type": "string" } ] } }, "progress": { "type": "object", "properties": { "exam_subjects_missing_out_of": { "type": "integer", "minimum": 0 }, "exams_without_any_marks": { "type": "integer", "minimum": 0 }, "report_cards_pending": { "type": "integer", "minimum": 0 }, "report_cards_processing": { "type": "integer", "minimum": 0 }, "report_cards_failed": { "type": "integer", "minimum": 0 }, "report_cards_done": { "type": "integer", "minimum": 0 } }, "required": [ "exam_subjects_missing_out_of", "exams_without_any_marks", "report_cards_pending", "report_cards_processing", "report_cards_failed", "report_cards_done" ] }, "term_context": { "anyOf": [ { "type": "object", "properties": { "academic_year": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "id", "year" ] }, "term": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "display_name": { "type": "string" }, "start_date": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "display_name", "start_date", "end_date" ] }, "days_total": { "type": [ "string", "null" ] }, "days_elapsed": { "type": [ "object", "null" ] }, "days_remaining": { "type": [ "object", "null" ] }, "percent_elapsed": { "type": [ "number", "null" ] } }, "required": [ "academic_year", "term", "days_total", "days_elapsed", "days_remaining", "percent_elapsed" ] }, { "type": "object", "properties": { "academic_year": { "type": "null" }, "term": { "type": "null" }, "days_total": { "type": "null" }, "days_elapsed": { "type": "null" }, "days_remaining": { "type": "null" }, "percent_elapsed": { "type": "null" } }, "required": [ "academic_year", "term", "days_total", "days_elapsed", "days_remaining", "percent_elapsed" ] } ] }, "workflow": { "anyOf": [ { "type": "object", "properties": { "term_id": { "type": "integer" }, "steps": { "type": "array", "prefixItems": [ { "type": "array", "items": {} }, { "type": "array", "items": {} }, { "type": "array", "items": {} }, { "type": "array", "items": {} } ], "minItems": 4, "maxItems": 4, "additionalItems": false }, "percent_complete": { "type": [ "number", "null" ] } }, "required": [ "term_id", "steps", "percent_complete" ] }, { "type": "object", "properties": { "term_id": { "type": "null" }, "steps": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "percent_complete": { "type": "null" } }, "required": [ "term_id", "steps", "percent_complete" ] } ] }, "attention": { "type": "array", "items": {} }, "performance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean" }, "term_id": { "type": "integer" }, "mean_percentage": { "type": "string" }, "mean_score": { "type": "string" }, "median_percentage": { "type": "string" }, "learners": { "type": "string" }, "distribution": { "type": "string" }, "strongest_grade": { "type": [ "object", "null" ], "description": "gradeBreakdown already sorts strongest first.", "properties": { "grade_id": { "type": "string" }, "display_name": { "type": "string" }, "mean_percentage": { "type": "string" }, "learners": { "type": "string" } }, "required": [ "grade_id", "display_name", "mean_percentage", "learners" ] }, "weakest_grade": { "type": [ "object", "null" ], "properties": { "grade_id": { "type": "string" }, "display_name": { "type": "string" }, "mean_percentage": { "type": "string" }, "learners": { "type": "string" } }, "required": [ "grade_id", "display_name", "mean_percentage", "learners" ] }, "highest_learner": { "type": [ "object", "null" ], "properties": { "student_id": { "type": "string" }, "full_name": { "type": "string" }, "percentage": { "type": "string" }, "class_display_name": { "type": "string" } }, "required": [ "student_id", "full_name", "percentage", "class_display_name" ] }, "strongest_class": { "type": [ "object", "null" ], "properties": { "class_section_id": { "type": "string" }, "display_name": { "type": "string" }, "mean_percentage": { "type": "string" }, "learners": { "type": "string" } }, "required": [ "class_section_id", "display_name", "mean_percentage", "learners" ] }, "most_improved_grade": { "type": [ "array", "null" ], "items": {} }, "most_improved_class": { "type": [ "array", "null" ], "items": {} }, "grade_performance": { "type": "array", "items": {} }, "subject_performance": { "type": "array", "items": {} } }, "required": [ "available", "term_id", "mean_percentage", "mean_score", "median_percentage", "learners", "distribution", "strongest_grade", "weakest_grade", "highest_learner", "strongest_class", "most_improved_grade", "most_improved_class", "grade_performance", "subject_performance" ] }, { "type": "object", "properties": { "available": { "type": "boolean" }, "term_id": { "type": "integer" }, "mean_percentage": { "type": "null" }, "mean_score": { "type": "null" }, "median_percentage": { "type": "null" }, "learners": { "type": "integer" }, "distribution": { "type": "null" }, "strongest_grade": { "type": "null" }, "weakest_grade": { "type": "null" }, "highest_learner": { "type": "null" }, "strongest_class": { "type": "null" }, "most_improved_grade": { "type": "null" }, "most_improved_class": { "type": "null" }, "grade_performance": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "subject_performance": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "term_id", "mean_percentage", "mean_score", "median_percentage", "learners", "distribution", "strongest_grade", "weakest_grade", "highest_learner", "strongest_class", "most_improved_grade", "most_improved_class", "grade_performance", "subject_performance" ] } ] } }, "required": [ "snapshot", "activity", "progress", "term_context", "workflow", "attention", "performance" ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Dashboard refreshed." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/exams": { "get": { "operationId": "exam.index", "description": "Returns exams, optionally filtered by `term_id` and\/or\n`grade_id`. Exam names are free-form (e.g. \"Opener\", \"CAT 1\",\n\"Mock\") \u2014 there is no fixed list of allowed exams per term.\n\nRestricted to Administrators.", "summary": "List exams", "tags": [ "Exams" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/ExamResource" }, { "type": "object", "required": [ "term", "grade" ] } ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "exam.store", "description": "Creates an exam within a term, for a single grade. Creating the\nexam automatically generates an ExamSubject row for every\nSubject currently belonging to that grade. Each subject inherits\nthe standard maximum automatically and can later be customized via\n`PUT \/exam-subjects\/{examSubject}\/out-of`.\n\n`include_in_report_card` controls whether this exam's marks\ncount toward the term's report card computation \u2014 a school can\nrun more exams than officially count.\n\nTo create the same exam (e.g. \"Opener\") across several grades at\nonce instead of repeating this call per grade, use\n`POST \/exams\/for-grades`.\n\nRestricted to Administrators.", "summary": "Create an exam", "tags": [ "Exams" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreExamRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/ExamResource" }, { "type": "object", "required": [ "term", "grade", "exam_subjects" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Exam created successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/exams\/for-grades": { "post": { "operationId": "exam.storeForGrades", "description": "Creates the SAME exam name (e.g. \"Opener\") in one request across\nevery grade listed in `grade_ids` \u2014 one Exam row per grade,\nsince Exam is structurally scoped to a single grade. There is no\nimplicit \"all grades\" behavior: the admin must explicitly list\nwhich grades this exam applies to, since not every exam\nnecessarily runs for every grade (e.g. a \"Mock\" exam might only\napply to upper grades).\n\nEach created row triggers its own ExamSubject auto-generation,\nexactly as a single `POST \/exams` would, including the automatic\ndefault maximum mark.\n\nRejected with a `422`, with nothing created, if this exam name\nalready exists for this term in ANY of the listed grades.\n\nRestricted to Administrators.", "summary": "Create one exam across multiple grades", "tags": [ "Exams" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreExamForGradesRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ExamResource" } }, "meta": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/exams\/{exam}": { "get": { "operationId": "exam.show", "description": "Returns a single exam with its term, grade, and every\nExamSubject (including which ones still need `out_of` set).\n\nRestricted to Administrators.", "summary": "View an exam", "tags": [ "Exams" ], "parameters": [ { "name": "exam", "in": "path", "required": true, "description": "The exam ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ExamResource" }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "exam.update", "description": "Updates the exam's name, report-card inclusion flag, or date.\n`term_id` and `grade_id` cannot be changed \u2014 delete and recreate\nthe exam if it was assigned to the wrong grade\/term.\n\nRestricted to Administrators.", "summary": "Update an exam", "tags": [ "Exams" ], "parameters": [ { "name": "exam", "in": "path", "required": true, "description": "The exam ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateExamRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/ExamResource" }, { "type": "object", "required": [ "term", "grade", "exam_subjects" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Exam updated successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "exam.destroy", "description": "Deletes the exam along with its ExamSubject rows and any marks\nrecorded against them, which cascade-delete via foreign key\nconstraints.\n\nRestricted to Administrators.", "summary": "Delete an exam", "tags": [ "Exams" ], "parameters": [ { "name": "exam", "in": "path", "required": true, "description": "The exam ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Exam deleted successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/exams\/{exam}\/out-of": { "put": { "operationId": "exam.bulkSetOutOf", "description": "Sets the same maximum mark across every subject in this exam in\none call, instead of repeating `PUT \/exam-subjects\/{id}\/out-of`\nper subject. By default only subjects that don't have `out_of`\nset yet are touched \u2014 pass `overwrite_existing: true` to force\nevery subject to this value, including ones already customized\nindividually. Per-subject overrides remain available afterward\nvia `PUT \/exam-subjects\/{examSubject}\/out-of`.\n\nRestricted to Administrators.", "summary": "Bulk-set \"out of\" for every subject in an exam", "tags": [ "Exams" ], "parameters": [ { "name": "exam", "in": "path", "required": true, "description": "The exam ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/BulkSetExamOutOfRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/ExamSubjectResource" }, { "type": "object", "required": [ "subject", "default_out_of" ] } ] } }, "meta": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/exam-subjects\/{examSubject}\/out-of": { "put": { "operationId": "exam.setOutOf", "description": "Sets (or updates) the maximum mark for a specific exam+subject\ncombination. Marks cannot be entered for an ExamSubject until\nthis is set.\n\nRestricted to Administrators.", "summary": "Set an exam subject's \"out of\"", "tags": [ "Exams" ], "parameters": [ { "name": "examSubject", "in": "path", "required": true, "description": "The exam subject ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SetExamSubjectOutOfRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ExamSubjectResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Out of updated successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/exam-subjects\/{examSubject}\/out-of-override": { "delete": { "operationId": "exam.resetOutOf", "summary": "Remove a subject-level maximum and inherit the exam-series default", "tags": [ "Exams" ], "parameters": [ { "name": "examSubject", "in": "path", "required": true, "description": "The exam subject ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/ExamSubjectResource" }, { "type": "object", "required": [ "subject", "default_out_of" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Maximum mark reset to the exam default." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/exam-series": { "get": { "operationId": "examSeries.index", "tags": [ "Exams" ], "parameters": [ { "name": "term_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/ExamSeriesResource" }, { "type": "object", "required": [ "term" ] } ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "examSeries.store", "tags": [ "Exams" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreExamSeriesRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ExamSeriesResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/exam-series\/{examSeries}": { "get": { "operationId": "examSeries.show", "tags": [ "Exams" ], "parameters": [ { "name": "examSeries", "in": "path", "required": true, "description": "The exam series ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ExamSeriesResource" }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "examSeries.update", "tags": [ "Exams" ], "parameters": [ { "name": "examSeries", "in": "path", "required": true, "description": "The exam series ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateExamSeriesRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ExamSeriesResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Exam updated across every grade." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "examSeries.destroy", "tags": [ "Exams" ], "parameters": [ { "name": "examSeries", "in": "path", "required": true, "description": "The exam series ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Exam and all grade sittings were deleted." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/exam-series\/{examSeries}\/out-of-overrides": { "delete": { "operationId": "examSeries.resetOutOfOverrides", "description": "The reset covers every grade sitting in this exam series. It is atomic:\nif any recorded learner mark exceeds the default, no override is reset.", "summary": "Remove every subject-level maximum and inherit the exam default", "tags": [ "Exams" ], "parameters": [ { "name": "examSeries", "in": "path", "required": true, "description": "The exam series ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ExamSeriesResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string" }, "reset_count": { "type": "integer" } }, "required": [ "message", "reset_count" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/fee-structures": { "get": { "operationId": "feeStructure.index", "description": "The saved, editable fee templates invoices are generated from.\nFilter with `academic_year_id`, `grade_id` and `term_id`.\n\nRestricted to Administrators.", "summary": "List fee structures", "tags": [ "Fee structures" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/FeeStructureResource" }, { "type": "object", "required": [ "academic_year", "grade", "term", "items", "total" ] } ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "feeStructure.store", "description": "A structure with no `grade_id` applies school-wide; one naming a\ngrade takes precedence for learners in it. Same for `term_id`.\n\nOmit `items` entirely and the template is seeded with the standard\nfee rows (Admission, Tuition, Uniform, Boarding, Examination,\nHospital, Activity) at zero, ready to be filled in \u2014 every row can\nthen be renamed, re-priced or removed.\n\nRestricted to Administrators.", "summary": "Create a fee structure", "tags": [ "Fee structures" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreFeeStructureRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/FeeStructureResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Fee structure created." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/fee-structures\/{feeStructure}": { "get": { "operationId": "feeStructure.show", "description": "Restricted to Administrators.", "summary": "Get a fee structure", "tags": [ "Fee structures" ], "parameters": [ { "name": "feeStructure", "in": "path", "required": true, "description": "The fee structure ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/FeeStructureResource" }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "feeStructure.update", "description": "Sending `items` replaces the whole list \u2014 the editor posts every\nrow, so rows can be added, renamed, re-priced, reordered and\nremoved in one save. Invoices already generated keep their own\ncopy of the lines and are not touched.\n\nRestricted to Administrators.", "summary": "Update a fee structure", "tags": [ "Fee structures" ], "parameters": [ { "name": "feeStructure", "in": "path", "required": true, "description": "The fee structure ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateFeeStructureRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/FeeStructureResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Fee structure updated." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "feeStructure.destroy", "description": "Invoices generated from it are unaffected \u2014 they hold their own\ncopy of the lines.\n\nRestricted to Administrators.", "summary": "Delete a fee structure", "tags": [ "Fee structures" ], "parameters": [ { "name": "feeStructure", "in": "path", "required": true, "description": "The fee structure ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Fee structure deleted." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/fee-structures\/{feeStructure}\/duplicate": { "post": { "operationId": "feeStructure.duplicate", "description": "Copies the template and all its rows to another term, grade or\nyear \u2014 the usual way to start a new term from last term's fees\nrather than a blank sheet.\n\nRestricted to Administrators.", "summary": "Duplicate a fee structure", "tags": [ "Fee structures" ], "parameters": [ { "name": "feeStructure", "in": "path", "required": true, "description": "The fee structure ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/DuplicateFeeStructureRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/FeeStructureResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Fee structure duplicated." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/finance\/ledger": { "get": { "operationId": "ledger.index", "description": "`summary` is the headline: invoiced, received, refunded, collected\n(received less refunds), outstanding, and how many learners are in\narrears. `movements` is every payment and refund, newest first,\nwith `signed_amount` negative for money going out.\n\nFilter by `term_id`, `academic_year_id`, `grade_id`,\n`class_section_id`, `student_id`, `from`, `to`, `method`, `type`.\n\nEvery figure is derived from invoice charges and payments.\nArrears carried onto a document are never counted here \u2014 the\ninvoices that raised them are already in these sums, so counting\nthe carried figure too would inflate outstanding every term.\n\nRestricted to Administrators.", "summary": "Money in and out", "tags": [ "Finance ledger" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "currency": { "type": "string" }, "invoiced": { "type": "number" }, "received": { "type": "number" }, "refunded": { "type": "number" }, "collected": { "type": "number" }, "outstanding": { "type": "number" }, "collection_rate": { "type": [ "number", "null" ] }, "invoice_count": { "type": "integer", "minimum": 0 }, "learners_in_arrears": { "type": "integer", "minimum": 0 } }, "required": [ "currency", "invoiced", "received", "refunded", "collected", "outstanding", "collection_rate", "invoice_count", "learners_in_arrears" ] }, "movements": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PaymentResource" } } }, "required": [ "summary", "movements" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/finance\/arrears": { "get": { "operationId": "ledger.arrears", "description": "Outstanding balance per learner for the selection, biggest debt\nfirst \u2014 the list a bursar works from.\n\nLearners who have settled in full are left out: this is a chasing\nlist, and in a paid-up class they would be most of it. A learner\nin credit (they paid more than was billed) is kept, because that\nis money the school is holding and someone has to see it.\n\nRestricted to Administrators.", "summary": "Who owes what", "tags": [ "Finance ledger" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "student_id": { "type": "integer" }, "full_name": { "type": [ "string", "null" ] }, "admission_number": { "type": [ "string", "null" ] }, "class_display_name": { "type": [ "string", "null" ] }, "invoiced": { "type": "number" }, "paid": { "type": "number" }, "balance": { "type": "number" } }, "required": [ "student_id", "full_name", "admission_number", "class_display_name", "invoiced", "paid", "balance" ] }, { "type": "string" } ] } }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/finance\/statements\/{student}": { "get": { "operationId": "ledger.statement", "description": "Every invoice and every payment in date order with a running\nbalance, the way a bank statement reads.\n\nRestricted to Administrators.", "summary": "A learner's statement of account", "tags": [ "Finance ledger" ], "parameters": [ { "name": "student", "in": "path", "required": true, "description": "The student ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "student": { "type": "object", "properties": { "id": { "type": "integer" }, "full_name": { "type": "string" }, "admission_number": { "type": "string" }, "class_display_name": { "type": "string" }, "guardian": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "name", "phone" ] } }, "required": [ "id", "full_name", "admission_number", "class_display_name", "guardian" ] }, "currency": { "type": "string" }, "entries": { "type": "array", "items": { "type": "string" } }, "totals": { "type": "object", "properties": { "invoiced": { "type": "number" }, "paid": { "type": "number" }, "balance": { "type": "number" } }, "required": [ "invoiced", "paid", "balance" ] } }, "required": [ "student", "currency", "entries", "totals" ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/finance\/statements\/{student}\/download": { "get": { "operationId": "ledger.downloadStatement", "description": "Restricted to Administrators.", "summary": "Download a statement of account", "tags": [ "Finance ledger" ], "parameters": [ { "name": "student", "in": "path", "required": true, "description": "The student ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object" } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/grades": { "get": { "operationId": "grade.index", "description": "Returns grades, optionally filtered to a single academic year via\nthe `academic_year_id` query parameter. Each grade includes its\nstreams and the streamless ClassSection (when it has no streams).\n\nRestricted to Administrators.", "summary": "List grades", "tags": [ "Grades" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/GradeResource" }, { "type": "object", "required": [ "academic_year", "streams", "class_section" ] } ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "grade.store", "description": "Creates a single grade level (e.g. \"Grade 1\") within an academic\nyear. A grade level can only exist once per academic year.\n\nCreating a grade automatically generates its streamless\nClassSection \u2014 the class students attach to until\/unless streams\nare added.\n\nRestricted to Administrators.", "summary": "Create a grade", "tags": [ "Grades" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreGradeRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/GradeResource" }, { "type": "object", "required": [ "academic_year", "streams", "class_section" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Grade created successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/grades\/bulk": { "post": { "operationId": "grade.bulkStore", "description": "Creates multiple grades in one request, e.g. setting up an entire\nacademic year's grade levels at once. Each row is validated as if\ncreated individually \u2014 duplicate (academic_year_id, level) pairs,\nwhether within the payload or already in the database, are\nrejected and none of the rows are created.\n\nEach created grade still triggers its own streamless ClassSection,\nexactly as a single `POST \/grades` would.\n\nRestricted to Administrators.", "summary": "Bulk create grades", "tags": [ "Grades" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/BulkStoreGradeRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/GradeResource" } }, "meta": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/grades\/{grade}": { "get": { "operationId": "grade.show", "description": "Returns a single grade with its streams and streamless ClassSection.\n\nRestricted to Administrators.", "summary": "View a grade", "tags": [ "Grades" ], "parameters": [ { "name": "grade", "in": "path", "required": true, "description": "The grade ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/GradeResource" }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "grade.update", "description": "Updates the grade's level, name, or academic year. Changing the\nlevel is still subject to the same per-academic-year uniqueness\nrule as creation.\n\nRestricted to Administrators.", "summary": "Update a grade", "tags": [ "Grades" ], "parameters": [ { "name": "grade", "in": "path", "required": true, "description": "The grade ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateGradeRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/GradeResource" }, { "type": "object", "required": [ "academic_year", "streams", "class_section" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Grade updated successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "grade.destroy", "description": "Deletes the grade along with its streams and ClassSection(s),\nwhich cascade-delete via foreign key constraints.\n\nRestricted to Administrators.", "summary": "Delete a grade", "tags": [ "Grades" ], "parameters": [ { "name": "grade", "in": "path", "required": true, "description": "The grade ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Grade deleted successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/invoices": { "get": { "operationId": "invoice.index", "description": "Filter by `term_id`, `grade_id`, `class_section_id`, `student_id`,\n`status`, and `search` (invoice number, learner name or admission\nnumber).\n\nEach row carries `subtotal` (this invoice's own charges),\n`amount_paid` and `balance`. `brought_forward` is what was\noutstanding when the invoice was issued \u2014 it is printed on the\ndocument so the parent sees a true total, but it must never be\nsummed into a balance: the arrears it describes belong to the\nearlier invoices that raised them.\n\nRestricted to Administrators.", "summary": "List invoices", "tags": [ "Invoices" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/InvoiceResource" }, { "type": "object", "required": [ "student", "term", "class_display_name", "items", "payments" ] } ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "invoice.store", "description": "With a `student_id` and no `items`, the lines are taken from the\nfee structure that applies to that learner's grade and term \u2014 most\nspecific wins. Send `items` to override them, or to bill a\nnon-learner recipient (a tender, a hall hire) by giving\n`recipient_name` instead of a learner.\n\nRestricted to Administrators.", "summary": "Raise a single invoice", "tags": [ "Invoices" ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreInvoiceRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/InvoiceResource" }, { "type": "object", "required": [ "student", "term", "class_display_name", "items", "payments" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/invoices\/students": { "post": { "operationId": "invoice.generateForStudents", "description": "The posted rows are a snapshot of the template after any manual\nedits. Existing live invoices for the term are returned separately\nso a single selection can open the existing invoice instead of\ncreating a duplicate.", "summary": "Raise invoices for one or more specifically selected learners", "tags": [ "Invoices" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/GenerateStudentInvoicesRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/invoices\/bulk": { "post": { "operationId": "invoice.bulkGenerate", "description": "Every active learner currently enrolled there is billed from the\nfee structure that applies to them. Runs synchronously \u2014 creating\ninvoice rows is cheap database work, so there is no queue to wait\non and no job that can sit pending.\n\nSafe to run twice: a learner who already has a live invoice for\nthe same term is skipped rather than billed again, and the\nresponse reports how many were skipped.\n\nRestricted to Administrators.", "summary": "Raise invoices for a whole grade or class", "tags": [ "Invoices" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/BulkGenerateInvoicesRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/InvoiceResource" }, { "type": "object", "required": [ "student", "term", "class_display_name", "items", "payments" ] } ] } }, "meta": { "type": "object", "properties": { "message": { "type": "string" }, "created": { "type": "integer", "minimum": 0 }, "skipped": { "type": "string" }, "existing": { "type": "integer", "minimum": 0 }, "existing_invoice_ids": { "type": "array", "items": {} } }, "required": [ "message", "created", "skipped", "existing", "existing_invoice_ids" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/invoices\/download": { "get": { "operationId": "invoice.downloadBatch", "description": "Takes the same filters as `GET \/invoices` and renders every match\ninto a single document, one page each \u2014 the whole class printed in\none pass at the start of term.\n\nRestricted to Administrators.", "summary": "Download many invoices as one PDF", "tags": [ "Invoices" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object" } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "errors": { "type": "array", "prefixItems": [ { "type": "string", "const": "No invoices match this selection." } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/invoices\/{invoice}": { "get": { "operationId": "invoice.show", "description": "Restricted to Administrators.", "summary": "Get an invoice", "tags": [ "Invoices" ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "description": "The invoice ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/InvoiceResource" }, { "type": "object", "required": [ "student", "term", "class_display_name", "items", "payments" ] } ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "invoice.update", "description": "Sending `items` replaces the whole list, so a row can be added,\nre-priced, reordered or removed for this one learner without\ntouching the fee structure or anybody else's invoice. The total\nand status are recomputed server-side and returned \u2014 the response\nis authoritative.\n\nRestricted to Administrators.", "summary": "Edit an invoice", "tags": [ "Invoices" ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "description": "The invoice ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateInvoiceRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/InvoiceResource" }, { "type": "object", "required": [ "student", "term", "class_display_name", "items", "payments" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Invoice updated." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/invoices\/{invoice}\/cancel": { "post": { "operationId": "invoice.cancel", "description": "A cancelled invoice leaves every balance and ledger total but is\nkept for the record. An invoice with payments against it cannot be\ncancelled \u2014 refund them first, otherwise the money would vanish\nfrom the ledger while the school still holds it.\n\nRestricted to Administrators.", "summary": "Cancel an invoice", "tags": [ "Invoices" ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "description": "The invoice ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/InvoiceResource" }, { "type": "object", "required": [ "student", "term", "class_display_name", "items", "payments" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Invoice cancelled." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/invoices\/{invoice}\/download": { "get": { "operationId": "invoice.download", "description": "Restricted to Administrators.", "summary": "Download an invoice as a PDF", "tags": [ "Invoices" ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "description": "The invoice ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object" } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/marks": { "get": { "operationId": "mark.index", "description": "Returns every mark recorded for a given `exam_subject_id` \u2014 the\nfull class list with scores for one subject's sitting of one\nexam.\n\nRestricted to Administrators.", "summary": "List marks for an exam subject", "tags": [ "Marks" ], "parameters": [ { "name": "exam_subject_id", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/MarkResource" } }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "mark.store", "description": "Records a single student's score against one exam subject.\nRejected with a `422` if: the exam subject has no `out_of` set\nyet, the score exceeds `out_of`, the student is excluded from\nthe subject, or a mark already exists for this student on this\nexam subject (use `PUT \/marks\/{mark}` to correct an existing\nmark instead).\n\nAdministrators, or a teacher for the classes they are assigned.", "summary": "Record a mark", "tags": [ "Marks" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreMarkRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/MarkResource" }, { "type": "object", "required": [ "student" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Mark recorded successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/marks\/bulk": { "post": { "operationId": "mark.bulkStore", "description": "Records marks for many students against the SAME exam subject in\none request \u2014 the realistic shape of classroom mark entry: pick\nthe exam + subject once, then key in scores for the whole class.\nThe whole batch is validated up front; if any row would exceed\n`out_of`, target an excluded student, or duplicate an existing\nmark, the entire request is rejected with a `422` and nothing is\ncreated.\n\nFor entering marks via spreadsheet instead of typing into the UI\nrow by row, see `GET \/marks\/roster\/{examSubject}` and\n`POST \/marks\/import`.\n\nAdministrators, or a teacher for the classes they are assigned.", "summary": "Bulk record marks", "tags": [ "Marks" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/BulkStoreMarkRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/MarkResource" } }, "meta": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/marks\/import": { "post": { "operationId": "mark.import", "description": "Accepts an uploaded `.xlsx`\/`.xls`\/`.csv` file (multipart field\n`file`) plus `exam_subject_id`, parses it, and bulk-creates marks\nfor every row that resolves to a real student \u2014 built for the\nteacher who finds it faster to fill in scores in Excel offline\nthan to use the in-app entry screen.\n\n**Expected sheet layout** (header row is skipped automatically):\n\n| Column A | Column B | Column C |\n|---|---|---|\n| admission_number | full_name (display only, ignored on import) | score |\n| AC012 | Jane Doe | 78 |\n| AC013 | John Smith | 45 |\n\nThis is the same layout returned by `GET \/marks\/roster\/{examSubject}`\n\u2014 the intended flow is: fetch the roster, build a spreadsheet\nfrom it client-side (or let the teacher export\/print it), the\nteacher fills in the `score` column, then re-uploads that file\nhere unchanged.\n\nEvery parsed row still goes through the exact same validation as\n`POST \/marks\/bulk` \u2014 out_of must be set, scores can't exceed it,\nexcluded students are rejected, duplicates are rejected. A row\nwhose `admission_number` doesn't match any student is skipped\nwith a warning rather than failing the entire import, so one\ntypo doesn't discard an otherwise-valid sheet.\n\nReturns both the marks that were successfully created AND any\nwarnings for rows that were skipped:\n\n```json\n{\n \"data\": {\n \"marks\": [ ... ],\n \"warnings\": [\"No student found with admission number \\\"AC999\\\" \u2014 row skipped.\"]\n }\n}\n```\n\nAdministrators, or a teacher for the classes they are assigned.", "summary": "Import marks from a spreadsheet", "tags": [ "Marks" ], "requestBody": { "required": true, "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/ImportMarksRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "marks": { "type": "array", "items": { "$ref": "#\/components\/schemas\/MarkResource" } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "marks", "warnings" ] }, "meta": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/marks\/roster\/{examSubject}": { "get": { "operationId": "mark.roster", "description": "Returns the exam, subject, and `out_of` context alongside the\nlist of every student eligible to sit this exam subject \u2014 i.e.\ntheir CURRENT class matches the exam's grade, and they are NOT\nexcluded from the subject \u2014 along with any score already\nrecorded for them. This single response has everything a\nfrontend needs to render a complete mark-entry sheet (or\ngenerate an Excel export) without a second call just to look up\nthe exam\/subject's own details:\n\n```json\n{\n \"data\": {\n \"exam\": { \"id\": 5, \"name\": \"Opener\", \"term_id\": 3 },\n \"subject\": { \"id\": 21, \"name\": \"Mathematics\", \"code\": \"G6-MAT\" },\n \"out_of\": 100,\n \"students\": [\n { \"student_id\": 12, \"admission_number\": \"AC012\", \"full_name\": \"Jane Doe\", \"score\": null, \"mark_id\": null },\n { \"student_id\": 13, \"admission_number\": \"AC013\", \"full_name\": \"John Smith\", \"score\": 78, \"mark_id\": 204 }\n ]\n }\n}\n```\n\n`out_of` is `null` if an administrator hasn't set it yet for\nthis exam subject \u2014 the roster still renders in that case, but\nthe frontend should prompt to configure it before allowing\nscore entry, since `POST \/marks` and `POST \/marks\/bulk` will\nreject any mark while it's unset.\n\n`score`\/`mark_id` per student are `null` for students who\nhaven't been marked yet, and populated for students who already\nhave a recorded mark \u2014 so the same endpoint works for both\n\"starting fresh\" and \"reviewing\/correcting an in-progress entry\n * session.\"\n\nPair this with `POST \/marks\/import` to let a teacher download\nthis roster into a spreadsheet (built client-side from this\nJSON), fill in scores offline, then re-upload it as a `.xlsx`\nfile rather than entering marks one row at a time in the UI.\n\nAdministrators, or a teacher for the classes they are assigned.", "summary": "Get the mark entry roster for an exam subject", "tags": [ "Marks" ], "parameters": [ { "name": "examSubject", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "exam": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "term_id": { "type": "integer" } }, "required": [ "id", "name", "term_id" ] }, "subject": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": "string" } }, "required": [ "id", "name", "code" ] }, "out_of": { "type": [ "integer", "null" ] }, "uses_default_out_of": { "type": "boolean" }, "default_out_of": { "type": "integer" }, "students": { "type": "array", "items": { "type": "object", "properties": { "student_id": { "type": "integer" }, "admission_number": { "type": "string" }, "full_name": { "type": "string" }, "score": { "type": [ "number", "null" ] }, "mark_id": { "type": [ "string", "null" ] } }, "required": [ "student_id", "admission_number", "full_name", "score", "mark_id" ] } } }, "required": [ "exam", "subject", "out_of", "uses_default_out_of", "default_out_of", "students" ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/marks\/students\/{student}": { "get": { "operationId": "mark.forStudent", "description": "Returns every mark recorded for a given student across every\nexam subject they've sat \u2014 used for a student's own results\nview.\n\nRestricted to Administrators.", "summary": "List marks for a student", "tags": [ "Marks" ], "parameters": [ { "name": "student", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/MarkResource" } }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/marks\/{mark}": { "put": { "operationId": "mark.update", "description": "Corrects an existing mark's score.\n\nAdministrators, or a teacher for the classes they are assigned.", "summary": "Update a mark", "tags": [ "Marks" ], "parameters": [ { "name": "mark", "in": "path", "required": true, "description": "The mark ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "score": { "type": "number", "minimum": 0 } }, "required": [ "score" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/MarkResource" }, { "type": "object", "required": [ "student" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Mark updated successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "delete": { "operationId": "mark.destroy", "description": "Removes a recorded mark entirely.\n\nAdministrators, or a teacher for the classes they are assigned.", "summary": "Delete a mark", "tags": [ "Marks" ], "parameters": [ { "name": "mark", "in": "path", "required": true, "description": "The mark ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Mark deleted successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/invoices\/{invoice}\/payments": { "post": { "operationId": "payment.store", "description": "Money received against an invoice. The invoice status is\nrecalculated \u2014 issued, part paid, or paid \u2014 and the updated\ninvoice comes back with the receipt so the caller never has to\nrefetch to know the new balance.\n\nPayments are never edited or deleted afterwards: a receipt has\nalready been handed over by the time a mistake is noticed, and\nrewriting history behind a receipt someone is holding is worse\nthan the mistake. Correct it with a refund carrying a note.\n\nRestricted to Administrators.", "summary": "Record a payment", "tags": [ "Payments" ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "description": "The invoice ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StorePaymentRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "payment": { "$ref": "#\/components\/schemas\/PaymentResource" }, "invoice": { "$ref": "#\/components\/schemas\/InvoiceResource" } }, "required": [ "payment", "invoice" ] }, "meta": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/invoices\/{invoice}\/refunds": { "post": { "operationId": "payment.refund", "description": "Money given back against an invoice. Cannot exceed what has been\nreceived on it, counting any earlier refunds.\n\nRestricted to Administrators.", "summary": "Record a refund", "tags": [ "Payments" ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "description": "The invoice ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StorePaymentRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "payment": { "$ref": "#\/components\/schemas\/PaymentResource" }, "invoice": { "$ref": "#\/components\/schemas\/InvoiceResource" } }, "required": [ "payment", "invoice" ] }, "meta": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/payments\/{payment}\/receipt": { "get": { "operationId": "payment.download", "description": "A refund prints the same document with the direction spelled out,\nso the parent has a record of money handed back too.\n\nRestricted to Administrators.", "summary": "Download a receipt", "tags": [ "Payments" ], "parameters": [ { "name": "payment", "in": "path", "required": true, "description": "The payment ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object" } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards": { "get": { "operationId": "reportCard.index", "description": "Restricted to Administrators.", "summary": "Returns report cards, filterable by `term_id`, `class_section_id`,\nor `status`. Useful for an admin dashboard showing \"which\n * students' report cards are done, pending, or failed.\"", "tags": [ "Report Cards" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ReportCardResource" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/files\/catalog": { "get": { "operationId": "reportCard.fileCatalog", "tags": [ "Report Cards" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "file_count": { "type": "integer" }, "size_bytes": { "type": "integer" }, "stale_count": { "type": "integer" }, "provisional_count": { "type": "integer" }, "latest_generated_at": { "type": "string" } }, "required": [ "file_count", "size_bytes", "stale_count", "provisional_count", "latest_generated_at" ] }, "years": { "type": "string" } }, "required": [ "summary", "years" ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/files": { "get": { "operationId": "reportCard.files", "tags": [ "Report Cards" ], "parameters": [ { "name": "academic_year_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "term_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "scope_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ReportCardFileResource" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/runs": { "get": { "operationId": "reportCard.generationRuns", "tags": [ "Report Cards" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "scope": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "label": { "type": "string" }, "term_id": { "type": "integer" }, "exam_series_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "type", "label", "term_id", "exam_series_id" ] }, "grade": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "display_name" ] }, "requested_by": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "policy": { "type": "string" }, "status": { "type": "string" }, "batch_id": { "type": [ "string", "null" ] }, "counts": { "type": "object", "properties": { "total": { "type": "integer" }, "eligible": { "type": "integer" }, "skipped": { "type": "integer" }, "pending": { "type": "integer" }, "processing": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "superseded": { "type": "integer" }, "provisional": { "type": "integer" } }, "required": [ "total", "eligible", "skipped", "pending", "processing", "completed", "failed", "superseded", "provisional" ] }, "failure_summary": { "type": "string", "description": "This is a reason => count map. Casting guarantees an empty map is\nencoded as `{}` instead of PHP's ambiguous empty JSON array `[]`." }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "student": { "type": "object", "properties": { "id": { "type": "integer" }, "admission_number": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "admission_number", "name" ] }, "report_card_id": { "type": [ "integer", "null" ] }, "eligible": { "type": "boolean" }, "missing_marks": { "type": "array", "items": {} }, "status": { "type": "string" }, "failure_reason": { "type": [ "string", "null" ] }, "generated_version": { "type": [ "integer", "null" ] }, "generation_token": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "student", "report_card_id", "eligible", "missing_marks", "status", "failure_reason", "generated_version", "generation_token", "started_at", "finished_at" ] } } }, "required": [ "id", "scope", "grade", "requested_by", "policy", "status", "batch_id", "counts", "failure_summary", "started_at", "finished_at", "created_at", "items" ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/runs\/{run}": { "get": { "operationId": "reportCard.generationRun", "tags": [ "Report Cards" ], "parameters": [ { "name": "run", "in": "path", "required": true, "description": "The run ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "scope": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "label": { "type": "string" }, "term_id": { "type": "integer" }, "exam_series_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "type", "label", "term_id", "exam_series_id" ] }, "grade": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "display_name" ] }, "requested_by": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "policy": { "type": "string" }, "status": { "type": "string" }, "batch_id": { "type": [ "string", "null" ] }, "counts": { "type": "object", "properties": { "total": { "type": "integer" }, "eligible": { "type": "integer" }, "skipped": { "type": "integer" }, "pending": { "type": "integer" }, "processing": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "superseded": { "type": "integer" }, "provisional": { "type": "integer" } }, "required": [ "total", "eligible", "skipped", "pending", "processing", "completed", "failed", "superseded", "provisional" ] }, "failure_summary": { "type": "string", "description": "This is a reason => count map. Casting guarantees an empty map is\nencoded as `{}` instead of PHP's ambiguous empty JSON array `[]`." }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "student": { "type": "object", "properties": { "id": { "type": "integer" }, "admission_number": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "admission_number", "name" ] }, "report_card_id": { "type": [ "integer", "null" ] }, "eligible": { "type": "boolean" }, "missing_marks": { "type": "array", "items": {} }, "status": { "type": "string" }, "failure_reason": { "type": [ "string", "null" ] }, "generated_version": { "type": [ "integer", "null" ] }, "generation_token": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "student", "report_card_id", "eligible", "missing_marks", "status", "failure_reason", "generated_version", "generation_token", "started_at", "finished_at" ] } } }, "required": [ "id", "scope", "grade", "requested_by", "policy", "status", "batch_id", "counts", "failure_summary", "started_at", "finished_at", "created_at", "items" ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/runs\/{run}\/retry": { "post": { "operationId": "reportCard.retryGenerationRun", "tags": [ "Report Cards" ], "parameters": [ { "name": "run", "in": "path", "required": true, "description": "The run ID", "schema": { "type": "integer" } } ], "responses": { "202": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "batch_id": { "type": [ "string", "null" ] }, "run_id": { "type": "integer" }, "total": { "type": "string" }, "scope_id": { "type": "integer" }, "scope_type": { "type": "string" }, "policy": { "type": "string" }, "eligible": { "type": "integer" }, "provisional": { "type": "integer" }, "skipped": { "type": "integer" }, "reused": { "type": "boolean" } }, "required": [ "batch_id", "run_id", "total", "scope_id", "scope_type", "policy", "eligible", "provisional", "skipped", "reused" ] }, "meta": { "type": "object", "properties": { "message": { "type": "string" }, "poll_url": { "type": "string" } }, "required": [ "message", "poll_url" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/batch\/{batchId}": { "get": { "operationId": "reportCard.batchStatus", "description": "Returns how many jobs are pending, processed, and failed in a\ngiven batch. Poll this endpoint after triggering a bulk generate\nto show a progress bar \u2014 stop polling when `finished` is `true`.\n\nRestricted to Administrators.", "summary": "Poll a bulk generation batch's progress", "tags": [ "Report Cards" ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total": { "type": "string" }, "pending": { "type": "string" }, "processed": { "type": "integer" }, "failed": { "type": "string" }, "finished": { "type": "boolean" } }, "required": [ "total", "pending", "processed", "failed", "finished" ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/students\/{student}\/terms\/{term}": { "post": { "operationId": "reportCard.generateForStudent", "description": "Creates (or resets) the report card record to `pending` and\ndispatches a queued PDF-generation job. Returns immediately \u2014\nthe actual PDF is generated in the background. Poll\n`GET \/api\/v1\/report-cards\/{reportCard}` to check status.\n\nRequires term results to already be computed for this student\n(call `POST \/api\/v1\/results\/terms\/{term}\/compute` first). If no term\nresult exists, the job fails with a clear error message.\n\nRestricted to Administrators.", "summary": "Generate a single student's report card", "tags": [ "Report Cards" ], "parameters": [ { "name": "student", "in": "path", "required": true, "description": "The student ID", "schema": { "type": "integer" } }, { "name": "term", "in": "path", "required": true, "description": "The term ID", "schema": { "type": "integer" } } ], "responses": { "202": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ReportCard" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Report card queued for generation." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "422": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "errors": { "type": "string" } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/exam-series\/{examSeries}\/preview": { "get": { "operationId": "reportCard.previewExamSeries", "tags": [ "Report Cards" ], "parameters": [ { "name": "examSeries", "in": "path", "required": true, "description": "The exam series ID", "schema": { "type": "integer" } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "scope": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "label": { "type": "string" }, "term_id": { "type": "integer" }, "exam_series_id": { "type": [ "integer", "null" ] }, "grade_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "type", "label", "term_id", "exam_series_id", "grade_id" ] }, "ready": { "type": "string" }, "can_generate_eligible": { "type": "string" }, "can_generate_all": { "type": "string" }, "summary": { "type": "object", "properties": { "total_learners": { "type": "integer", "minimum": 0 }, "eligible_learners": { "type": "integer", "minimum": 0 }, "blocked_learners": { "type": "integer", "minimum": 0 }, "missing_marks": { "type": "string" }, "hard_blockers": { "type": "integer", "minimum": 0 } }, "required": [ "total_learners", "eligible_learners", "blocked_learners", "missing_marks", "hard_blockers" ] }, "structural_blockers": { "type": "array", "items": { "type": "string" } }, "eligible_learners": { "type": "array", "items": { "type": "object", "properties": { "student_id": { "type": "integer" }, "admission_number": { "type": "string" }, "student_name": { "type": "string" }, "grade_id": { "type": "integer" }, "grade_name": { "type": "string" }, "class_section_id": { "type": "integer" }, "class_name": { "type": "string" }, "expected_marks": { "type": "integer" }, "entered_marks": { "type": "string" }, "missing_marks_count": { "type": "integer", "minimum": 0 }, "eligible": { "type": "string" }, "missing_marks": { "type": "array", "items": { "type": "string" } } }, "required": [ "student_id", "admission_number", "student_name", "grade_id", "grade_name", "class_section_id", "class_name", "expected_marks", "entered_marks", "missing_marks_count", "eligible", "missing_marks" ] } }, "blocked_learners": { "type": "array", "items": { "type": "object", "properties": { "student_id": { "type": "integer" }, "admission_number": { "type": "string" }, "student_name": { "type": "string" }, "grade_id": { "type": "integer" }, "grade_name": { "type": "string" }, "class_section_id": { "type": "integer" }, "class_name": { "type": "string" }, "expected_marks": { "type": "integer" }, "entered_marks": { "type": "string" }, "missing_marks_count": { "type": "integer", "minimum": 0 }, "eligible": { "type": "string" }, "missing_marks": { "type": "array", "items": { "type": "string" } } }, "required": [ "student_id", "admission_number", "student_name", "grade_id", "grade_name", "class_section_id", "class_name", "expected_marks", "entered_marks", "missing_marks_count", "eligible", "missing_marks" ] } }, "learners": { "type": "array", "items": { "type": "object", "properties": { "student_id": { "type": "integer" }, "admission_number": { "type": "string" }, "student_name": { "type": "string" }, "grade_id": { "type": "integer" }, "grade_name": { "type": "string" }, "class_section_id": { "type": "integer" }, "class_name": { "type": "string" }, "expected_marks": { "type": "integer" }, "entered_marks": { "type": "string" }, "missing_marks_count": { "type": "integer", "minimum": 0 }, "eligible": { "type": "string" }, "missing_marks": { "type": "array", "items": { "type": "string" } } }, "required": [ "student_id", "admission_number", "student_name", "grade_id", "grade_name", "class_section_id", "class_name", "expected_marks", "entered_marks", "missing_marks_count", "eligible", "missing_marks" ] } } }, "required": [ "scope", "ready", "can_generate_eligible", "can_generate_all", "summary", "structural_blockers", "eligible_learners", "blocked_learners", "learners" ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/exam-series\/{examSeries}\/bulk": { "post": { "operationId": "reportCard.bulkGenerateForExamSeries", "description": "The Exams UI exposes Opener, Midterm and Endterm as school-wide\nseries. Individual Exam rows are only their grade sittings and must\nnot leak into the report-card workflow as duplicate choices.", "summary": "Generate one assessment across every grade, or one selected grade", "tags": [ "Report Cards" ], "parameters": [ { "name": "examSeries", "in": "path", "required": true, "description": "The exam series ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "grade_id": { "type": [ "integer", "null" ] }, "policy": { "type": [ "string", "null" ], "enum": [ "eligible_only", "include_incomplete", null ] } } } } } }, "responses": { "202": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "message": { "type": "string" }, "poll_url": { "type": "string" } }, "required": [ "message", "poll_url" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/exams\/{exam}\/bulk": { "post": { "operationId": "reportCard.bulkGenerateForExam", "description": "Automatically recomputes exam results and term results first,\nthen dispatches one PDF-generation job per eligible student in\nthe exam's grade. Returns a `batch_id` immediately \u2014 use\n`GET \/api\/v1\/report-cards\/batch\/{batchId}` to poll progress.\n\nThis is the \"generate all with one click\" action \u2014 generating\n40 PDFs asynchronously in the background rather than blocking\nthe HTTP request.\n\nRestricted to Administrators.", "summary": "Bulk generate report cards for a whole exam's grade", "tags": [ "Report Cards" ], "parameters": [ { "name": "exam", "in": "path", "required": true, "description": "The exam ID", "schema": { "type": "integer" } } ], "responses": { "202": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "message": { "type": "string" }, "poll_url": { "type": "string" } }, "required": [ "message", "poll_url" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "422": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "errors": { "type": "string" } }, "required": [ "data", "meta", "errors" ] }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "meta": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "errors": { "type": "array", "prefixItems": [ { "type": "string" } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/terms\/{term}\/preview": { "get": { "operationId": "reportCard.previewTerm", "tags": [ "Report Cards" ], "parameters": [ { "name": "term", "in": "path", "required": true, "description": "The term ID", "schema": { "type": "integer" } }, { "name": "grade_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "scope": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "label": { "type": "string" }, "term_id": { "type": "integer" }, "exam_series_id": { "type": [ "integer", "null" ] }, "grade_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "type", "label", "term_id", "exam_series_id", "grade_id" ] }, "ready": { "type": "string" }, "can_generate_eligible": { "type": "string" }, "can_generate_all": { "type": "string" }, "summary": { "type": "object", "properties": { "total_learners": { "type": "integer", "minimum": 0 }, "eligible_learners": { "type": "integer", "minimum": 0 }, "blocked_learners": { "type": "integer", "minimum": 0 }, "missing_marks": { "type": "string" }, "hard_blockers": { "type": "integer", "minimum": 0 } }, "required": [ "total_learners", "eligible_learners", "blocked_learners", "missing_marks", "hard_blockers" ] }, "structural_blockers": { "type": "array", "items": { "type": "string" } }, "eligible_learners": { "type": "array", "items": { "type": "object", "properties": { "student_id": { "type": "integer" }, "admission_number": { "type": "string" }, "student_name": { "type": "string" }, "grade_id": { "type": "integer" }, "grade_name": { "type": "string" }, "class_section_id": { "type": "integer" }, "class_name": { "type": "string" }, "expected_marks": { "type": "integer" }, "entered_marks": { "type": "string" }, "missing_marks_count": { "type": "integer", "minimum": 0 }, "eligible": { "type": "string" }, "missing_marks": { "type": "array", "items": { "type": "string" } } }, "required": [ "student_id", "admission_number", "student_name", "grade_id", "grade_name", "class_section_id", "class_name", "expected_marks", "entered_marks", "missing_marks_count", "eligible", "missing_marks" ] } }, "blocked_learners": { "type": "array", "items": { "type": "object", "properties": { "student_id": { "type": "integer" }, "admission_number": { "type": "string" }, "student_name": { "type": "string" }, "grade_id": { "type": "integer" }, "grade_name": { "type": "string" }, "class_section_id": { "type": "integer" }, "class_name": { "type": "string" }, "expected_marks": { "type": "integer" }, "entered_marks": { "type": "string" }, "missing_marks_count": { "type": "integer", "minimum": 0 }, "eligible": { "type": "string" }, "missing_marks": { "type": "array", "items": { "type": "string" } } }, "required": [ "student_id", "admission_number", "student_name", "grade_id", "grade_name", "class_section_id", "class_name", "expected_marks", "entered_marks", "missing_marks_count", "eligible", "missing_marks" ] } }, "learners": { "type": "array", "items": { "type": "object", "properties": { "student_id": { "type": "integer" }, "admission_number": { "type": "string" }, "student_name": { "type": "string" }, "grade_id": { "type": "integer" }, "grade_name": { "type": "string" }, "class_section_id": { "type": "integer" }, "class_name": { "type": "string" }, "expected_marks": { "type": "integer" }, "entered_marks": { "type": "string" }, "missing_marks_count": { "type": "integer", "minimum": 0 }, "eligible": { "type": "string" }, "missing_marks": { "type": "array", "items": { "type": "string" } } }, "required": [ "student_id", "admission_number", "student_name", "grade_id", "grade_name", "class_section_id", "class_name", "expected_marks", "entered_marks", "missing_marks_count", "eligible", "missing_marks" ] } } }, "required": [ "scope", "ready", "can_generate_eligible", "can_generate_all", "summary", "structural_blockers", "eligible_learners", "blocked_learners", "learners" ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/terms\/{term}\/bulk": { "post": { "operationId": "reportCard.bulkGenerateForTerm", "description": "Same as the exam-level bulk generate, but covers every grade\nthat has exams in the given term. Useful for an end-of-term\nschool-wide report card run.\n\nRestricted to Administrators.", "summary": "Bulk generate report cards for a whole term", "tags": [ "Report Cards" ], "parameters": [ { "name": "term", "in": "path", "required": true, "description": "The term ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "grade_id": { "type": [ "integer", "null" ] }, "policy": { "type": [ "string", "null" ], "enum": [ "eligible_only", "include_incomplete", null ] } } } } } }, "responses": { "202": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "batch_id": { "type": [ "string", "null" ] }, "run_id": { "type": "integer" }, "total": { "type": "string" }, "scope_id": { "type": "integer" }, "scope_type": { "type": "string" }, "policy": { "type": "string" }, "eligible": { "type": "integer" }, "provisional": { "type": "integer" }, "skipped": { "type": "integer" }, "reused": { "type": "boolean" } }, "required": [ "batch_id", "run_id", "total", "scope_id", "scope_type", "policy", "eligible", "provisional", "skipped", "reused" ] }, "meta": { "type": "object", "properties": { "message": { "type": "string" }, "poll_url": { "type": "string" } }, "required": [ "message", "poll_url" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/{reportCard}": { "get": { "operationId": "reportCard.show", "description": "Returns the current status (`pending`, `processing`, `done`,\n`failed`) and, once done, the frozen snapshot data (subject\nlines, totals, ranks). Does not return the PDF itself \u2014 use\n`GET \/report-cards\/{reportCard}\/download` for the PDF file.\n\nRestricted to Administrators.", "summary": "View a report card's status and data", "tags": [ "Report Cards" ], "parameters": [ { "name": "reportCard", "in": "path", "required": true, "description": "The report card ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/ReportCardResource" }, { "type": "object", "required": [ "scope", "student", "term", "classSection", "subjects" ] } ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/{reportCard}\/download": { "get": { "operationId": "reportCard.download", "description": "Redirects to a short-lived signed R2 URL (or streams the file from\nlocal storage in development). Returns `404` if the report card\nhasn't been generated yet, and `410` if its file is still held by\na storage provider the application no longer uses \u2014 it must be\nmigrated or regenerated.\n\nRestricted to Administrators.", "summary": "Download a report card PDF", "tags": [ "Report Cards" ], "parameters": [ { "name": "reportCard", "in": "path", "required": true, "description": "The report card ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "410": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "errors": { "type": "string" } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/report-cards\/{reportCard}\/subjects\/{subject}\/comment": { "patch": { "operationId": "reportCard.updateSubjectComment", "description": "Sets or updates the teacher's written comment for one subject\nline on an already-generated report card. After updating\ncomments, re-trigger generation to produce a fresh PDF with the\ncomments included.\n\nRestricted to Administrators.", "summary": "Update a subject's teacher comment", "tags": [ "Report Cards" ], "parameters": [ { "name": "reportCard", "in": "path", "required": true, "description": "The report card ID", "schema": { "type": "integer" } }, { "name": "subject", "in": "path", "required": true, "description": "The subject ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "teacher_comment": { "type": "string", "maxLength": 500 } }, "required": [ "teacher_comment" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ReportCardSubjectResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Teacher comment updated." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/results\/exams\/{exam}\/compute": { "post": { "operationId": "results.computeExam", "description": "Computes (or recomputes) the results for every student who has\nmarks in the given exam \u2014 totals, averages, performance levels,\nstream rank, and grade rank. Safe to call multiple times; each\ncall overwrites the previous result with fresh data from the\ncurrent marks. Call this after all marks for an exam have been\nentered, or again after any corrections.\n\nRestricted to Administrators.", "summary": "Compute exam results", "tags": [ "Results" ], "parameters": [ { "name": "exam", "in": "path", "required": true, "description": "The exam ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ExamResultResource" } }, "meta": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "422": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "meta": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "errors": { "type": "array", "prefixItems": [ { "type": "string" } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/results\/terms\/{term}\/compute": { "post": { "operationId": "results.computeTerm", "description": "Computes (or recomputes) the term summary results for every\nstudent who has exam results in any include_in_report_card exam\nfor this term. Subject scores are averaged across those exams.\nFirst validates that every included exam has a maximum mark and\na mark for every eligible learner in every subject, then refreshes\nall included exam results automatically before building the term.\n\nRestricted to Administrators.", "summary": "Compute term results", "tags": [ "Results" ], "parameters": [ { "name": "term", "in": "path", "required": true, "description": "The term ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TermResultResource" } }, "meta": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "422": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "errors": { "type": "string" } }, "required": [ "data", "meta", "errors" ] }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "meta": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "errors": { "type": "array", "prefixItems": [ { "type": "string" } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/results\/exams\/{exam}\/readiness": { "get": { "operationId": "results.examReadiness", "tags": [ "Results" ], "parameters": [ { "name": "exam", "in": "path", "required": true, "description": "The exam ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "term_id": { "type": "integer" }, "ready": { "type": "boolean" }, "summary": { "type": "object", "properties": { "included_exams": { "type": "integer", "minimum": 0 }, "ready_exams": { "type": "integer", "minimum": 0 }, "missing_out_of_subjects": { "type": "integer" }, "missing_marks": { "type": "integer" } }, "required": [ "included_exams", "ready_exams", "missing_out_of_subjects", "missing_marks" ] }, "exams": { "type": "array", "items": { "type": "object", "properties": { "exam_id": { "type": "integer" }, "term_id": { "type": "integer" }, "name": { "type": "string" }, "grade_id": { "type": "integer" }, "grade_name": { "type": "string" }, "ready": { "type": "string" }, "computed": { "type": "boolean" }, "computed_at": { "type": [ "string", "null" ] }, "subjects": { "type": "array", "items": { "type": "object", "properties": { "exam_subject_id": { "type": "integer" }, "subject_id": { "type": "integer" }, "subject_name": { "type": "string" }, "out_of": { "type": [ "integer", "null" ] }, "eligible_students": { "type": "integer", "minimum": 0 }, "marks_entered": { "type": "integer", "minimum": 0 }, "missing_marks": { "type": [ "object", "null" ] }, "ready": { "type": "string" } }, "required": [ "exam_subject_id", "subject_id", "subject_name", "out_of", "eligible_students", "marks_entered", "missing_marks", "ready" ] } } }, "required": [ "exam_id", "term_id", "name", "grade_id", "grade_name", "ready", "computed", "computed_at", "subjects" ] } } }, "required": [ "term_id", "ready", "summary", "exams" ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/results\/terms\/{term}\/readiness": { "get": { "operationId": "results.termReadiness", "tags": [ "Results" ], "parameters": [ { "name": "term", "in": "path", "required": true, "description": "The term ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "term_id": { "type": "integer" }, "ready": { "type": "boolean" }, "summary": { "type": "object", "properties": { "included_exams": { "type": "integer", "minimum": 0 }, "ready_exams": { "type": "integer", "minimum": 0 }, "missing_out_of_subjects": { "type": "integer" }, "missing_marks": { "type": "integer" } }, "required": [ "included_exams", "ready_exams", "missing_out_of_subjects", "missing_marks" ] }, "exams": { "type": "array", "items": { "type": "object", "properties": { "exam_id": { "type": "integer" }, "term_id": { "type": "integer" }, "name": { "type": "string" }, "grade_id": { "type": "integer" }, "grade_name": { "type": "string" }, "ready": { "type": "string" }, "computed": { "type": "boolean" }, "computed_at": { "type": [ "string", "null" ] }, "subjects": { "type": "array", "items": { "type": "object", "properties": { "exam_subject_id": { "type": "integer" }, "subject_id": { "type": "integer" }, "subject_name": { "type": "string" }, "out_of": { "type": [ "integer", "null" ] }, "eligible_students": { "type": "integer", "minimum": 0 }, "marks_entered": { "type": "integer", "minimum": 0 }, "missing_marks": { "type": [ "object", "null" ] }, "ready": { "type": "string" } }, "required": [ "exam_subject_id", "subject_id", "subject_name", "out_of", "eligible_students", "marks_entered", "missing_marks", "ready" ] } } }, "required": [ "exam_id", "term_id", "name", "grade_id", "grade_name", "ready", "computed", "computed_at", "subjects" ] } } }, "required": [ "term_id", "ready", "summary", "exams" ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/results\/exams\/{exam}": { "get": { "operationId": "results.examResults", "description": "Returns computed exam results for a given exam, optionally\nfiltered to a specific class section via `class_section_id`.\nOrdered by grade_rank ascending. Use `?class_section_id=X` to\nview results for one stream only, or omit it to see the full\ngrade-wide results list.\n\nRestricted to Administrators.", "summary": "View exam results \u2014 by grade", "tags": [ "Results" ], "parameters": [ { "name": "exam", "in": "path", "required": true, "description": "The exam ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ExamResultResource" } }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/results\/terms\/{term}": { "get": { "operationId": "results.termResults", "description": "Returns computed term results for a given term, optionally\nfiltered to a specific class section via `class_section_id`.\nOrdered by grade_rank ascending.\n\nRestricted to Administrators.", "summary": "View term results \u2014 by grade", "tags": [ "Results" ], "parameters": [ { "name": "term", "in": "path", "required": true, "description": "The term ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TermResultResource" } }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/results\/exams\/{exam}\/students\/{student}": { "get": { "operationId": "results.studentExamResult", "description": "Returns one student's result for a specific exam, including\ntheir per-subject scores, performance levels, points, and rank.\n\nRestricted to Administrators.", "summary": "View a student's exam result", "tags": [ "Results" ], "parameters": [ { "name": "exam", "in": "path", "required": true, "description": "The exam ID", "schema": { "type": "integer" } }, { "name": "student", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ExamResultResource" }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/results\/terms\/{term}\/students\/{student}": { "get": { "operationId": "results.studentTermResult", "description": "Returns one student's term summary, including averaged subject\nscores, performance levels, points, and rank.\n\nRestricted to Administrators.", "summary": "View a student's term result", "tags": [ "Results" ], "parameters": [ { "name": "term", "in": "path", "required": true, "description": "The term ID", "schema": { "type": "integer" } }, { "name": "student", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/TermResultResource" }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/my-teaching": { "get": { "operationId": "teachingAssignment.mine", "description": "The signed-in teacher's own classes and the marks they still owe\nfor the term (default: the current term).", "summary": "My marking progress", "tags": [ "Staff" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "term": { "type": "object", "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "display_name" ] }, "summary": { "type": "object", "properties": { "assignments": { "type": "integer", "minimum": 0 }, "exams": { "type": "string" }, "missing_marks": { "type": "string" } }, "required": [ "assignments", "exams", "missing_marks" ] }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "grade_id": { "type": "integer" }, "class_section": { "type": "object", "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "display_name" ] }, "subject": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "learners": { "type": "integer", "minimum": 0 }, "missing_count": { "type": "string" }, "exams": { "type": "array", "items": { "type": [ "object", "null" ], "properties": { "exam_id": { "type": "integer" }, "exam_name": { "type": "string" }, "exam_subject_id": { "type": "integer" }, "include_in_report_card": { "type": "boolean" }, "eligible": { "type": "integer", "minimum": 0 }, "entered": { "type": "string" }, "missing_count": { "type": "integer", "minimum": 0 }, "missing": { "type": "array", "items": { "type": "object", "properties": { "student_id": { "type": "integer" }, "admission_number": { "type": "string" }, "full_name": { "type": "string" } }, "required": [ "student_id", "admission_number", "full_name" ] } } }, "required": [ "exam_id", "exam_name", "exam_subject_id", "include_in_report_card", "eligible", "entered", "missing_count", "missing" ] } } }, "required": [ "id", "grade_id", "class_section", "subject", "learners", "missing_count", "exams" ] } } }, "required": [ "term", "summary", "assignments" ] }, { "type": "object", "properties": { "term": { "type": "null" }, "summary": { "type": "object", "properties": { "assignments": { "type": "integer", "minimum": 0 }, "exams": { "type": "string" }, "missing_marks": { "type": "string" } }, "required": [ "assignments", "exams", "missing_marks" ] }, "assignments": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "term", "summary", "assignments" ] } ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/teaching-assignments\/copy": { "post": { "operationId": "teachingAssignment.copy", "description": "Rolls every assignment of `from_term_id` into `to_term_id` \u2014 or only\none teacher's, with `user_id`. Into a new academic year each class\nis matched by grade level and stream. Existing assignments in the\ntarget term are never overwritten; what could not be copied comes\nback in `skipped`.\n\nRestricted to Administrators.", "summary": "Copy teaching assignments into another term", "tags": [ "Staff" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CopyTeachingAssignmentsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "copied": { "type": "integer" }, "skipped": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "copied", "skipped" ] }, "meta": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/staff": { "get": { "operationId": "staff.index", "description": "Every account holding at least one staff role. Filter with\n`search` (name, email or phone), `role` and `is_active`.\n\nRestricted to Administrators.", "summary": "List staff", "tags": [ "Staff" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "role", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "admin", "head_teacher", "deputy_head_teacher", "dean", "teacher", "bursar", "secretary", null ] } }, { "name": "is_active", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/UserResource" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" }, "roles": { "type": "array", "prefixItems": [ { "type": "string", "const": "admin" }, { "type": "string", "const": "head_teacher" }, { "type": "string", "const": "deputy_head_teacher" }, { "type": "string", "const": "dean" }, { "type": "string", "const": "teacher" }, { "type": "string", "const": "bursar" }, { "type": "string", "const": "secretary" } ], "minItems": 7, "maxItems": 7, "additionalItems": false } }, "required": [ "current_page", "last_page", "total", "roles" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "staff.store", "description": "Creates a login for them with the given password and roles. A staff\nmember may hold several roles; only `admin` and `teacher` grant\naccess to the application.\n\nRestricted to Administrators.", "summary": "Add a staff member", "tags": [ "Staff" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreStaffRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/UserResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Staff member added." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/staff\/{staff}": { "get": { "operationId": "staff.show", "description": "Restricted to Administrators.", "summary": "View a staff member", "tags": [ "Staff" ], "parameters": [ { "name": "staff", "in": "path", "required": true, "description": "The staff ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/UserResource" }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "staff.update", "description": "Deactivating an account or resetting its password signs it out\neverywhere. An administrator cannot deactivate or demote themselves,\nso the school always keeps at least one active administrator.\n\nRestricted to Administrators.", "summary": "Update a staff member", "tags": [ "Staff" ], "parameters": [ { "name": "staff", "in": "path", "required": true, "description": "The staff ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateStaffRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/UserResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Staff member updated." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "staff.destroy", "description": "Only for an account added by mistake \u2014 anyone with teaching history\nor recorded marks is refused with a `422`; deactivate them instead.\n\nRestricted to Administrators.", "summary": "Delete a staff member", "tags": [ "Staff" ], "parameters": [ { "name": "staff", "in": "path", "required": true, "description": "The staff ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Staff member deleted." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/staff\/{staff}\/assignments": { "get": { "operationId": "teachingAssignment.index", "description": "Pass `term_id` for one term; without it every term is returned.\n\nRestricted to Administrators.", "summary": "List a staff member's teaching assignments", "tags": [ "Staff" ], "parameters": [ { "name": "staff", "in": "path", "required": true, "description": "The staff ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TeachingAssignmentResource" } }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "teachingAssignment.store", "description": "Gives the teacher one subject in one or more classes for a term.\nRefused with a `422` when a class does not offer the subject, is\nnot in the term's academic year, or already has that subject taught\nby someone else \u2014 reassigning means removing the other teacher's\nassignment first.\n\nRestricted to Administrators.", "summary": "Assign a subject to a teacher", "tags": [ "Staff" ], "parameters": [ { "name": "staff", "in": "path", "required": true, "description": "The staff ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreTeachingAssignmentRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TeachingAssignmentResource" } }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Teaching assignment saved." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/staff\/{staff}\/assignments\/{assignment}": { "delete": { "operationId": "teachingAssignment.destroy", "description": "Restricted to Administrators.", "summary": "Remove a teaching assignment", "tags": [ "Staff" ], "parameters": [ { "name": "staff", "in": "path", "required": true, "description": "The staff ID", "schema": { "type": "integer" } }, { "name": "assignment", "in": "path", "required": true, "description": "The assignment ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Teaching assignment removed." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/staff\/{staff}\/marking": { "get": { "operationId": "teachingAssignment.marking", "description": "For each of their classes and subjects in the term (default: the\ncurrent term), every exam and the learners whose mark is still\nmissing.\n\nRestricted to Administrators.", "summary": "A staff member's marking progress", "tags": [ "Staff" ], "parameters": [ { "name": "staff", "in": "path", "required": true, "description": "The staff ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "term": { "type": "object", "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "display_name" ] }, "summary": { "type": "object", "properties": { "assignments": { "type": "integer", "minimum": 0 }, "exams": { "type": "string" }, "missing_marks": { "type": "string" } }, "required": [ "assignments", "exams", "missing_marks" ] }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "grade_id": { "type": "integer" }, "class_section": { "type": "object", "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "display_name" ] }, "subject": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "learners": { "type": "integer", "minimum": 0 }, "missing_count": { "type": "string" }, "exams": { "type": "array", "items": { "type": [ "object", "null" ], "properties": { "exam_id": { "type": "integer" }, "exam_name": { "type": "string" }, "exam_subject_id": { "type": "integer" }, "include_in_report_card": { "type": "boolean" }, "eligible": { "type": "integer", "minimum": 0 }, "entered": { "type": "string" }, "missing_count": { "type": "integer", "minimum": 0 }, "missing": { "type": "array", "items": { "type": "object", "properties": { "student_id": { "type": "integer" }, "admission_number": { "type": "string" }, "full_name": { "type": "string" } }, "required": [ "student_id", "admission_number", "full_name" ] } } }, "required": [ "exam_id", "exam_name", "exam_subject_id", "include_in_report_card", "eligible", "entered", "missing_count", "missing" ] } } }, "required": [ "id", "grade_id", "class_section", "subject", "learners", "missing_count", "exams" ] } } }, "required": [ "term", "summary", "assignments" ] }, { "type": "object", "properties": { "term": { "type": "null" }, "summary": { "type": "object", "properties": { "assignments": { "type": "integer", "minimum": 0 }, "exams": { "type": "string" }, "missing_marks": { "type": "string" } }, "required": [ "assignments", "exams", "missing_marks" ] }, "assignments": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "term", "summary", "assignments" ] } ] }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/streams": { "get": { "operationId": "stream.index", "description": "Returns streams, optionally filtered to a single grade via the\n`grade_id` query parameter.\n\nRestricted to Administrators.", "summary": "List streams", "tags": [ "Streams" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/StreamResource" }, { "type": "object", "required": [ "grade", "class_section" ] } ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "stream.store", "description": "Creates a stream (free-text name, e.g. \"Blue\", \"A\") within a\ngrade. A stream name can only exist once within the same grade \u2014\nthe same name can be reused across different grades.\n\nCreating a stream automatically generates its ClassSection \u2014 the\nclass students attach to for this specific stream.\n\nRestricted to Administrators.", "summary": "Create a stream", "tags": [ "Streams" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreStreamRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/StreamResource" }, { "type": "object", "required": [ "grade", "class_section" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Stream created successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/streams\/bulk": { "post": { "operationId": "stream.bulkStore", "description": "Creates multiple streams in one request, e.g. setting up all\nstreams for a grade at once. Each row is validated as if created\nindividually \u2014 duplicate (grade_id, name) pairs, whether within\nthe payload or already in the database, are rejected and none of\nthe rows are created.\n\nEach created stream still triggers its own ClassSection, exactly\nas a single `POST \/streams` would.\n\nRestricted to Administrators.", "summary": "Bulk create streams", "tags": [ "Streams" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/BulkStoreStreamRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/StreamResource" } }, "meta": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/streams\/{stream}": { "get": { "operationId": "stream.show", "description": "Returns a single stream with its grade and ClassSection.\n\nRestricted to Administrators.", "summary": "View a stream", "tags": [ "Streams" ], "parameters": [ { "name": "stream", "in": "path", "required": true, "description": "The stream ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/StreamResource" }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "stream.update", "description": "Updates the stream's name or grade. Changing the name is still\nsubject to the same per-grade uniqueness rule as creation.\n\nRestricted to Administrators.", "summary": "Update a stream", "tags": [ "Streams" ], "parameters": [ { "name": "stream", "in": "path", "required": true, "description": "The stream ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateStreamRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/StreamResource" }, { "type": "object", "required": [ "grade", "class_section" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Stream updated successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "stream.destroy", "description": "Deletes the stream along with its ClassSection, which\ncascade-deletes via foreign key constraint.\n\nNote: deleting a grade's last remaining stream does not currently\nrecreate that grade's streamless ClassSection automatically \u2014 this\nis a known gap, not yet handled by an event listener.\n\nRestricted to Administrators.", "summary": "Delete a stream", "tags": [ "Streams" ], "parameters": [ { "name": "stream", "in": "path", "required": true, "description": "The stream ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Stream deleted successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/medical-records\/students": { "get": { "operationId": "studentMedicalRecord.students", "tags": [ "Student Medical Records" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "admission_number": { "type": "string" }, "full_name": { "type": "string" }, "current_class": { "type": "string" }, "medical_summary": { "type": "object", "properties": { "state": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "none" ] } ] }, "active_records": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] } }, "required": [ "state", "active_records" ] } }, "required": [ "id", "admission_number", "full_name", "current_class", "medical_summary" ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/students\/{student}\/medical-records": { "get": { "operationId": "studentMedicalRecord.index", "tags": [ "Student Medical Records" ], "parameters": [ { "name": "student", "in": "path", "required": true, "description": "The student ID", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "student": { "type": "object", "properties": { "id": { "type": "integer" }, "admission_number": { "type": "string" }, "full_name": { "type": "string" } }, "required": [ "id", "admission_number", "full_name" ] }, "summary": { "type": "object", "properties": { "state": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "none" ] } ] }, "active_records": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] } }, "required": [ "state", "active_records" ] }, "records": { "type": "array", "items": { "$ref": "#\/components\/schemas\/StudentMedicalRecordResource" } } }, "required": [ "student", "summary", "records" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "studentMedicalRecord.store", "tags": [ "Student Medical Records" ], "parameters": [ { "name": "student", "in": "path", "required": true, "description": "The student ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/StoreStudentMedicalRecordRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/StudentMedicalRecordResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Medical record added successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/medical-records\/{medicalRecord}": { "patch": { "operationId": "studentMedicalRecord.update", "tags": [ "Student Medical Records" ], "parameters": [ { "name": "medicalRecord", "in": "path", "required": true, "description": "The medical record ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/UpdateStudentMedicalRecordRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/StudentMedicalRecordResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Medical record updated successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "studentMedicalRecord.destroy", "tags": [ "Student Medical Records" ], "parameters": [ { "name": "medicalRecord", "in": "path", "required": true, "description": "The medical record ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Medical record removed successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/medical-records\/{medicalRecord}\/download": { "get": { "operationId": "studentMedicalRecord.download", "tags": [ "Student Medical Records" ], "parameters": [ { "name": "medicalRecord", "in": "path", "required": true, "description": "The medical record ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Transfer-Encoding": { "required": true, "schema": { "type": "string", "enum": [ "chunked" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/students": { "get": { "operationId": "student.index", "description": "Returns students, optionally filtered to a single ClassSection\nvia the `class_section_id` query parameter. Each student\nincludes their current class enrollment.\n\nRestricted to Administrators.", "summary": "List students", "tags": [ "Students" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/StudentResource" }, { "type": "object", "required": [ "current_class" ] } ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "student.store", "description": "Creates a student and immediately enrolls them into a class for\nthe given academic year as their first current enrollment. The\nclass is specified as `grade_id` + optional `stream_id` \u2014 not a\nraw `class_section_id` \u2014 since picking \"Grade 6, Blue stream\" is\nhow an admin actually thinks about it. `stream_id` is required\nif the chosen grade has streams, and must be omitted if it\ndoesn't; the service resolves these into the actual ClassSection.\n\n`admission_number` is generated automatically \u2014 never accepted\nfrom the client \u2014 as a global sequential value, e.g. `AC001`,\n`AC002`. It does not reset per year and can never be changed\nonce assigned, even across promotions.\n\nRestricted to Administrators.", "summary": "Create a student", "tags": [ "Students" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreStudentRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/StudentResource" }, { "type": "object", "required": [ "current_class" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Student created successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/students\/{student}": { "get": { "operationId": "student.show", "description": "Returns a single student with their current class enrollment and\nsubject exclusions. Pass `?with_effective_subjects=1` to also\ninclude the computed list of subjects this student actually\ntakes (their grade's full subject list, minus exclusions) \u2014\nomitted by default since it requires extra queries.\n\nRestricted to Administrators.", "summary": "View a student", "tags": [ "Students" ], "parameters": [ { "name": "student", "in": "path", "required": true, "description": "The student ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/StudentResource" }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "student.update", "description": "Updates bio\/guardian fields only (name, date of birth, gender,\nguardian contact). Class section changes are NOT handled here \u2014\nuse `POST \/students\/{student}\/change-class` instead, since\nswitching a student's class is a meaningful event with its own\nstatus and date, not a plain field update.\n\nRestricted to Administrators.", "summary": "Update a student", "tags": [ "Students" ], "parameters": [ { "name": "student", "in": "path", "required": true, "description": "The student ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateStudentRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/StudentResource" }, { "type": "object", "required": [ "current_class" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Student updated successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "student.destroy", "description": "Sets `is_active` to `false` rather than deleting the record \u2014\npreserves the student's enrollment history (and, later, their\nmarks history) for reporting purposes. There is currently no\nhard-delete endpoint for students.\n\nRestricted to Administrators.", "summary": "Deactivate a student", "tags": [ "Students" ], "parameters": [ { "name": "student", "in": "path", "required": true, "description": "The student ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Student deactivated successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/students\/{student}\/change-class": { "post": { "operationId": "student.changeClass", "description": "Moves the student to a different ClassSection \u2014 either a routine\npromotion into a new academic year, or a mid-year stream\/class\nchange within the same academic year. The target class is\nspecified as `grade_id` + optional `stream_id`, the same shape\nas `POST \/students` \u2014 not a raw `class_section_id`. Closes the\nexisting current enrollment (marking it with the given `status`,\ndefault \"promoted\", and today's date as `left_on`) and opens a\nnew current enrollment for the target class\/year, atomically.\n\nRestricted to Administrators.", "summary": "Change a student's class", "tags": [ "Students" ], "parameters": [ { "name": "student", "in": "path", "required": true, "description": "The student ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ChangeClassRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/StudentResource" }, { "type": "object", "required": [ "current_class" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Student class changed successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/students\/{student}\/subjects\/exclude": { "post": { "operationId": "student.excludeSubject", "description": "Removes the given subject from the student's otherwise-automatic\nfull grade subject list. The subject must belong to the\nstudent's CURRENT grade \u2014 excluding an unrelated subject is\nrejected with a `422`. Excluding an already-excluded subject is\na no-op, not an error.\n\nRestricted to Administrators.", "summary": "Exclude a student from a subject", "tags": [ "Students" ], "parameters": [ { "name": "student", "in": "path", "required": true, "description": "The student ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/StudentResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Student excluded from subject successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/students\/{student}\/subjects\/{subject}\/exclude": { "delete": { "operationId": "student.includeSubject", "description": "Removes an existing exclusion, restoring the subject to the\nstudent's default (grade-wide) subject list. A no-op if the\nstudent wasn't excluded from this subject to begin with.\n\nRestricted to Administrators.", "summary": "Re-include a student in a subject", "tags": [ "Students" ], "parameters": [ { "name": "student", "in": "path", "required": true, "description": "The student ID", "schema": { "type": "integer" } }, { "name": "subject", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/StudentResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Student re-included in subject successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/subjects": { "get": { "operationId": "subject.index", "description": "Returns the subject catalog. Subjects are global \u2014 the same\nsubject can be attached to several grades at once, rather than\nbeing duplicated per grade. Pass `grade_id` to scope the list (and\neach subject's `grades` entry) to subjects attached to that grade.\n\nRestricted to Administrators.", "summary": "List subjects", "tags": [ "Subjects" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/SubjectResource" }, { "type": "object", "required": [ "grades" ] } ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "subject.store", "description": "Creates a subject (Learning Area) in the shared catalog. The\nsubject's `code` is generated automatically \u2014 never accepted from\nthe client. If the first 3 letters of the name collide with an\nexisting code, the system automatically widens to 4, 5, or more\nletters until a unique code is found.\n\nOptionally pass `grade_ids` to immediately attach the new subject\nto one or more grades in the same call, all sharing the same\nperformance-level band thresholds (default 75% \/ 50% \/ 30%). If\nomitted, the subject is created unattached and can be applied to\ngrades later via `POST \/subjects\/{subject}\/grades`.\n\nRestricted to Administrators.", "summary": "Create a subject", "tags": [ "Subjects" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreSubjectRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/SubjectResource" }, { "type": "object", "required": [ "grades" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Subject created successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/subjects\/merge": { "post": { "operationId": "subject.merge", "description": "Re-points every grade attachment, exam subject (and its marks),\nexclusion, and materialised result row from each subject in\n`duplicate_subject_ids` onto `primary_subject_id`, then deletes\nthe now-unreferenced duplicates. Everything happens in one\ntransaction \u2014 a full success or no change at all.\n\nRejected with a `422`, with nothing changed, if the same exam\nalready has marks recorded under both the primary and a\nduplicate \u2014 that means real marks exist under both names for the\nsame sitting, which has to be resolved by a human before the\nmerge can proceed.\n\nRestricted to Administrators.", "summary": "Merge duplicate subjects into one canonical subject", "tags": [ "Subjects" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/MergeSubjectsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/SubjectResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Subjects merged successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/subjects\/{subject}": { "get": { "operationId": "subject.show", "description": "Returns a single subject with every grade it's attached to and\nthat grade's performance-level band thresholds.\n\nRestricted to Administrators.", "summary": "View a subject", "tags": [ "Subjects" ], "parameters": [ { "name": "subject", "in": "path", "required": true, "description": "The subject ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/SubjectResource" }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "subject.update", "description": "Updates the subject's name. `code` is immutable. Band thresholds\nare per-grade \u2014 use `PUT \/subjects\/{subject}\/grades\/{grade}`.\n\nRestricted to Administrators.", "summary": "Update a subject", "tags": [ "Subjects" ], "parameters": [ { "name": "subject", "in": "path", "required": true, "description": "The subject ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateSubjectRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/SubjectResource" }, { "type": "object", "required": [ "grades" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Subject updated successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "subject.destroy", "description": "Deletes the subject everywhere it's attached, along with its\ngrade attachments, ExamSubject rows, and any marks recorded\nagainst it, which cascade-delete via foreign key constraints.\n\nRestricted to Administrators.", "summary": "Delete a subject", "tags": [ "Subjects" ], "parameters": [ { "name": "subject", "in": "path", "required": true, "description": "The subject ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Subject deleted successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/subjects\/{subject}\/grades": { "post": { "operationId": "subject.attachToGrades", "description": "Attaches an already-existing subject to one or more additional\ngrades in one call, all sharing the same band thresholds. This is\nwhat auto-provisions ExamSubject rows into that grade's existing\nexams, matching what happens when a subject is attached at\ncreation time.\n\nRestricted to Administrators.", "summary": "Apply a subject to more grades", "tags": [ "Subjects" ], "parameters": [ { "name": "subject", "in": "path", "required": true, "description": "The subject ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/AttachSubjectToGradesRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/SubjectResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Subject attached to grade(s) successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/subjects\/{subject}\/grades\/{grade}": { "put": { "operationId": "subject.updateGradeBands", "description": "Restricted to Administrators.", "summary": "Update a subject's band thresholds for one grade", "tags": [ "Subjects" ], "parameters": [ { "name": "subject", "in": "path", "required": true, "description": "The subject ID", "schema": { "type": "integer" } }, { "name": "grade", "in": "path", "required": true, "description": "The grade ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateGradeSubjectBandsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/SubjectResource" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Band thresholds updated successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "subject.detachFromGrade", "description": "Rejected with a `422` if marks have already been recorded for\nthis subject in this grade \u2014 detaching would orphan real academic\ndata. The subject itself, and its attachment to other grades, is\nunaffected.\n\nRestricted to Administrators.", "summary": "Detach a subject from a grade", "tags": [ "Subjects" ], "parameters": [ { "name": "subject", "in": "path", "required": true, "description": "The subject ID", "schema": { "type": "integer" } }, { "name": "grade", "in": "path", "required": true, "description": "The grade ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Subject detached from grade successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/terms": { "get": { "operationId": "term.index", "description": "Returns terms, optionally filtered to a single academic year via\nthe `academic_year_id` query parameter.\n\nRestricted to Administrators.", "summary": "List terms", "tags": [ "Terms" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/TermResource" }, { "type": "object", "required": [ "academic_year" ] } ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "total" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "term.store", "description": "Creates a term (1, 2, or 3) within an academic year, with\noptional start\/end dates. A term number can only exist once per\nacademic year.\n\n`is_current` cannot be set here \u2014 marking a term current is a\nseparate action (not yet implemented in this controller) that\nalso needs to keep the parent academic year's current flag in\nsync.\n\nRestricted to Administrators.", "summary": "Create a term", "tags": [ "Terms" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreTermRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/TermResource" }, { "type": "object", "required": [ "academic_year" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Term created successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/terms\/{term}": { "get": { "operationId": "term.show", "description": "Returns a single term with its academic year.\n\nRestricted to Administrators.", "summary": "View a term", "tags": [ "Terms" ], "parameters": [ { "name": "term", "in": "path", "required": true, "description": "The term ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/TermResource" }, "meta": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "term.update", "description": "Updates the term's number, dates, or academic year. Changing the\nnumber is still subject to the same per-academic-year uniqueness\nrule as creation. `is_current` cannot be changed through this\nendpoint.\n\nRestricted to Administrators.", "summary": "Update a term", "tags": [ "Terms" ], "parameters": [ { "name": "term", "in": "path", "required": true, "description": "The term ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateTermRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/TermResource" }, { "type": "object", "required": [ "academic_year" ] } ] }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Term updated successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "term.destroy", "description": "Deletes the term. Any assessments attached to it would need their\nown cascade\/restrict rule once Assessments are built \u2014 not yet\nenforced here.\n\nRestricted to Administrators.", "summary": "Delete a term", "tags": [ "Terms" ], "parameters": [ { "name": "term", "in": "path", "required": true, "description": "The term ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "meta": { "type": "object", "properties": { "message": { "type": "string", "const": "Term deleted successfully." } }, "required": [ "message" ] }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data", "meta", "errors" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer", "bearerFormat": "token" } }, "schemas": { "AcademicYearResource": { "type": "object", "properties": { "id": { "type": "integer" }, "year": { "type": "integer" }, "starts_on": { "type": [ "string", "null" ] }, "ends_on": { "type": [ "string", "null" ] }, "is_current": { "type": "boolean" }, "grades": { "type": "array", "items": { "$ref": "#\/components\/schemas\/GradeResource" } }, "terms": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TermResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "year", "starts_on", "ends_on", "is_current", "created_at", "updated_at" ], "title": "AcademicYearResource" }, "AttachSubjectToGradesRequest": { "type": "object", "properties": { "grade_ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "uniqueItems": true }, "ee_min_percentage": { "type": "integer", "minimum": 0, "maximum": 100 }, "me_min_percentage": { "type": "integer", "minimum": 0, "maximum": 100 }, "ae_min_percentage": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "grade_ids" ], "title": "AttachSubjectToGradesRequest" }, "BulkGenerateInvoicesRequest": { "type": "object", "properties": { "grade_id": { "type": "integer" }, "class_section_id": { "type": [ "integer", "null" ] }, "term_id": { "type": "integer" }, "fee_structure_id": { "type": [ "integer", "null" ] }, "issue_date": { "type": [ "string", "null" ], "format": "date-time" }, "due_date": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 } }, "required": [ "grade_id", "term_id" ], "title": "BulkGenerateInvoicesRequest" }, "BulkSetExamOutOfRequest": { "type": "object", "properties": { "out_of": { "type": "integer", "minimum": 1, "maximum": 1000 }, "overwrite_existing": { "type": "boolean" } }, "required": [ "out_of" ], "title": "BulkSetExamOutOfRequest" }, "BulkStoreGradeRequest": { "type": "object", "properties": { "grades": { "type": "array", "items": { "type": "object", "properties": { "academic_year_id": { "type": "integer" }, "level": { "type": "integer", "minimum": 1, "maximum": 12 }, "name": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "academic_year_id", "level" ] }, "minItems": 1 } }, "required": [ "grades" ], "title": "BulkStoreGradeRequest" }, "BulkStoreMarkRequest": { "type": "object", "properties": { "exam_subject_id": { "type": "integer" }, "marks": { "type": "array", "items": { "type": "object", "properties": { "student_id": { "type": "integer" }, "score": { "type": "number", "minimum": 0 } }, "required": [ "student_id", "score" ] }, "minItems": 1, "uniqueItems": true } }, "required": [ "exam_subject_id", "marks" ], "title": "BulkStoreMarkRequest" }, "BulkStoreStreamRequest": { "type": "object", "properties": { "streams": { "type": "array", "items": { "type": "object", "properties": { "grade_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 } }, "required": [ "grade_id", "name" ] }, "minItems": 1 } }, "required": [ "streams" ], "title": "BulkStoreStreamRequest" }, "ChangeClassRequest": { "type": "object", "properties": { "academic_year_id": { "type": "integer" }, "grade_id": { "type": "integer" }, "stream_id": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "promoted", "transferred", "graduated", "withdrawn" ] } }, "required": [ "academic_year_id", "grade_id" ], "title": "ChangeClassRequest" }, "ClassSectionResource": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "grade_id": { "type": "integer" }, "stream_id": { "type": [ "integer", "null" ] }, "has_stream": { "type": "boolean" }, "display_name": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "grade_id", "stream_id", "has_stream", "display_name", "created_at" ], "title": "ClassSectionResource" }, "CopyTeachingAssignmentsRequest": { "type": "object", "properties": { "from_term_id": { "type": "integer" }, "to_term_id": { "type": "integer" }, "user_id": { "type": [ "integer", "null" ] } }, "required": [ "from_term_id", "to_term_id" ], "title": "CopyTeachingAssignmentsRequest" }, "DuplicateFeeStructureRequest": { "type": "object", "properties": { "academic_year_id": { "type": [ "integer", "null" ] }, "grade_id": { "type": [ "integer", "null" ] }, "term_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ], "maxLength": 255 } }, "title": "DuplicateFeeStructureRequest" }, "EmailRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ], "title": "EmailRequest" }, "ExamResource": { "type": "object", "properties": { "id": { "type": "integer" }, "term_id": { "type": "integer" }, "term": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "number", "display_name" ] }, "grade_id": { "type": "integer" }, "grade": { "type": "object", "properties": { "id": { "type": "integer" }, "level": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "level", "display_name" ] }, "name": { "type": "string" }, "include_in_report_card": { "type": "boolean" }, "exam_date": { "type": [ "string", "null" ] }, "exam_subjects": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ExamSubjectResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "term_id", "grade_id", "name", "include_in_report_card", "exam_date", "created_at", "updated_at" ], "title": "ExamResource" }, "ExamResultResource": { "type": "object", "properties": { "id": { "type": "integer" }, "exam_id": { "type": "integer" }, "student_id": { "type": "integer" }, "class_section_id": { "type": "integer" }, "total_marks": { "type": "number" }, "total_out_of": { "type": "number" }, "average_percentage": { "type": "number" }, "total_points": { "type": "integer" }, "grade_rank": { "type": [ "integer", "null" ] }, "stream_rank": { "type": [ "integer", "null" ] }, "computed_at": { "type": [ "string", "null" ], "format": "date-time" }, "student": { "$ref": "#\/components\/schemas\/StudentResource" }, "subjects": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ExamResultSubjectResource" } } }, "required": [ "id", "exam_id", "student_id", "class_section_id", "total_marks", "total_out_of", "average_percentage", "total_points", "grade_rank", "stream_rank", "computed_at" ], "title": "ExamResultResource" }, "ExamResultSubjectResource": { "type": "object", "properties": { "id": { "type": "integer" }, "exam_result_id": { "type": "integer" }, "subject_id": { "type": "integer" }, "score": { "type": "number" }, "out_of": { "type": "number" }, "percentage": { "type": "number" }, "performance_level": { "type": "string" }, "points": { "type": "integer" }, "subject": { "$ref": "#\/components\/schemas\/SubjectResource" } }, "required": [ "id", "exam_result_id", "subject_id", "score", "out_of", "percentage", "performance_level", "points" ], "title": "ExamResultSubjectResource" }, "ExamSeriesResource": { "type": "object", "properties": { "id": { "type": "integer" }, "term_id": { "type": "integer" }, "term": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "number", "display_name" ] }, "name": { "type": "string" }, "include_in_report_card": { "type": "boolean" }, "exam_date": { "type": [ "string", "null" ] }, "default_out_of": { "type": "integer" }, "custom_overrides_count": { "type": "integer", "minimum": 0 }, "custom_overrides": { "type": "array", "items": { "type": "object", "properties": { "exam_subject_id": { "type": "integer" }, "exam_id": { "type": "integer" }, "grade": { "type": "object", "properties": { "id": { "type": "integer" }, "level": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "level", "display_name" ] }, "subject": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "out_of": { "type": "integer" } }, "required": [ "exam_subject_id", "exam_id", "grade", "subject", "out_of" ] } }, "grades_count": { "type": "integer", "minimum": 0 }, "subjects_count": { "type": "string" }, "ready_subjects_count": { "type": "string" }, "grades": { "type": "array", "items": { "type": "object", "properties": { "exam_id": { "type": "integer" }, "grade": { "type": "object", "properties": { "id": { "type": "integer" }, "level": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "level", "display_name" ] }, "subjects_count": { "type": "integer", "minimum": 0 }, "ready_subjects_count": { "type": "integer", "minimum": 0 }, "is_ready": { "type": "string" } }, "required": [ "exam_id", "grade", "subjects_count", "ready_subjects_count", "is_ready" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "term_id", "name", "include_in_report_card", "exam_date", "default_out_of", "custom_overrides_count", "custom_overrides", "grades_count", "subjects_count", "ready_subjects_count", "grades", "created_at", "updated_at" ], "title": "ExamSeriesResource" }, "ExamSubjectResource": { "type": "object", "properties": { "id": { "type": "integer" }, "exam_id": { "type": "integer" }, "subject_id": { "type": "integer" }, "subject": { "$ref": "#\/components\/schemas\/SubjectResource" }, "out_of": { "type": [ "number", "null" ] }, "uses_default_out_of": { "type": "boolean" }, "default_out_of": { "type": "integer" }, "is_ready_for_marks": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "exam_id", "subject_id", "out_of", "uses_default_out_of", "is_ready_for_marks", "created_at" ], "title": "ExamSubjectResource" }, "FeeStructureItemResource": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "amount": { "type": "number" }, "sort_order": { "type": "integer" }, "is_optional": { "type": "boolean" } }, "required": [ "id", "label", "description", "amount", "sort_order", "is_optional" ], "title": "FeeStructureItemResource" }, "FeeStructureResource": { "type": "object", "properties": { "id": { "type": "integer" }, "academic_year_id": { "type": "integer" }, "academic_year": { "type": "object", "properties": { "id": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "id", "year" ] }, "grade_id": { "type": [ "integer", "null" ] }, "grade": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "display_name" ] }, "term_id": { "type": [ "integer", "null" ] }, "term": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "number": { "type": "integer" } }, "required": [ "id", "number" ] }, "name": { "type": "string" }, "currency": { "type": "string" }, "is_active": { "type": "boolean" }, "notes": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "$ref": "#\/components\/schemas\/FeeStructureItemResource" } }, "total": { "type": "number" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "academic_year_id", "grade_id", "term_id", "name", "currency", "is_active", "notes", "created_at", "updated_at" ], "title": "FeeStructureResource" }, "GenerateStudentInvoicesRequest": { "type": "object", "properties": { "student_ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 200, "uniqueItems": true }, "term_id": { "type": "integer" }, "fee_structure_id": { "type": [ "integer", "null" ] }, "issue_date": { "type": [ "string", "null" ], "format": "date-time" }, "due_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "footer_note": { "type": [ "string", "null" ], "maxLength": 2000 }, "items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "quantity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999 }, "unit_amount": { "type": "number", "minimum": 0, "maximum": 99999999.99 } }, "required": [ "label", "unit_amount" ] }, "minItems": 1 } }, "required": [ "student_ids", "term_id", "items" ], "title": "GenerateStudentInvoicesRequest" }, "GradeResource": { "type": "object", "properties": { "id": { "type": "integer" }, "academic_year_id": { "type": "integer" }, "academic_year": { "type": "object", "properties": { "id": { "type": "integer" }, "year": { "type": "integer" }, "is_current": { "type": "boolean" } }, "required": [ "id", "year", "is_current" ] }, "level": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "streams": { "type": "array", "items": { "$ref": "#\/components\/schemas\/StreamResource" } }, "class_section": { "$ref": "#\/components\/schemas\/ClassSectionResource" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "academic_year_id", "level", "name", "display_name", "created_at", "updated_at" ], "title": "GradeResource" }, "ImportMarksRequest": { "type": "object", "properties": { "exam_subject_id": { "type": "integer" }, "file": { "type": "string", "format": "binary", "contentMediaType": "application\/octet-stream", "description": "Maximum file size: 5120 kilobytes." } }, "required": [ "exam_subject_id", "file" ], "title": "ImportMarksRequest" }, "InvoiceItemResource": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unit_amount": { "type": "number" }, "amount": { "type": "number" }, "sort_order": { "type": "integer" } }, "required": [ "id", "label", "description", "quantity", "unit_amount", "amount", "sort_order" ], "title": "InvoiceItemResource" }, "InvoiceResource": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "student_id": { "type": [ "integer", "null" ] }, "student": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "full_name": { "type": "string" }, "admission_number": { "type": "string" }, "guardian_name": { "type": [ "string", "null" ] }, "guardian_phone": { "type": [ "string", "null" ] } }, "required": [ "id", "full_name", "admission_number", "guardian_name", "guardian_phone" ] }, "recipient_name": { "type": [ "string", "null" ] }, "recipient_details": { "type": [ "string", "null" ] }, "term_id": { "type": [ "integer", "null" ] }, "term": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "number": { "type": "integer" } }, "required": [ "id", "number" ] }, "class_section_id": { "type": [ "integer", "null" ] }, "class_display_name": { "type": [ "string", "null" ] }, "issue_date": { "type": "string" }, "due_date": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "subtotal": { "type": "number", "description": "This invoice's own charges only." }, "brought_forward": { "type": "number", "description": "What was outstanding when this invoice was issued.\nPresentation only \u2014 the API never sums it into a balance,\nand neither should a client." }, "total_due_on_document": { "type": "number" }, "amount_paid": { "type": "number" }, "balance": { "type": "number" }, "notes": { "type": [ "string", "null" ] }, "footer_note": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_reason": { "type": [ "string", "null" ] }, "is_editable": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#\/components\/schemas\/InvoiceItemResource" } }, "payments": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PaymentResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "invoice_number", "status", "student_id", "recipient_name", "recipient_details", "term_id", "class_section_id", "issue_date", "due_date", "currency", "subtotal", "brought_forward", "total_due_on_document", "amount_paid", "balance", "notes", "footer_note", "cancelled_at", "cancelled_reason", "is_editable", "created_at", "updated_at" ], "title": "InvoiceResource" }, "LoginRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "device_name": { "type": "string", "maxLength": 255 } }, "required": [ "email", "password", "device_name" ], "title": "LoginRequest" }, "MarkResource": { "type": "object", "properties": { "id": { "type": "integer" }, "exam_subject_id": { "type": "integer" }, "student_id": { "type": "integer" }, "student": { "type": "object", "properties": { "id": { "type": "integer" }, "admission_number": { "type": "string" }, "full_name": { "type": "string" } }, "required": [ "id", "admission_number", "full_name" ] }, "score": { "type": "number" }, "out_of": { "type": [ "integer", "null" ] }, "percentage": { "type": [ "number", "null" ] }, "performance_level": { "type": [ "string", "null" ] }, "points": { "type": [ "string", "null" ] }, "recorded_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "exam_subject_id", "student_id", "score", "out_of", "percentage", "performance_level", "points", "recorded_by", "created_at", "updated_at" ], "title": "MarkResource" }, "MergeSubjectsRequest": { "type": "object", "properties": { "primary_subject_id": { "type": "integer" }, "duplicate_subject_ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "uniqueItems": true } }, "required": [ "primary_subject_id", "duplicate_subject_ids" ], "title": "MergeSubjectsRequest" }, "PaymentResource": { "type": "object", "properties": { "id": { "type": "integer" }, "payment_number": { "type": "string" }, "invoice_id": { "type": "integer" }, "invoice_number": { "type": "string" }, "student_id": { "type": [ "integer", "null" ] }, "student": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "full_name": { "type": "string" }, "admission_number": { "type": "string" } }, "required": [ "id", "full_name", "admission_number" ] }, "type": { "type": "string" }, "amount": { "type": "number" }, "signed_amount": { "type": "number", "description": "Negative for a refund, so a client never has to know the\nsign convention to total a list of movements." }, "paid_on": { "type": "string" }, "method": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "received_by": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "payment_number", "invoice_id", "student_id", "type", "amount", "signed_amount", "paid_on", "method", "reference", "notes", "created_at" ], "title": "PaymentResource" }, "ReportCard": { "type": "object", "properties": { "id": { "type": "integer" }, "student_id": { "type": "integer" }, "term_id": { "type": "integer" }, "report_card_scope_id": { "type": "integer" }, "class_section_id": { "type": "integer" }, "status": { "type": "string" }, "completion_status": { "type": "string" }, "missing_marks": { "type": [ "array", "null" ], "items": {} }, "generation_policy": { "type": [ "string", "null" ] }, "generation_version": { "type": "integer" }, "requested_version": { "type": "integer" }, "generation_token": { "type": [ "string", "null" ] }, "pdf_path": { "type": [ "string", "null" ] }, "storage_provider": { "type": "string" }, "storage_asset_id": { "type": [ "string", "null" ] }, "storage_version": { "type": [ "string", "null" ] }, "pdf_checksum": { "type": [ "string", "null" ] }, "pdf_size": { "type": [ "integer", "null" ] }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "average_marks": { "type": [ "string", "null" ] }, "average_percentage": { "type": [ "string", "null" ] }, "total_points": { "type": [ "integer", "null" ] }, "sub_band_total_points": { "type": [ "string", "null" ] }, "mean_points": { "type": [ "string", "null" ] }, "grade_rank": { "type": [ "integer", "null" ] }, "stream_rank": { "type": [ "integer", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "is_stale": { "type": "boolean" }, "stale_at": { "type": [ "string", "null" ], "format": "date-time" }, "stale_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "student_id", "term_id", "report_card_scope_id", "class_section_id", "status", "completion_status", "missing_marks", "generation_policy", "generation_version", "requested_version", "generation_token", "pdf_path", "storage_provider", "storage_asset_id", "storage_version", "pdf_checksum", "pdf_size", "generated_at", "average_marks", "average_percentage", "total_points", "sub_band_total_points", "mean_points", "grade_rank", "stream_rank", "failure_reason", "is_stale", "stale_at", "stale_reason", "created_at", "updated_at" ], "title": "ReportCard" }, "ReportCardFileResource": { "type": "object", "properties": { "id": { "type": "integer" }, "filename": { "type": "string" }, "download_url": { "type": "string" }, "size_bytes": { "type": [ "integer", "null" ] }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "generation_version": { "type": "integer" }, "completion_status": { "type": "string" }, "is_stale": { "type": "boolean" }, "stale_at": { "type": [ "string", "null" ], "format": "date-time" }, "stale_reason": { "type": [ "string", "null" ] }, "student": { "type": "object", "properties": { "id": { "type": "integer" }, "admission_number": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "admission_number", "name" ] }, "academic_year": { "type": "object", "properties": { "id": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "id", "year" ] }, "term": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "number", "display_name" ] }, "scope": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "label": { "type": "string" }, "exam_series_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "type", "label", "exam_series_id" ] }, "class_section": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" }, "grade": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "display_name" ] } }, "required": [ "id", "display_name", "grade" ] } }, "required": [ "id", "filename", "download_url", "size_bytes", "generated_at", "generation_version", "completion_status", "is_stale", "stale_at", "stale_reason", "student", "academic_year", "term", "scope", "class_section" ], "title": "ReportCardFileResource" }, "ReportCardResource": { "type": "object", "properties": { "id": { "type": "integer" }, "student_id": { "type": "integer" }, "term_id": { "type": "integer" }, "report_card_scope_id": { "type": "integer" }, "scope": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "label": { "type": "string" }, "exam_series_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "type", "label", "exam_series_id" ] }, "class_section_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "completion_status": { "type": "string" }, "missing_marks": { "type": "array", "items": {} }, "generation_policy": { "type": [ "string", "null" ] }, "generation_version": { "type": "integer" }, "requested_version": { "type": "integer" }, "is_generating": { "type": "boolean" }, "pdf_path": { "type": [ "string", "null" ] }, "storage_provider": { "type": "string" }, "pdf_checksum": { "type": [ "string", "null" ] }, "pdf_size": { "type": [ "integer", "null" ] }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "average_marks": { "type": [ "number", "null" ] }, "average_percentage": { "type": [ "number", "null" ] }, "total_points": { "type": [ "integer", "null" ] }, "sub_band_total_points": { "type": [ "number", "null" ] }, "mean_points": { "type": [ "number", "null" ] }, "grade_rank": { "type": [ "integer", "null" ] }, "stream_rank": { "type": [ "integer", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "is_stale": { "type": "boolean" }, "stale_at": { "type": [ "string", "null" ], "format": "date-time" }, "stale_reason": { "type": [ "string", "null" ] }, "student": { "$ref": "#\/components\/schemas\/StudentResource" }, "term": { "$ref": "#\/components\/schemas\/TermResource" }, "classSection": { "type": "object", "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "display_name" ] }, "subjects": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ReportCardSubjectResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "student_id", "term_id", "report_card_scope_id", "class_section_id", "status", "completion_status", "missing_marks", "generation_policy", "generation_version", "requested_version", "is_generating", "pdf_path", "storage_provider", "pdf_checksum", "pdf_size", "generated_at", "average_marks", "average_percentage", "total_points", "sub_band_total_points", "mean_points", "grade_rank", "stream_rank", "failure_reason", "is_stale", "stale_at", "stale_reason", "created_at", "updated_at" ], "title": "ReportCardResource" }, "ReportCardSubjectResource": { "type": "object", "properties": { "id": { "type": "integer" }, "report_card_id": { "type": "integer" }, "subject_id": { "type": [ "integer", "null" ] }, "subject_name": { "type": "string" }, "subject_code": { "type": "string" }, "is_incomplete": { "type": "boolean" }, "missing_components": { "type": "array", "items": {} }, "average_score": { "type": [ "number", "null" ] }, "out_of": { "type": [ "number", "null" ] }, "average_percentage": { "type": [ "number", "null" ] }, "performance_level": { "type": [ "string", "null" ] }, "points": { "type": [ "integer", "null" ] }, "sub_band": { "type": [ "string", "null" ] }, "sub_band_points": { "type": [ "number", "null" ] }, "ee_min_percentage": { "type": [ "number", "null" ] }, "me_min_percentage": { "type": [ "number", "null" ] }, "ae_min_percentage": { "type": [ "number", "null" ] }, "teacher_comment": { "type": [ "string", "null" ] }, "teacher_comment_edited_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "report_card_id", "subject_id", "subject_name", "subject_code", "is_incomplete", "missing_components", "average_score", "out_of", "average_percentage", "performance_level", "points", "sub_band", "sub_band_points", "ee_min_percentage", "me_min_percentage", "ae_min_percentage", "teacher_comment", "teacher_comment_edited_at", "created_at", "updated_at" ], "title": "ReportCardSubjectResource" }, "ResetPasswordRequest": { "type": "object", "properties": { "token": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 }, "password_confirmation": { "type": "string", "minLength": 8 } }, "required": [ "token", "email", "password", "password_confirmation" ], "title": "ResetPasswordRequest" }, "SetExamSubjectOutOfRequest": { "type": "object", "properties": { "out_of": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "out_of" ], "title": "SetExamSubjectOutOfRequest" }, "StoreAcademicYearRequest": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 2000, "maximum": 2100 }, "starts_on": { "type": [ "string", "null" ], "format": "date-time" }, "ends_on": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "year" ], "title": "StoreAcademicYearRequest" }, "StoreExamForGradesRequest": { "type": "object", "properties": { "term_id": { "type": "integer" }, "grade_ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "uniqueItems": true }, "name": { "type": "string", "maxLength": 255 }, "include_in_report_card": { "type": "boolean" }, "exam_date": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "term_id", "grade_ids", "name" ], "title": "StoreExamForGradesRequest" }, "StoreExamRequest": { "type": "object", "properties": { "term_id": { "type": "integer" }, "grade_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "include_in_report_card": { "type": "boolean" }, "exam_date": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "term_id", "grade_id", "name" ], "title": "StoreExamRequest" }, "StoreExamSeriesRequest": { "type": "object", "properties": { "term_id": { "type": "integer" }, "name": { "type": "string", "enum": [ "Opener", "Midterm", "Endterm" ] }, "include_in_report_card": { "type": "boolean" }, "exam_date": { "type": [ "string", "null" ], "format": "date-time" }, "default_out_of": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "term_id", "name" ], "title": "StoreExamSeriesRequest" }, "StoreFeeStructureRequest": { "type": "object", "properties": { "academic_year_id": { "type": "integer" }, "grade_id": { "type": [ "integer", "null" ], "description": "Null means the template applies school-wide." }, "term_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "currency": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 }, "is_active": { "type": [ "boolean", "null" ] }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "items": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "amount": { "type": "number", "description": "Zero is allowed: a template row can be a placeholder the\nadministrator fills in per learner later.", "minimum": 0, "maximum": 99999999.99 }, "is_optional": { "type": [ "boolean", "null" ] } }, "required": [ "label", "amount" ] } } }, "required": [ "academic_year_id", "name" ], "title": "StoreFeeStructureRequest" }, "StoreGradeRequest": { "type": "object", "properties": { "academic_year_id": { "type": "integer" }, "level": { "type": "integer", "minimum": 1, "maximum": 12 }, "name": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "academic_year_id", "level" ], "title": "StoreGradeRequest" }, "StoreInvoiceRequest": { "type": "object", "properties": { "student_id": { "type": [ "integer", "null" ], "description": "Either a learner, or a free-text recipient for a tender or\nhire. withValidator enforces that one of them is present." }, "recipient_name": { "type": [ "string", "null" ], "maxLength": 255 }, "recipient_details": { "type": [ "string", "null" ], "maxLength": 2000 }, "term_id": { "type": [ "integer", "null" ] }, "academic_year_id": { "type": [ "integer", "null" ] }, "fee_structure_id": { "type": [ "integer", "null" ] }, "issue_date": { "type": [ "string", "null" ], "format": "date-time" }, "due_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "footer_note": { "type": [ "string", "null" ], "maxLength": 2000 }, "items": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "quantity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999 }, "unit_amount": { "type": "number", "minimum": 0, "maximum": 99999999.99 } }, "required": [ "label", "unit_amount" ] }, "minItems": 1 } }, "title": "StoreInvoiceRequest" }, "StoreMarkRequest": { "type": "object", "properties": { "exam_subject_id": { "type": "integer" }, "student_id": { "type": "integer" }, "score": { "type": "number", "minimum": 0 } }, "required": [ "exam_subject_id", "student_id", "score" ], "title": "StoreMarkRequest" }, "StorePaymentRequest": { "type": "object", "properties": { "amount": { "type": "number", "description": "Always positive; the endpoint decides payment or refund.", "maximum": 99999999.99 }, "paid_on": { "type": [ "string", "null" ], "format": "date-time" }, "method": { "type": [ "string", "null" ], "enum": [ "cash", "cheque", "bank", "mpesa", "other", null ] }, "reference": { "type": [ "string", "null" ], "maxLength": 255 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 } }, "required": [ "amount" ], "title": "StorePaymentRequest" }, "StoreStaffRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 32 }, "password": { "type": "string", "minLength": 8, "maxLength": 255 }, "is_active": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "admin", "head_teacher", "deputy_head_teacher", "dean", "teacher", "bursar", "secretary" ] }, "minItems": 1, "uniqueItems": true } }, "required": [ "name", "email", "password", "roles" ], "title": "StoreStaffRequest" }, "StoreStreamRequest": { "type": "object", "properties": { "grade_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 } }, "required": [ "grade_id", "name" ], "title": "StoreStreamRequest" }, "StoreStudentMedicalRecordRequest": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "allergy", "condition", "medication", "immunization", "injury", "other" ] }, "severity": { "type": "string", "enum": [ "information", "attention", "critical" ] }, "title": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "occurred_on": { "type": [ "string", "null" ], "format": "date-time" }, "valid_until": { "type": [ "string", "null" ], "format": "date-time" }, "is_active": { "type": "boolean" }, "document": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application\/octet-stream", "description": "Maximum file size: 10000 kilobytes." } }, "required": [ "category", "severity", "title" ], "title": "StoreStudentMedicalRecordRequest" }, "StoreStudentRequest": { "type": "object", "properties": { "first_name": { "type": "string", "maxLength": 255 }, "last_name": { "type": "string", "maxLength": 255 }, "date_of_birth": { "type": [ "string", "null" ], "format": "date-time" }, "gender": { "type": [ "string", "null" ], "enum": [ "male", "female", null ] }, "guardian_name": { "type": [ "string", "null" ], "maxLength": 255 }, "guardian_phone": { "type": [ "string", "null" ], "maxLength": 32 }, "guardian_relationship": { "type": [ "string", "null" ], "maxLength": 100 }, "academic_year_id": { "type": "integer" }, "grade_id": { "type": "integer" }, "stream_id": { "type": [ "integer", "null" ] } }, "required": [ "first_name", "last_name", "academic_year_id", "grade_id" ], "title": "StoreStudentRequest" }, "StoreSubjectRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "grade_ids": { "type": "array", "items": { "type": "integer" }, "uniqueItems": true }, "ee_min_percentage": { "type": "integer", "minimum": 0, "maximum": 100 }, "me_min_percentage": { "type": "integer", "minimum": 0, "maximum": 100 }, "ae_min_percentage": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "name" ], "title": "StoreSubjectRequest" }, "StoreTeachingAssignmentRequest": { "type": "object", "properties": { "term_id": { "type": "integer" }, "subject_id": { "type": "integer" }, "class_section_ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "uniqueItems": true } }, "required": [ "term_id", "subject_id", "class_section_ids" ], "title": "StoreTeachingAssignmentRequest" }, "StoreTermRequest": { "type": "object", "properties": { "academic_year_id": { "type": "integer" }, "number": { "type": "integer", "minimum": 1, "maximum": 3 }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "academic_year_id", "number" ], "title": "StoreTermRequest" }, "StreamResource": { "type": "object", "properties": { "id": { "type": "integer" }, "grade_id": { "type": "integer" }, "grade": { "type": "object", "properties": { "id": { "type": "integer" }, "level": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "level", "display_name" ] }, "name": { "type": "string" }, "display_name": { "type": "string" }, "class_section": { "anyOf": [ { "$ref": "#\/components\/schemas\/ClassSectionResource" }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "grade_id", "name", "display_name", "created_at", "updated_at" ], "title": "StreamResource" }, "StudentMedicalRecordResource": { "type": "object", "properties": { "id": { "type": "integer" }, "category": { "type": "string" }, "severity": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "occurred_on": { "type": [ "string", "null" ] }, "valid_until": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "is_current": { "type": "boolean" }, "document": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "mime": { "type": [ "string", "null" ] }, "size": { "type": [ "integer", "null" ] } }, "required": [ "name", "mime", "size" ] }, "recorded_by": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "updated_by": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "category", "severity", "title", "description", "occurred_on", "valid_until", "is_active", "is_current", "document", "created_at", "updated_at" ], "title": "StudentMedicalRecordResource" }, "StudentResource": { "type": "object", "properties": { "id": { "type": "integer" }, "admission_number": { "type": "string" }, "admission_year": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "full_name": { "type": "string" }, "date_of_birth": { "type": [ "string", "null" ] }, "gender": { "type": [ "string", "null" ] }, "guardian": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "relationship": { "type": [ "string", "null" ] } }, "required": [ "name", "phone", "relationship" ] }, "is_active": { "type": "boolean" }, "current_class": { "type": [ "object", "null" ], "properties": { "enrollment_id": { "type": "integer" }, "academic_year_id": { "type": "integer" }, "grade_id": { "type": "integer" }, "class_section_id": { "type": "integer" }, "display_name": { "type": "string" }, "status": { "type": "string" }, "enrolled_on": { "type": [ "string", "null" ] } }, "required": [ "enrollment_id", "academic_year_id", "grade_id", "class_section_id", "display_name", "status", "enrolled_on" ] }, "excluded_subjects": { "type": "array", "items": { "type": "object", "properties": { "subject_id": { "type": "integer" }, "subject_name": { "type": "string" }, "subject_code": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "excluded_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "subject_id", "subject_name", "subject_code", "reason", "excluded_at" ] } }, "effective_subjects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": "string" } }, "required": [ "id", "name", "code" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "admission_number", "admission_year", "first_name", "last_name", "full_name", "date_of_birth", "gender", "guardian", "is_active", "created_at", "updated_at" ], "title": "StudentResource" }, "SubjectResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": "string" }, "grades": { "type": "array", "items": { "type": "object", "properties": { "grade": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "level": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "level", "display_name" ] }, "bands": { "type": "object", "properties": { "ee_min_percentage": { "type": "integer" }, "me_min_percentage": { "type": "integer" }, "ae_min_percentage": { "type": "integer" } }, "required": [ "ee_min_percentage", "me_min_percentage", "ae_min_percentage" ] } }, "required": [ "grade", "bands" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "code", "created_at", "updated_at" ], "title": "SubjectResource" }, "TeachingAssignmentResource": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "term_id": { "type": "integer" }, "class_section": { "type": "object", "properties": { "id": { "type": "integer" }, "grade_id": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "grade_id", "display_name" ] }, "subject": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": "string" } }, "required": [ "id", "name", "code" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "user_id", "term_id", "class_section", "subject", "created_at" ], "title": "TeachingAssignmentResource" }, "TermResource": { "type": "object", "properties": { "id": { "type": "integer" }, "academic_year_id": { "type": "integer" }, "academic_year": { "type": "object", "properties": { "id": { "type": "integer" }, "year": { "type": "integer" }, "is_current": { "type": "boolean" } }, "required": [ "id", "year", "is_current" ] }, "number": { "type": "integer" }, "start_date": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ] }, "is_current": { "type": "boolean" }, "display_name": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "academic_year_id", "number", "start_date", "end_date", "is_current", "display_name", "created_at", "updated_at" ], "title": "TermResource" }, "TermResultResource": { "type": "object", "properties": { "id": { "type": "integer" }, "term_id": { "type": "integer" }, "student_id": { "type": "integer" }, "class_section_id": { "type": "integer" }, "average_marks": { "type": "number" }, "average_percentage": { "type": "number" }, "total_points": { "type": "integer" }, "grade_rank": { "type": [ "integer", "null" ] }, "stream_rank": { "type": [ "integer", "null" ] }, "computed_at": { "type": [ "string", "null" ], "format": "date-time" }, "student": { "$ref": "#\/components\/schemas\/StudentResource" }, "subjects": { "type": "array", "items": { "$ref": "#\/components\/schemas\/TermResultSubjectResource" } } }, "required": [ "id", "term_id", "student_id", "class_section_id", "average_marks", "average_percentage", "total_points", "grade_rank", "stream_rank", "computed_at" ], "title": "TermResultResource" }, "TermResultSubjectResource": { "type": "object", "properties": { "id": { "type": "integer" }, "term_result_id": { "type": "integer" }, "subject_id": { "type": "integer" }, "average_score": { "type": "number" }, "out_of": { "type": "number" }, "average_percentage": { "type": "number" }, "performance_level": { "type": "string" }, "points": { "type": "integer" }, "subject": { "$ref": "#\/components\/schemas\/SubjectResource" } }, "required": [ "id", "term_result_id", "subject_id", "average_score", "out_of", "average_percentage", "performance_level", "points" ], "title": "TermResultSubjectResource" }, "UpdateAcademicYearRequest": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 2000, "maximum": 2100 }, "starts_on": { "type": [ "string", "null" ], "format": "date-time" }, "ends_on": { "type": [ "string", "null" ], "format": "date-time" } }, "title": "UpdateAcademicYearRequest" }, "UpdateExamRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "include_in_report_card": { "type": "boolean" }, "exam_date": { "type": [ "string", "null" ], "format": "date-time" } }, "title": "UpdateExamRequest" }, "UpdateExamSeriesRequest": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "Opener", "Midterm", "Endterm" ] }, "include_in_report_card": { "type": "boolean" }, "exam_date": { "type": [ "string", "null" ], "format": "date-time" }, "default_out_of": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "title": "UpdateExamSeriesRequest" }, "UpdateFeeStructureRequest": { "type": "object", "properties": { "academic_year_id": { "type": "integer" }, "grade_id": { "type": [ "integer", "null" ], "description": "Null means the template applies school-wide." }, "term_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "currency": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 }, "is_active": { "type": [ "boolean", "null" ] }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "items": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "amount": { "type": "number", "description": "Zero is allowed: a template row can be a placeholder the\nadministrator fills in per learner later.", "minimum": 0, "maximum": 99999999.99 }, "is_optional": { "type": [ "boolean", "null" ] } }, "required": [ "label", "amount" ] } } }, "title": "UpdateFeeStructureRequest" }, "UpdateGradeRequest": { "type": "object", "properties": { "academic_year_id": { "type": "integer" }, "level": { "type": "integer", "minimum": 1, "maximum": 12 }, "name": { "type": [ "string", "null" ], "maxLength": 255 } }, "title": "UpdateGradeRequest" }, "UpdateGradeSubjectBandsRequest": { "type": "object", "properties": { "ee_min_percentage": { "type": "integer", "minimum": 0, "maximum": 100 }, "me_min_percentage": { "type": "integer", "minimum": 0, "maximum": 100 }, "ae_min_percentage": { "type": "integer", "minimum": 0, "maximum": 100 } }, "title": "UpdateGradeSubjectBandsRequest" }, "UpdateInvoiceRequest": { "type": "object", "properties": { "recipient_name": { "type": [ "string", "null" ], "maxLength": 255 }, "recipient_details": { "type": [ "string", "null" ], "maxLength": 2000 }, "issue_date": { "type": "string", "format": "date-time" }, "due_date": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "footer_note": { "type": [ "string", "null" ], "maxLength": 2000 }, "items": { "type": "array", "description": "Sending items replaces the whole list, so a row can be\nadded, re-priced, reordered or removed in one save.", "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "quantity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999 }, "unit_amount": { "type": "number", "minimum": 0, "maximum": 99999999.99 } }, "required": [ "label", "unit_amount" ] }, "minItems": 1 } }, "title": "UpdateInvoiceRequest" }, "UpdateStaffRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 32 }, "password": { "type": [ "string", "null" ], "minLength": 8, "maxLength": 255 }, "is_active": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "admin", "head_teacher", "deputy_head_teacher", "dean", "teacher", "bursar", "secretary" ] }, "minItems": 1, "uniqueItems": true } }, "title": "UpdateStaffRequest" }, "UpdateStreamRequest": { "type": "object", "properties": { "grade_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 } }, "title": "UpdateStreamRequest" }, "UpdateStudentMedicalRecordRequest": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "allergy", "condition", "medication", "immunization", "injury", "other" ] }, "severity": { "type": "string", "enum": [ "information", "attention", "critical" ] }, "title": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "occurred_on": { "type": [ "string", "null" ], "format": "date-time" }, "valid_until": { "type": [ "string", "null" ], "format": "date-time" }, "is_active": { "type": "boolean" }, "document": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application\/octet-stream", "description": "Maximum file size: 10000 kilobytes." } }, "title": "UpdateStudentMedicalRecordRequest" }, "UpdateStudentRequest": { "type": "object", "properties": { "first_name": { "type": "string", "maxLength": 255 }, "last_name": { "type": "string", "maxLength": 255 }, "date_of_birth": { "type": [ "string", "null" ], "format": "date-time" }, "gender": { "type": [ "string", "null" ], "enum": [ "male", "female", null ] }, "guardian_name": { "type": [ "string", "null" ], "maxLength": 255 }, "guardian_phone": { "type": [ "string", "null" ], "maxLength": 32 }, "guardian_relationship": { "type": [ "string", "null" ], "maxLength": 100 } }, "title": "UpdateStudentRequest" }, "UpdateSubjectRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 } }, "required": [ "name" ], "title": "UpdateSubjectRequest" }, "UpdateTermRequest": { "type": "object", "properties": { "academic_year_id": { "type": "integer" }, "number": { "type": "integer", "minimum": 1, "maximum": 3 }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" } }, "title": "UpdateTermRequest" }, "UserResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "roles": { "type": "object" }, "teaching_assignments_count": { "type": "integer" }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "email", "phone", "is_active", "roles", "email_verified_at", "created_at" ], "title": "UserResource" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "AuthorizationException": { "description": "Authorization error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }