{ "openapi": "3.0.0", "info": { "title": "NMEC API | Stable Shield Solutions", "description": "Backend for the NMEC project. Powered by Stable Shield Solutions", "version": "1.0.0" }, "paths": { "/api/create-national-officer": { "post": { "tags": [ "Api" ], "summary": "Create a National Officer account", "description": "Allows the Super Admin to create a new National Officer account with one or more role assignments.", "operationId": "70dcb4cd2afac48e79e8b0c697b945b5", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "surname", "first_name", "email", "phone" ], "properties": { "surname": { "type": "string", "example": "Okafor" }, "first_name": { "type": "string", "example": "Ada" }, "middle_name": { "type": "string", "example": "B." }, "email": { "type": "string", "format": "email", "example": "ada.okafor@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "roles": { "description": "Optional array of roles. Defaults to ['National Officer'] if not provided.", "type": "array", "items": { "type": "string", "example": "Director Literacy" } } }, "type": "object" } } } }, "responses": { "200": { "description": "User created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "National Officer account created and mail sent" }, "assigned_roles": { "type": "array", "items": { "type": "string", "example": "National Officer" } } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "properties": { "email": { "type": "array", "items": { "type": "string", "example": "The email has already been taken." } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/create-super-admin": { "post": { "tags": [ "Unprotected" ], "summary": "Create a super admin", "operationId": "a2ca9f51164ef35ada3c9ebc008f0bc8", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "surname", "first_name", "email", "phone", "role" ], "properties": { "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Michael" }, "email": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "role": { "type": "string", "example": "Super Admin" } }, "type": "object" } } } }, "responses": { "201": { "description": "Super Admin Created Successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Super Admin Created Successfully" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "example": { "email": [ "The email has already been taken." ] } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/login": { "post": { "tags": [ "Unprotected" ], "summary": "User login", "description": "Allows a user (e.g. National Officer, State Agency Admin) to log in and returns a token along with user data, roles, and profile completion status.", "operationId": "loginUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "superadmin@gmail.com" }, "password": { "type": "string", "format": "password", "example": "123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful login", "content": { "application/json": { "schema": { "properties": { "access_token": { "type": "string", "example": "eyJ0eXAiOiJK..." }, "token_type": { "type": "string", "example": "bearer" }, "user": { "properties": { "id": { "type": "integer", "example": 1 }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "email": { "type": "string", "example": "superadmin@gmail.com" } }, "type": "object" }, "roles": { "type": "array", "items": { "type": "string", "example": "National Officers" } }, "profile_completed": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Invalid credentials" } }, "type": "object" } } } }, "403": { "description": "Email not verified", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Please verify your email before logging in." } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "User not found." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/verify/{userId}/{token}": { "get": { "tags": [ "Unprotected" ], "summary": "Verify email address", "description": "Verifies a user's email address using a token sent to their email. The token is matched from cache. If successful, marks the email as verified.", "operationId": "verifyEmail", "parameters": [ { "name": "userId", "in": "path", "description": "The ID of the user", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "token", "in": "path", "description": "The email verification token", "required": true, "schema": { "type": "string", "example": "AbC123XyZ" } } ], "responses": { "200": { "description": "Email verified successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Email verified successfully. You can now log in." } }, "type": "object" } } } }, "400": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invalid or expired verification token." } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "User not found." } }, "type": "object" } } } } } } }, "/api/complete-national-profile": { "post": { "tags": [ "National Officers" ], "summary": "Complete National Officer Profile", "description": "Allows a national officer to complete their profile, including uploading passport and signature images. The request should be multipart/form-data.", "operationId": "completeNationalProfile", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "surname": { "description": "Surname of the user", "type": "string", "maxLength": 50 }, "first_name": { "description": "First name of the user", "type": "string", "maxLength": 50 }, "middle_name": { "description": "Middle name of the user", "type": "string", "maxLength": 50 }, "gender": { "description": "Gender of the user", "type": "string" }, "marital_status": { "description": "Marital status", "type": "string" }, "staff_id": { "description": "Staff ID", "type": "string" }, "dob": { "description": "Date of birth", "type": "string", "format": "date" }, "year_of_employment": { "description": "Year of employment", "type": "integer" }, "passport": { "description": "Passport image (jpg, jpeg, png, max 2MB)", "type": "string", "format": "binary" }, "signature": { "description": "Signature image (jpg, jpeg, png, max 2MB)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Profile updated successfully." }, "user": { "properties": { "id": { "type": "integer" }, "surname": { "type": "string" }, "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "status": { "type": "integer" } }, "type": "object" }, "profile": { "type": "object" }, "passport_url": { "type": "string", "format": "url" }, "signature_url": { "type": "string", "format": "url" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/change-password": { "post": { "tags": [ "Api" ], "summary": "Change user password", "operationId": "fa86eb814026ec4bfd43a62ad84509a9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "current_password", "new_password", "new_password_confirmation" ], "properties": { "current_password": { "type": "string", "example": "oldpass123" }, "new_password": { "type": "string", "minLength": 6, "example": "newpass456" }, "new_password_confirmation": { "type": "string", "example": "newpass456" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password changed successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Password changed successfully." } }, "type": "object" } } } }, "400": { "description": "Current password is incorrect", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Current password is incorrect." } }, "type": "object" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed." }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred." }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/forgot-password": { "post": { "tags": [ "Unprotected" ], "summary": "Send password reset link", "description": "Generates a password reset token and sends it to the user's email address.", "operationId": "forgotPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password reset link sent", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Password reset link sent to your email" } }, "type": "object" } } } }, "422": { "description": "Validation error (e.g., email not found or invalid)", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "properties": { "email": { "type": "array", "items": { "type": "string", "example": "The selected email is invalid." } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/reset-password": { "post": { "tags": [ "Unprotected" ], "summary": "Reset user password", "description": "Resets the user's password using a valid token sent to their email.", "operationId": "resetPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "token", "password", "password_confirmation" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "token": { "type": "string", "example": "b4e3f78b8a1234ac9f91ec2a8fc963b0ff2a4f2ad2334" }, "password": { "type": "string", "format": "password", "example": "newpassword123" }, "password_confirmation": { "type": "string", "format": "password", "example": "newpassword123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password has been reset successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Password has been reset successfully" } }, "type": "object" } } } }, "400": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invalid or expired token" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "properties": { "password": { "type": "array", "items": { "type": "string", "example": "The password must be at least 6 characters." } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/resend-verification": { "post": { "tags": [ "Unprotected" ], "summary": "Resend email verification link to a user", "operationId": "resendVerificationEmail", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Verification email resent successfully.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Verification email resent successfully." } }, "type": "object" } } } }, "400": { "description": "Email is already verified or invalid input.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Email is already verified." } }, "type": "object" } } } }, "500": { "description": "Unable to send email.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unable to send email. Try again later." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/create-programmes": { "post": { "tags": [ "Api" ], "summary": "Create a new programme and optionally assign subjects", "description": "Super Admin can create a programme and optionally assign one or multiple existing subjects to it. The operation uses a database transaction to ensure safe saving.", "operationId": "createProgramme", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Name of the programme", "type": "string", "example": "Software Engineering" }, "description": { "description": "Optional programme description", "type": "string", "example": "Programme for learning software development" }, "subject_ids": { "description": "Optional list of subject IDs to assign to the programme", "type": "array", "items": { "type": "integer", "example": 2 } } }, "type": "object" } } } }, "responses": { "201": { "description": "Programme created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Programme created successfully" }, "programme": { "properties": { "id": { "type": "integer", "example": 6 }, "name": { "type": "string", "example": "Software Engineering" }, "description": { "type": "string", "example": "Programme for learning software development" }, "subjects": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "English Language" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "500": { "description": "Server error while creating programme" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/create-subjects": { "post": { "tags": [ "Api" ], "summary": "Create a new subject", "description": "Creates a new subject without assigning it to any programme.", "operationId": "createSubject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "English Language" }, "description": { "type": "string", "example": "Basic English studies" }, "curriculum": { "type": "string", "example": "Grammar, comprehension, writing" } }, "type": "object" } } } }, "responses": { "201": { "description": "Subject created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Subject created successfully." }, "subject": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "English Language" }, "description": { "type": "string", "example": "Basic English studies" }, "curriculum": { "type": "string", "example": "Grammar, comprehension, writing" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/programmes/{programme_id}/assign-subjects": { "post": { "tags": [ "Api" ], "summary": "Assign single or multiple subjects to a programme", "operationId": "db42d19988ae7953b585a0dae009968d", "parameters": [ { "name": "programme_id", "in": "path", "description": "ID of the programme", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "subjects" ], "properties": { "subjects": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Subjects assigned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Subjects assigned successfully" } }, "type": "object" } } } }, "404": { "description": "Programme not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/programmes-with-subjects": { "get": { "tags": [ "Centre" ], "summary": "Get all programmes with their assigned subjects", "operationId": "400cf49386f01867cc3d226134dcb9b9", "responses": { "200": { "description": "List of programmes with subjects", "content": { "application/json": { "schema": { "properties": { "programmes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Basic Literacy" }, "created_at": { "type": "string", "format": "date-time", "example": "2025-06-18T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-06-18T12:00:00Z" }, "subjects": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Mathematics" }, "programme_id": { "type": "integer", "example": 1 }, "created_at": { "type": "string", "format": "date-time", "example": "2025-06-18T12:10:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-06-18T12:10:00Z" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/get-all-programmes": { "get": { "tags": [ "Centre" ], "summary": "Get all programmes", "description": "Fetch a list of all programmes (latest first).", "operationId": "9319f88c79a2ca7272cb5049f3bed361", "responses": { "200": { "description": "List of all programmes", "content": { "application/json": { "schema": { "properties": { "programmes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Vocational Education" }, "created_at": { "type": "string", "format": "date-time", "example": "2025-06-18T14:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-06-18T14:00:00Z" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/register-centre": { "post": { "tags": [ "Centre" ], "summary": "Register a new Centre", "description": "Allows a centre owner/admin to self-register a new centre.", "operationId": "registerCentre", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "registered_name", "community_type", "ownership", "email", "phone", "zone", "state", "lga", "ward", "latitude", "longitude", "password", "password_confirmation" ], "properties": { "registered_name": { "type": "string", "example": "ABC Learning Centre" }, "community_type": { "type": "string", "enum": [ "Rural", "Urban" ], "example": "Urban" }, "ownership": { "type": "string", "enum": [ "Private", "Government" ], "example": "Private" }, "email": { "type": "string", "format": "email", "example": "centre@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "zone": { "type": "string", "enum": [ "North Central", "North East", "North West", "South East", "South South", "South West" ], "example": "South East" }, "state": { "type": "string", "example": "Anambra" }, "lga": { "type": "string", "example": "Awka South" }, "ward": { "type": "string", "example": "Umuokpu Ward" }, "latitude": { "type": "number", "format": "float", "example": 6.5243999999999999772626324556767940521240234375 }, "longitude": { "type": "number", "format": "float", "example": 3.37919999999999998152588887023739516735076904296875 }, "password": { "type": "string", "format": "password", "example": "secret123" }, "password_confirmation": { "type": "string", "format": "password", "example": "secret123" }, "picture": { "description": "Optional centre picture (jpg, jpeg, png)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Registration successful", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Registration successful." }, "centre_id": { "type": "string", "example": "NMEC/ANAMB/00001" }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "Centre Admin" ] }, "centre": { "properties": { "registered_name": { "type": "string", "example": "ABC Learning Centre" }, "email": { "type": "string", "example": "centre@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "community_type": { "type": "string", "example": "Urban" }, "picture_url": { "type": "string", "example": "http://localhost/centre_pictures/centre_uuid.jpg" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed." }, "errors": { "type": "object" } }, "type": "object" } } } } } } }, "/api/verify-centre/{id}/{token}": { "get": { "tags": [ "Centre" ], "summary": "Verify Centre Email", "description": "Verifies a centre's email using a token sent via email.", "operationId": "verifyCentreEmail", "parameters": [ { "name": "id", "in": "path", "description": "ID of the centre", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "token", "in": "path", "description": "Verification token sent via email", "required": true, "schema": { "type": "string", "example": "ABCD1234" } } ], "responses": { "200": { "description": "Email verified successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Email verified successfully. You can now login." } }, "type": "object" } } } }, "400": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invalid or expired token." } }, "type": "object" } } } }, "404": { "description": "Centre not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Centre not found." } }, "type": "object" } } } } } } }, "/api/resend-verification-centre": { "post": { "tags": [ "Centre" ], "summary": "Resend verification email to a centre", "description": "Resends a verification link to the centre if the email is not yet verified.", "operationId": "resendCentreVerification", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "centre@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Verification link resent or email already verified", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Verification link resent." } }, "type": "object" } } } }, "404": { "description": "Centre not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "properties": { "email": { "type": "array", "items": { "type": "string", "example": "The email field is required." } } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/login-centre": { "post": { "tags": [ "Centre" ], "summary": "Login a centre account", "description": "Authenticates a centre by email and password, returns a JWT token if successful.", "operationId": "loginCentre", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "centre@example.com" }, "password": { "type": "string", "format": "password", "example": "password123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "properties": { "token": { "type": "string", "example": "eyJ0eXAiOiJKV1QiLCJhbGciOi..." }, "centre": { "description": "Centre details", "properties": { "id": { "type": "integer", "example": 1 }, "email": { "type": "string", "example": "centre@example.com" }, "name": { "type": "string", "example": "Centre ABC" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invalid credentials" } }, "type": "object" } } } }, "403": { "description": "Email not verified", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Verify email before login" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "properties": { "email": { "type": "array", "items": { "type": "string", "example": "The email field is required." } } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/logout": { "post": { "tags": [ "Api" ], "summary": "Logout the authenticated user", "description": "Invalidates the current JWT token, effectively logging out the user.", "operationId": "logoutUser", "responses": { "200": { "description": "Logout successful", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Logged out successfully." } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre-profile-complete": { "post": { "tags": [ "Centre" ], "summary": "Complete or update a centre profile", "description": "Allows an authenticated centre to complete or update its profile, upload files optionally, and assign programmes.", "operationId": "81259fde0193ffb2b5fcf7be42804c61", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "last_name", "first_name", "phone", "gender", "marital_status", "state_of_origin", "lga_of_origin", "state_of_residence", "lga_of_residence", "residential_address", "nin", "highest_qualification", "days_of_operation", "neighbourhood", "centre_ownership" ], "properties": { "last_name": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Paul", "nullable": true }, "photo": { "type": "string", "format": "binary", "nullable": true }, "signature": { "type": "string", "format": "binary", "nullable": true }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Male" }, "marital_status": { "type": "string", "example": "Single" }, "state_of_origin": { "type": "string", "example": "Lagos" }, "lga_of_origin": { "type": "string", "example": "Ikeja" }, "state_of_residence": { "type": "string", "example": "Lagos" }, "lga_of_residence": { "type": "string", "example": "Surulere" }, "residential_address": { "type": "string", "example": "123 Main Street" }, "nin": { "type": "string", "example": "12345678901" }, "highest_qualification": { "type": "string", "example": "BSc Education" }, "programmes": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ], "nullable": true }, "days_of_operation": { "type": "array", "items": { "type": "string" }, "example": [ "Monday", "Tuesday" ] }, "neighbourhood": { "type": "string", "example": "Ikeja GRA" }, "centre_ownership": { "type": "string", "example": "Private" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile saved successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profile saved successfully" }, "profile": { "properties": { "centre_id": { "type": "integer", "example": 1 }, "last_name": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Paul" }, "photo": { "type": "string", "example": "centre/photos/photo.jpg" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Male" }, "marital_status": { "type": "string", "example": "Single" }, "state_of_origin": { "type": "string", "example": "Lagos" }, "lga_of_origin": { "type": "string", "example": "Ikeja" }, "state_of_residence": { "type": "string", "example": "Lagos" }, "lga_of_residence": { "type": "string", "example": "Surulere" }, "residential_address": { "type": "string", "example": "123 Main Street" }, "nin": { "type": "string", "example": "12345678901" }, "highest_qualification": { "type": "string", "example": "BSc Education" }, "signature": { "type": "string", "example": "centre/signatures/signature.jpg" }, "days_of_operation": { "type": "array", "items": { "type": "string" }, "example": [ "Monday", "Tuesday" ] }, "neighbourhood": { "type": "string", "example": "Ikeja GRA" }, "centre_ownership": { "type": "string", "example": "Private" } }, "type": "object" }, "programmes": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] }, "centre_state": { "type": "string", "example": "Lagos" }, "centre_lga": { "type": "string", "example": "Ikeja" }, "photo_url": { "type": "string", "example": "http://yourdomain.com/storage/centre/photos/photo.jpg" }, "signature_url": { "type": "string", "example": "http://yourdomain.com/storage/centre/signatures/signature.jpg" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation error" }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/create-state-agency-admin": { "post": { "tags": [ "Zonal Admin" ], "summary": "Create State Agency Admin", "description": "Allows a Zonal Admin to create a new State Agency Admin with passport and signature upload.", "operationId": "createStateAgencyAdmin", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "surname", "first_name", "email", "phone", "gender" ], "properties": { "surname": { "type": "string", "example": "Okoro" }, "first_name": { "type": "string", "example": "Chioma" }, "middle_name": { "type": "string", "example": "Faith" }, "email": { "type": "string", "format": "email", "example": "chioma.okoro@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "gender": { "type": "string", "enum": [ "Male", "Female" ], "example": "Female" }, "marital_status": { "type": "string", "example": "Single" }, "passport": { "description": "Upload passport image", "type": "string", "format": "binary" }, "signature": { "description": "Upload signature image", "type": "string", "format": "binary" }, "nin": { "type": "string", "example": "12345678901" }, "staff_id": { "type": "string", "example": "SA-001" }, "dob": { "type": "string", "format": "date", "example": "1990-05-20" }, "year_of_employment": { "type": "integer", "example": 2025 }, "state": { "type": "string", "example": "Delta" } }, "type": "object" } } } }, "responses": { "200": { "description": "State Agency Admin created successfully" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/complete-state-agency-admin-profile": { "post": { "tags": [ "State Agency Admin" ], "summary": "Complete or update State Agency Admin profile", "description": "Allows a State Agency Admin to complete or update their profile, including personal information, employment data, and file uploads.", "operationId": "completeStateAgencyProfile", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "state" ], "properties": { "gender": { "type": "string", "example": "male" }, "marital_status": { "type": "string", "example": "Single" }, "staff_id": { "type": "string", "example": "STAFF12345" }, "dob": { "type": "string", "format": "date", "example": "1985-07-16" }, "nin": { "type": "string", "example": "12345678901" }, "state": { "type": "string", "example": "Lagos" }, "year_of_employment": { "type": "string", "example": "2020" }, "passport": { "type": "file", "format": "binary" }, "signature": { "type": "file", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profile updated successfully." }, "profile": { "type": "object" }, "passport_url": { "type": "string", "example": "https://yourdomain.com/storage/passports/uuid.jpg" }, "signature_url": { "type": "string", "example": "https://yourdomain.com/storage/signatures/uuid.jpg" } }, "type": "object" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed." }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/users-by-role": { "get": { "tags": [ "Api" ], "summary": "Get all users with a specific role", "description": "Retrieve all users assigned to a given role such as 'State Agency Admin', 'National Officers', etc.", "operationId": "getUsersByRole", "parameters": [ { "name": "role", "in": "query", "description": "Name of the role (e.g. 'State Agency Admin')", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Users retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "role": { "type": "string", "example": "State Agency Admin" }, "users": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state-admin-centres": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get centres in the same state as the State Agency Admin", "description": "Returns all centres whose state matches the authenticated State Agency Admin's profile state.", "operationId": "getCentresInSameState", "responses": { "200": { "description": "List of centres in the same state", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "centres": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "centre_id": { "type": "integer", "example": 10 }, "state_of_centre": { "type": "string", "example": "Lagos" }, "lga_of_centre": { "type": "string", "example": "Ikeja" }, "centre_address": { "type": "string", "example": "123 Centre Street" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "centre": { "properties": { "id": { "type": "integer", "example": 10 }, "registered_name": { "type": "string", "example": "ABC Training Centre" }, "status": { "type": "string", "example": "pending" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profile not found." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state-admin-centre/{id}/approve": { "post": { "tags": [ "State Agency Admin" ], "summary": "Approve a centre", "description": "Approves a centre by ID if it exists and belongs to the same state as the admin.", "operationId": "approveCentre", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the centre to approve", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Centre approved", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Centre approved." } }, "type": "object" } } } }, "403": { "description": "Centre not found or not in your state", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Centre not found or not in your state." } }, "type": "object" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profile not found." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state-admin-centre/{id}/reject": { "post": { "tags": [ "State Agency Admin" ], "summary": "Reject a centre", "description": "Rejects a centre by ID if it exists and belongs to the same state as the authenticated admin.", "operationId": "rejectCentre", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the centre to reject", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Centre rejected successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Centre rejected." } }, "type": "object" } } } }, "403": { "description": "Centre not found or not in your state", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Centre not found or not in your state." } }, "type": "object" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profile not found." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/get-all-centres": { "get": { "tags": [ "Api" ], "summary": "Get all centres", "description": "Allows Super Admin to retrieve all centre profiles along with their associated centre accounts.", "operationId": "getAllCentres", "responses": { "200": { "description": "List of all centres", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "centres": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "centre_address": { "type": "string", "example": "123 Main Street" }, "programmes": { "type": "array", "items": { "type": "string", "example": "Literacy" } }, "days_of_operation": { "type": "array", "items": { "type": "string", "example": "Monday" } }, "centre": { "properties": { "id": { "type": "integer", "example": 10 }, "email": { "type": "string", "example": "centre@example.com" }, "registered_name": { "type": "string", "example": "Bright Future Centre" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/assign-roles-to-user": { "post": { "tags": [ "Api" ], "summary": "Assign roles to an existing user", "description": "Allows the Super Admin to assign one or multiple roles to an already registered user.", "operationId": "assignRolesToUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id", "roles" ], "properties": { "user_id": { "description": "ID of the user to assign roles to", "type": "integer", "example": 12 }, "roles": { "description": "Array of role names to assign", "type": "array", "items": { "type": "string", "example": "Director Vocational" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Roles assigned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Roles assigned successfully" }, "assigned_roles": { "type": "array", "items": { "type": "string", "example": "Director Vocational" } } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "example": { "roles": [ "The selected roles.0 is invalid." ] } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/remove-roles-from-user": { "post": { "tags": [ "Api" ], "summary": "Remove roles from an existing user", "description": "Allows the Super Admin to remove one or multiple roles from a registered user.", "operationId": "removeRolesFromUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id", "roles" ], "properties": { "user_id": { "description": "ID of the user from whom roles will be removed", "type": "integer", "example": 12 }, "roles": { "description": "Array of role names to remove", "type": "array", "items": { "type": "string", "example": "Director Literacy" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Roles removed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Roles removed successfully" }, "remaining_roles": { "type": "array", "items": { "type": "string", "example": "Director Literacy" } } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "example": { "roles": [ "The selected roles.0 is invalid." ] } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/all-users-with-roles": { "get": { "tags": [ "Api" ], "summary": "Get all users with their roles", "description": "Allows the Super Admin to fetch all registered users along with their assigned roles.", "operationId": "getAllUsersWithRoles", "responses": { "200": { "description": "List of users with their roles", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "users": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "roles": { "type": "array", "items": { "type": "string", "example": "National Officers" } } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/register-learner": { "post": { "tags": [ "Centre" ], "summary": "Register a new learner", "description": "Registers a new learner under the centre of the logged-in admin. Generates a default password and assigns the 'Learner' role.", "operationId": "registerLearner", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "surname", "first_name", "email", "phone", "program_id", "date_of_birth", "gender" ], "properties": { "surname": { "type": "string", "maxLength": 50, "example": "Doe" }, "first_name": { "type": "string", "maxLength": 50, "example": "John" }, "middle_name": { "type": "string", "maxLength": 50, "example": "Michael", "nullable": true }, "email": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "program_id": { "description": "ID of the program the learner is applying for", "type": "integer", "example": 1 }, "date_of_birth": { "type": "string", "format": "date", "example": "2005-06-15" }, "gender": { "type": "string", "enum": [ "Male", "Female", "Other" ], "example": "Male" }, "snap_picture": { "description": "Upload a snapshot of the learner", "type": "file", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Learner registered successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Learner registered successfully. Default password: 123456" }, "learner": { "properties": { "learner_id": { "type": "string", "example": "NMECC/ANAM/00001/0001" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "profile_completed": { "type": "boolean", "example": false }, "snap_picture_url": { "type": "string", "example": "http://localhost/storage/snapshots/1699999999_photo.png", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Validation failed." }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Registration failed. Please try again later." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/verify-learner/{id}/{token}": { "get": { "tags": [ "Learner" ], "summary": "Verify learner email and generate learner ID", "operationId": "8fc35718335e7333eaf8e23deb9e55b7", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the learner", "required": true, "schema": { "type": "integer", "example": 123 } }, { "name": "token", "in": "path", "description": "The verification token sent to the learner's email", "required": true, "schema": { "type": "string", "example": "ABCD1234" } } ], "responses": { "200": { "description": "Email verified successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Email verified successfully. Your Learner ID has been sent to your email." } }, "type": "object" } } } }, "400": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invalid or expired token" } }, "type": "object" } } } } } } }, "/api/learner-login": { "post": { "tags": [ "Learner" ], "summary": "Learner Login", "description": "Login a learner using either email or learner ID and password", "operationId": "loginLearner", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "login", "password" ], "properties": { "login": { "description": "Learner email or learner ID", "type": "string", "example": "NMEC/ANAMB/00001/0001" }, "password": { "type": "string", "format": "password", "example": "123456" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Login successful" }, "token": { "type": "string", "example": "eyJ0eXAiOiJKV1QiLCJh..." }, "learner_id": { "type": "string", "example": "NMEC/ANAMB/00001/0001" }, "email": { "type": "string", "example": "john@gmail.com" }, "status": { "type": "string", "example": "approved" }, "roles": { "type": "array", "items": { "type": "string", "example": "learner" } }, "profile_completed": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invalid credentials" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "example": { "login": [ "The login field is required." ] } } }, "type": "object" } } } } } } }, "/api/complete-learner-profile": { "post": { "tags": [ "Learner" ], "summary": "Complete or Update Learner Profile", "description": "Allows an authenticated learner to complete or update their profile. Only the learner can perform this action.", "operationId": "completeLearnerProfile", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "phone" ], "properties": { "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Male" }, "marital_status": { "type": "string", "example": "Single" }, "state_of_origin": { "type": "string", "example": "Anambra" }, "lga_of_origin": { "type": "string", "example": "Awka South" }, "home_town": { "type": "string", "example": "Awka" }, "state_of_residence": { "type": "string", "example": "Lagos" }, "lga_of_residence": { "type": "string", "example": "Ikeja" }, "residential_address": { "type": "string", "example": "12 Allen Avenue, Ikeja" }, "nin": { "type": "string", "example": "12345678901" }, "last_sch_attended": { "type": "string", "example": "Government Secondary School" }, "reason_for_leaving": { "type": "string", "example": "Completed secondary education" }, "highest_qualification_dates": { "type": "string", "example": "WAEC - 2022" }, "any_other_info": { "type": "string", "example": "Interested in ICT training" }, "date_of_birth": { "type": "string", "format": "date", "example": "2000-05-10" }, "photo": { "description": "Passport photograph (jpg, jpeg, png)", "type": "string", "format": "binary" }, "signature": { "description": "Signature image (jpg, jpeg, png)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profile updated successfully." }, "learner_id": { "type": "string", "example": "NMEC/ANAMB/00001/0001" }, "profile_completed": { "type": "boolean", "example": true }, "profile": { "type": "object" }, "photo_url": { "type": "string", "example": "http://localhost/storage/learner_photos/photo_172839392.png" }, "signature_url": { "type": "string", "example": "http://localhost/storage/learner_signatures/sign_172839392.png" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/complete-facilitator-profile": { "post": { "tags": [ "Facilitator" ], "summary": "Complete Facilitator Profile", "description": "Allows an authenticated facilitator to complete or update their profile information.", "operationId": "021c518c13a5e64d567e23d8df3d5cbb", "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "marital_status": { "type": "string", "example": "Single" }, "state_of_origin": { "type": "string", "example": "Lagos" }, "lga_of_origin": { "type": "string", "example": "Ikeja" }, "home_town": { "type": "string", "example": "Ikeja" }, "state_of_residence": { "type": "string", "example": "Abuja" }, "lga_of_residence": { "type": "string", "example": "Gwagwalada" }, "residential_address": { "type": "string", "example": "No 12 Example Street" }, "nin": { "type": "string", "example": "12345678901" }, "highest_qualification_dates": { "type": "string", "example": "2015-2019" }, "course_of_study": { "type": "string", "example": "Computer Science" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile completed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Profile completed successfully" }, "user": { "type": "object" }, "profile": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing token" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/verify-facilitator/{id}/{token}": { "get": { "tags": [ "Facilitator" ], "summary": "Verify facilitator email and generate Facilitator ID", "operationId": "81175a9cb675fafd50c8f815feed38d3", "parameters": [ { "name": "id", "in": "path", "description": "Facilitator ID (database primary key)", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "token", "in": "path", "description": "Verification token sent via email", "required": true, "schema": { "type": "string", "example": "d4f5g6h7j8k9l0mn" } } ], "responses": { "200": { "description": "Email already verified or verification successful", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Email verified successfully. Your Facilitator ID has been sent to your email." } }, "type": "object" } } } }, "400": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invalid or expired token" } }, "type": "object" } } } }, "404": { "description": "Facilitator not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "No query results for model [App\\\\Models\\\\Facilitator] 1" } }, "type": "object" } } } } } } }, "/api/register-facilitator": { "post": { "tags": [ "Centre" ], "summary": "Register a new facilitator", "description": "Creates a new facilitator account by a Centre Admin. Saves gender, date_of_birth, snap_picture, and links facilitator to the centre.", "operationId": "registerFacilitator", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "surname", "first_name", "email", "phone", "gender", "date_of_birth", "password" ], "properties": { "surname": { "type": "string", "maxLength": 50, "example": "Doe" }, "first_name": { "type": "string", "maxLength": 50, "example": "John" }, "middle_name": { "type": "string", "maxLength": 50, "example": "Michael", "nullable": true }, "email": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "phone": { "description": "Phone number in local or international format", "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "enum": [ "Male", "Female", "Other" ], "example": "Male" }, "date_of_birth": { "type": "string", "format": "date", "example": "1995-05-15" }, "password": { "type": "string", "format": "password", "minLength": 6, "example": "password123" }, "snap_picture": { "description": "Optional facilitator profile picture (jpg, jpeg, png)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Facilitator registered successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Facilitator registered successfully" }, "facilitator": { "properties": { "facilitator_id": { "type": "string", "example": "NMEC/CTR/00001/F0001" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Male" }, "date_of_birth": { "type": "string", "example": "1995-05-15" }, "centre_of_choice": { "type": "string", "example": "Example Training Centre", "nullable": true }, "profile_completed": { "type": "boolean", "example": false }, "snap_picture_url": { "type": "string", "example": "http://example.com/storage/facilitator_snaps/1712345678_image.jpg", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "example": { "email": [ "The email has already been taken." ], "phone": [ "Enter a valid phone number." ] } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Centre Admin not authenticated" }, "500": { "description": "Registration failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Registration failed. Please try again." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/login-facilitator": { "post": { "tags": [ "Facilitator" ], "summary": "Login as a facilitator", "operationId": "f213a5b1967728f8aaa33449c24021e6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "facilitator@example.com" }, "password": { "type": "string", "format": "password", "example": "secret123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Login successful" }, "token": { "type": "string", "example": "jwt_token_here" }, "facilitator_status": { "type": "string", "example": "pending" }, "facilitator_id": { "type": "string", "example": "202600123456" }, "roles": { "type": "array", "items": { "type": "string", "example": "Facilitator" } }, "profile_completed": { "type": "boolean", "example": false } }, "type": "object" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invalid credentials" } }, "type": "object" } } } }, "403": { "description": "Email not verified", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Please verify your email before logging in." } }, "type": "object" } } } } } } }, "/api/centre-admin/facilitators/{facilitatorId}/approve": { "put": { "tags": [ "Centre" ], "summary": "Approve or reject a facilitator", "description": "Allows a Centre Admin to approve or reject a facilitator's application by updating the status.", "operationId": "dc658f05ccfa06c518e65684953970f5", "parameters": [ { "name": "facilitatorId", "in": "path", "description": "ID of the facilitator to approve/reject", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "description": "The status to set for the facilitator", "type": "string", "enum": [ "approved", "rejected" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Facilitator successfully approved/rejected", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Facilitator has been approved." }, "facilitator": { "properties": { "id": { "type": "integer", "example": 4 }, "name": { "type": "string", "example": "Tolu Arokodare" }, "email": { "type": "string", "example": "tolu@gmail.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Facilitator not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Facilitator not found." } }, "type": "object" } } } }, "403": { "description": "Unauthorized action", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthorized action." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centres-by-state": { "get": { "tags": [ "Learner" ], "summary": "Get list of centres within the learner's state of residence", "operationId": "02471c3048fe56a10cb6deeedf009e29", "responses": { "200": { "description": "List of centres in learner's state of residence", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Centres fetched successfully" }, "state": { "type": "string", "example": "Kano" }, "centres": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "centre_id": { "type": "integer", "example": 15 }, "last_name": { "type": "string", "example": "Abdullahi" }, "first_name": { "type": "string", "example": "Aisha" }, "state_of_centre": { "type": "string", "example": "Kano" }, "lga_of_centre": { "type": "string", "example": "Gwale" }, "centre_address": { "type": "string", "example": "No. 12 Kofar Mata Rd" }, "programmes": { "type": "array", "items": { "type": "string", "example": "Basic Literacy" } } }, "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Learner profile not completed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Learner profile not completed" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/national-officer/edit-profile": { "post": { "tags": [ "National Officers" ], "summary": "Update logged-in National Officer's full profile", "description": "Allows an authenticated National Officer to update their user profile and associated profile details, including passport and signature images stored in the public folder.", "operationId": "editNationalOfficerProfile", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "surname": { "type": "string", "maxLength": 50, "example": "Doe" }, "first_name": { "type": "string", "maxLength": 50, "example": "Jane" }, "middle_name": { "type": "string", "maxLength": 50, "example": "Ann" }, "phone": { "type": "string", "example": "08012345678" }, "gender": { "type": "string", "enum": [ "male", "female", "Other" ], "example": "female" }, "marital_status": { "type": "string", "example": "Single" }, "staff_id": { "type": "string", "maxLength": 20, "example": "NOF-00123" }, "dob": { "type": "string", "format": "date", "example": "1990-08-15" }, "year_of_employment": { "type": "integer", "example": 2018 }, "passport": { "description": "Passport image file (jpeg, png, jpg)", "type": "string", "format": "binary" }, "signature": { "description": "Signature image file (jpeg, png, jpg)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Profile updated successfully" }, "user": { "properties": { "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "Jane" }, "middle_name": { "type": "string", "example": "Ann" }, "email": { "type": "string", "example": "jane.doe@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "status": { "type": "boolean", "example": true } }, "type": "object" }, "profile": { "properties": { "gender": { "type": "string", "example": "female" }, "marital_status": { "type": "string", "example": "Single" }, "staff_id": { "type": "string", "example": "NOF-00123" }, "dob": { "type": "string", "format": "date", "example": "1990-08-15" }, "year_of_employment": { "type": "integer", "example": 2018 }, "passport": { "type": "string", "example": "passports/passport_uuid.jpg" }, "signature": { "type": "string", "example": "signatures/signature_uuid.png" } }, "type": "object" }, "passport_url": { "type": "string", "example": "http://localhost:8000/passports/passport_uuid.jpg" }, "signature_url": { "type": "string", "example": "http://localhost:8000/signatures/signature_uuid.png" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "example": { "phone": [ "The phone has already been taken." ] } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state-agency-admin/edit-profile": { "post": { "tags": [ "State Agency Admin" ], "summary": "Edit the profile of a State Agency Admin", "description": "Allows an authenticated State Agency Admin to update their profile, including passport and signature images stored in the public folder.", "operationId": "editStateAgencyAdminProfile", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "surname": { "type": "string", "maxLength": 50, "example": "Doe" }, "first_name": { "type": "string", "maxLength": 50, "example": "John" }, "middle_name": { "type": "string", "maxLength": 50, "example": "Michael" }, "phone": { "type": "string", "example": "08012345678" }, "gender": { "type": "string", "enum": [ "male", "female", "Other" ], "example": "male" }, "marital_status": { "type": "string", "maxLength": 50, "example": "Married" }, "staff_id": { "type": "string", "maxLength": 20, "example": "SA-00123" }, "nin": { "type": "string", "maxLength": 20, "example": "12345678901" }, "dob": { "type": "string", "format": "date", "example": "1985-06-25" }, "year_of_employment": { "type": "integer", "maximum": 2100, "minimum": 1900, "example": 2010 }, "state": { "type": "string", "maxLength": 100, "example": "Lagos" }, "passport": { "description": "Passport image file (jpeg, png, jpg)", "type": "string", "format": "binary" }, "signature": { "description": "Signature image file (jpeg, png, jpg)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Profile updated successfully" }, "user": { "properties": { "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Michael" }, "email": { "type": "string", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "status": { "type": "boolean", "example": true } }, "type": "object" }, "profile": { "properties": { "gender": { "type": "string", "example": "male" }, "marital_status": { "type": "string", "example": "Married" }, "staff_id": { "type": "string", "example": "SA-00123" }, "nin": { "type": "string", "example": "12345678901" }, "dob": { "type": "string", "format": "date", "example": "1985-06-25" }, "year_of_employment": { "type": "integer", "example": 2010 }, "state": { "type": "string", "example": "Lagos" }, "passport": { "type": "string", "example": "passports/passport_uuid.jpg" }, "signature": { "type": "string", "example": "signatures/signature_uuid.png" } }, "type": "object" }, "passport_url": { "type": "string", "example": "http://localhost:8000/passports/passport_uuid.jpg" }, "signature_url": { "type": "string", "example": "http://localhost:8000/signatures/signature_uuid.png" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "example": { "phone": [ "The phone has already been taken." ] } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/edit-profile": { "post": { "tags": [ "Centre" ], "summary": "Edit or update the centre admin profile and centre details", "description": "Allows a logged-in centre admin to update their profile, centre details, programmes, photo, and signature.", "operationId": "editCentreAdminProfile", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "last_name": { "type": "string", "maxLength": 50, "example": "Doe" }, "first_name": { "type": "string", "maxLength": 50, "example": "John" }, "middle_name": { "type": "string", "maxLength": 50, "example": "Michael" }, "phone": { "type": "string", "example": "08012345678" }, "gender": { "type": "string", "enum": [ "Male", "Female" ], "example": "Male" }, "marital_status": { "type": "string", "example": "Single" }, "state_of_origin": { "type": "string", "example": "Lagos" }, "lga_of_origin": { "type": "string", "example": "Ikeja" }, "state_of_residence": { "type": "string", "example": "Lagos" }, "lga_of_residence": { "type": "string", "example": "Surulere" }, "residential_address": { "type": "string", "example": "No 23, Main Street" }, "nin": { "type": "string", "example": "12345678901" }, "highest_qualification": { "type": "string", "example": "B.Sc" }, "town": { "type": "string", "example": "Umuokpu" }, "centre_address": { "type": "string", "example": "No 23, Main Street" }, "year_of_establishment": { "type": "integer", "example": 2005 }, "time_of_operation": { "description": "Array of operation times", "type": "array", "items": { "type": "string" }, "example": [ "08:00-12:00", "13:00-17:00" ] }, "days_of_operation": { "description": "Array of operation days", "type": "array", "items": { "type": "string" }, "example": [ "Monday", "Tuesday" ] }, "neighborhood": { "type": "string", "example": "Market" }, "is_owned": { "type": "boolean", "example": true }, "programmes": { "description": "IDs of programmes assigned to centre", "type": "array", "items": { "type": "integer" }, "example": [ 1, 3 ] }, "photo": { "type": "string", "format": "binary" }, "signature": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Centre profile updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Centre profile updated successfully" }, "centre": { "type": "object" }, "profile": { "type": "object" }, "details": { "type": "object" }, "programmes": { "type": "array", "items": { "type": "object" } }, "photo_url": { "type": "string", "example": "https://yourdomain.com/centre_photos/photo.jpg" }, "signature_url": { "type": "string", "example": "https://yourdomain.com/centre_signatures/signature.jpg" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The time_of_operation field must be an array." }, "errors": { "properties": { "time_of_operation": { "type": "array", "items": { "type": "string" } }, "days_of_operation": { "type": "array", "items": { "type": "string" } }, "programmes": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/edit-learner-profile": { "post": { "tags": [ "Learner" ], "summary": "Edit learner profile", "description": "Allows an authenticated learner to update their profile information and upload photo or signature.", "operationId": "editLearnerProfile", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "surname": { "type": "string", "maxLength": 50, "example": "Doe" }, "first_name": { "type": "string", "maxLength": 50, "example": "John" }, "middle_name": { "type": "string", "maxLength": 50, "example": "Michael" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "enum": [ "Male", "Female", "Other" ], "example": "Male" }, "date_of_birth": { "type": "string", "format": "date", "example": "2000-05-10" }, "marital_status": { "type": "string", "example": "Single" }, "state_of_origin": { "type": "string", "example": "Anambra" }, "lga_of_origin": { "type": "string", "example": "Awka South" }, "home_town": { "type": "string", "example": "Nibo" }, "state_of_residence": { "type": "string", "example": "Lagos" }, "lga_of_residence": { "type": "string", "example": "Ikeja" }, "residential_address": { "type": "string", "example": "12 Allen Avenue Ikeja" }, "last_sch_attended": { "type": "string", "example": "University of Lagos" }, "reason_for_leaving": { "type": "string", "example": "Completed program" }, "any_other_info": { "type": "string", "example": "Interested in advanced training" }, "nin": { "type": "string", "example": "12345678901" }, "highest_qualification_dates": { "type": "string", "example": "BSc 2021" }, "photo": { "description": "Learner passport photograph (jpg, jpeg, png, max 2MB)", "type": "string", "format": "binary" }, "signature": { "description": "Learner signature image (jpg, jpeg, png, max 2MB)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Learner profile updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Profile updated successfully" }, "learner": { "properties": { "id": { "type": "integer", "example": 3 }, "learner_id": { "type": "string", "example": "NMEC/ANAMB/00001/0001" }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Michael" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Male" }, "date_of_birth": { "type": "string", "example": "2000-05-10" }, "profile_completed": { "type": "boolean", "example": true } }, "type": "object" }, "profile": { "properties": { "photo": { "type": "string", "example": "learner_photos/photo.jpg" }, "signature": { "type": "string", "example": "learner_signatures/signature.jpg" }, "marital_status": { "type": "string", "example": "Single" }, "state_of_origin": { "type": "string", "example": "Anambra" }, "lga_of_origin": { "type": "string", "example": "Awka South" }, "home_town": { "type": "string", "example": "Nibo" }, "state_of_residence": { "type": "string", "example": "Lagos" }, "lga_of_residence": { "type": "string", "example": "Ikeja" }, "residential_address": { "type": "string", "example": "12 Allen Avenue Ikeja" }, "last_sch_attended": { "type": "string", "example": "University of Lagos" }, "reason_for_leaving": { "type": "string", "example": "Completed program" }, "any_other_info": { "type": "string", "example": "Interested in advanced training" }, "nin": { "type": "string", "example": "12345678901" }, "highest_qualification_dates": { "type": "string", "example": "BSc 2021" } }, "type": "object" }, "photo_url": { "type": "string", "example": "http://localhost/storage/learner_photos/photo.jpg", "nullable": true }, "signature_url": { "type": "string", "example": "http://localhost/storage/learner_signatures/signature.jpg", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Something went wrong" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/delete-user/{id}": { "delete": { "tags": [ "Api" ], "summary": "Delete a user and all associated profiles", "description": "Deletes the user with the specified ID, along with their national officer and state agency profiles, including any uploaded passport and signature files.", "operationId": "deleteUser", "parameters": [ { "name": "id", "in": "path", "description": "ID of the user to delete", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User and associated profile deleted successfully." } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not found." } }, "type": "object" } } } }, "500": { "description": "Error deleting user", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error deleting user." }, "error": { "type": "string", "example": "Exception message" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/get-user/{id}": { "get": { "tags": [ "Api" ], "summary": "Fetch user by ID", "description": "Retrieve a user's data along with roles, national officer profile, and state agency profile.", "operationId": "getUserById", "parameters": [ { "name": "id", "in": "path", "description": "ID of the user to retrieve", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "User retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "user": { "description": "User details with related data", "properties": { "id": { "type": "integer", "example": 1 }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Michael" }, "email": { "type": "string", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "roles": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Admin" } }, "type": "object" } }, "profile": { "description": "National officer profile", "type": "object" }, "stateAgencyProfile": { "description": "State agency profile", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not found." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/national-officers": { "get": { "tags": [ "Api" ], "summary": "Get all National Officers", "operationId": "411eaf12a59b1e4170fbe57ce2f22a52", "responses": { "200": { "description": "List of National Officers" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/state-agency-admins": { "get": { "tags": [ "Api" ], "summary": "Get all State Agency Admins with their Zonal Admin", "description": "Returns a list of all State Agency Admins including their profile details and the Zonal Admin they belong to", "operationId": "getStateAgency", "responses": { "200": { "description": "List of State Agency Admins retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 15 }, "surname": { "type": "string", "example": "Okafor" }, "first_name": { "type": "string", "example": "Chinedu" }, "middle_name": { "type": "string", "example": "James" }, "email": { "type": "string", "example": "stateadmin@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "roles": { "type": "array", "items": { "type": "string", "example": "State Agency Admin" } }, "profile": { "properties": { "gender": { "type": "string", "example": "Male" }, "marital_status": { "type": "string", "example": "Single" }, "passport": { "type": "string", "example": "http://localhost/passports/passport_xxx.jpg" }, "signature": { "type": "string", "example": "http://localhost/signatures/signature_xxx.png" }, "nin": { "type": "string", "example": "12345678901" }, "staff_id": { "type": "string", "example": "SA123" }, "dob": { "type": "string", "format": "date", "example": "1992-04-12" }, "year_of_employment": { "type": "integer", "example": 2022 }, "state": { "type": "string", "example": "Lagos" } }, "type": "object" }, "zonal_admin": { "properties": { "id": { "type": "integer", "example": 5 }, "surname": { "type": "string", "example": "Adeyemi" }, "first_name": { "type": "string", "example": "Tunde" }, "middle_name": { "type": "string", "example": "Olu" }, "email": { "type": "string", "example": "zonaladmin@example.com" }, "phone": { "type": "string", "example": "08098765432" } }, "type": "object", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/centre-admins": { "get": { "tags": [ "Api" ], "summary": "Get all Centre Admins", "operationId": "e907ee649da3a1151122530084d07af5", "responses": { "200": { "description": "List of Centre Admins" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/reset-user-password/{id}": { "post": { "tags": [ "Api" ], "summary": "Reset user password", "description": "Resets a user's password to a new random password and sends it via email.", "operationId": "resetUserPassword", "parameters": [ { "name": "id", "in": "path", "description": "ID of the user whose password will be reset", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Password reset successfully and email sent to user", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Password reset successfully and email sent to user" } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "User not found" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Something went wrong" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state-admin/centre-profile/{id}/edit": { "post": { "tags": [ "State Agency Admin" ], "summary": "Edit Centre Admin Profile by State Agency Admin", "description": "Allows a State Agency Admin to update a Centre Admin profile, only if the centre is within the same state. Supports photo and signature uploads.", "operationId": "editCentreAdminProfileByStateAdmin", "parameters": [ { "name": "id", "in": "path", "description": "ID of the centre whose admin profile is being edited", "required": true, "schema": { "type": "integer", "example": 15 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "surname": { "type": "string", "maxLength": 50, "example": "Doe" }, "first_name": { "type": "string", "maxLength": 50, "example": "John" }, "middle_name": { "type": "string", "maxLength": 50, "example": "A." }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "enum": [ "male", "female" ], "example": "male" }, "marital_status": { "type": "string", "example": "single" }, "centre_address": { "type": "string", "maxLength": 150, "example": "123 Example Street" }, "centre_ownership": { "type": "string", "maxLength": 50, "example": "Private" }, "photo": { "description": "Centre photo (jpeg, jpg, png)", "type": "string", "format": "binary" }, "signature": { "description": "Centre signature (jpeg, jpg, png)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Centre Admin profile updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Centre updated successfully" }, "data": { "type": "object" }, "photo_url": { "type": "string", "example": "http://localhost:8000/centre_photos/photo_uuid.jpg" }, "signature_url": { "type": "string", "example": "http://localhost:8000/centre_signatures/signature_uuid.png" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Unauthorized to edit centre outside your state", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthorized: You can only edit centres in your state" } }, "type": "object" } } } }, "404": { "description": "Centre or profile not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Centre or profile not found" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "example": { "phone": [ "The phone has already been taken." ] } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state-admin/reset-centre-admin-password/{id}": { "post": { "tags": [ "State Agency Admin" ], "summary": "Reset Centre Admin Password to Default", "description": "Allows a State Agency Admin to reset a Centre Admin's password to a default password (PassWord123!) if the centre belongs to the same state. The new password is emailed to the Centre Admin.", "operationId": "resetCentreAdminPasswordToDefault", "parameters": [ { "name": "id", "in": "path", "description": "ID of the centre whose admin password is to be reset", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Password reset successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Password reset successfully to default." }, "default_password": { "type": "string", "example": "PassWord123!" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden or Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthorized. You can only reset passwords of centres in your state." } }, "type": "object" } } } }, "404": { "description": "Centre Admin not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Centre Admin not found." } }, "type": "object" } } } }, "500": { "description": "Password reset but email failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "warning" }, "message": { "type": "string", "example": "Password reset but email failed." }, "error": { "type": "string", "example": "SMTP connection failed" }, "default_password": { "type": "string", "example": "PassWord123!" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre-admin/change-password": { "post": { "tags": [ "Centre" ], "summary": "Change password for Centre Admin", "operationId": "e2ed9483d62dcf6906bc98da23c27e96", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "current_password", "new_password", "new_password_confirmation" ], "properties": { "current_password": { "type": "string", "example": "oldpass123" }, "new_password": { "type": "string", "example": "newpass456" }, "new_password_confirmation": { "type": "string", "example": "newpass456" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password changed successfully" }, "401": { "description": "Incorrect current password" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state-admin/approved-centres": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get Approved Centres in State", "description": "Retrieves all centres with 'approved' status within the authenticated State Agency Admin's state.", "operationId": "getApprovedCentresInState", "responses": { "200": { "description": "Approved centres retrieved successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Approved centres retrieved successfully." }, "centres": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Centre Name" }, "status": { "type": "string", "example": "approved" }, "profile": { "properties": { "state_of_centre": { "type": "string", "example": "Lagos" }, "centre_address": { "type": "string", "example": "123 Centre Street" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "400": { "description": "State not found for the authenticated State Agency Admin.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "State not found for the authenticated State Agency Admin." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/programmes-with-subjects": { "get": { "tags": [ "Api" ], "summary": "Get all Programmes with their Subjects", "description": "Retrieves all programmes along with their associated subjects.", "operationId": "getProgrammesWithSubjects", "responses": { "200": { "description": "Programmes with subjects retrieved successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Programmes with subjects retrieved successfully." }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Science" }, "subjects": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 101 }, "name": { "type": "string", "example": "Biology" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/approved-centres": { "get": { "tags": [ "Api" ], "summary": "Get All Approved Centres", "description": "Fetches all centres with 'approved' status, including their associated profiles.", "operationId": "getAllApprovedCentres", "responses": { "200": { "description": "Approved centres retrieved successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Approved centres retrieved successfully." }, "centres": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Centre ABC" }, "status": { "type": "string", "example": "approved" }, "profile": { "properties": { "state_of_centre": { "type": "string", "example": "Lagos" }, "centre_address": { "type": "string", "example": "123 Example Road" }, "phone": { "type": "string", "example": "+2348012345678" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/programmes/{id}/edit": { "put": { "tags": [ "Api" ], "summary": "Edit a programme's name, description, and assigned subjects", "description": "Allows updating the name, description, and reassigning subjects of a programme. Any subjects not included in subject_ids will be removed from the programme.", "operationId": "editProgramme", "parameters": [ { "name": "id", "in": "path", "description": "ID of the programme to update", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Vocational Training Programme" }, "description": { "type": "string", "example": "Updated programme description for advanced training." }, "subject_ids": { "description": "Array of subject IDs to assign to the programme. Replaces all current assignments.", "type": "array", "items": { "type": "integer", "example": 1 } } }, "type": "object" } } } }, "responses": { "200": { "description": "Programme updated successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Programme updated successfully." }, "programme": { "description": "The updated programme with its assigned subjects", "type": "object" } }, "type": "object" } } } }, "404": { "description": "Programme not found." }, "422": { "description": "Validation error - invalid input." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/subjects/{id}/edit": { "put": { "tags": [ "Api" ], "summary": "Update subject details", "description": "Updates subject information such as name, description, or curriculum.", "operationId": "editSubject", "parameters": [ { "name": "id", "in": "path", "description": "Subject ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Mathematics" }, "description": { "type": "string", "example": "Basic mathematics studies" }, "curriculum": { "type": "string", "example": "Algebra, Geometry" } }, "type": "object" } } } }, "responses": { "200": { "description": "Subject updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Subject updated successfully." }, "subject": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Mathematics" }, "description": { "type": "string", "example": "Basic mathematics studies" }, "curriculum": { "type": "string", "example": "Algebra, Geometry" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Subject not found" }, "422": { "description": "Validation error" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/learner/change-password": { "post": { "tags": [ "Learner" ], "summary": "Change Learner Password", "description": "Allows an authenticated learner to change their password by providing the current and new password.", "operationId": "changeLearnerPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "current_password", "new_password", "new_password_confirmation" ], "properties": { "current_password": { "type": "string", "example": "oldPassword123" }, "new_password": { "type": "string", "format": "password", "example": "newPassword456" }, "new_password_confirmation": { "type": "string", "format": "password", "example": "newPassword456" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password changed successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Password changed successfully." } }, "type": "object" } } } }, "422": { "description": "Validation failed or current password incorrect.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Current password is incorrect." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre-admin/learners/{id}/approve": { "post": { "tags": [ "Centre" ], "summary": "Approve Learner", "description": "Approves a learner by setting their status to 'approved'.", "operationId": "approveLearner", "parameters": [ { "name": "id", "in": "path", "description": "ID of the learner to approve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Learner approved successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Learner approved successfully." } }, "type": "object" } } } }, "404": { "description": "Learner not found.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "No query results for model [App\\\\Models\\\\Learner] 10" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre-admin/learners/{id}/reject": { "post": { "tags": [ "Centre" ], "summary": "Reject Learner", "description": "Rejects a learner by setting their status to 'rejected'.", "operationId": "rejectLearner", "parameters": [ { "name": "id", "in": "path", "description": "ID of the learner to reject", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Learner rejected successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Learner rejected successfully." } }, "type": "object" } } } }, "404": { "description": "Learner not found.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "No query results for model [App\\\\Models\\\\Learner] 99" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre-admin/learners/{id}/edit": { "post": { "tags": [ "Centre" ], "summary": "Update Learner by Centre Admin", "description": "Allows a Centre Admin to update a learner that belongs to their centre. All fields are optional.", "operationId": "updateLearnerByCentreAdmin", "parameters": [ { "name": "id", "in": "path", "description": "Learner ID", "required": true, "schema": { "type": "integer", "example": 15 } } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "properties": { "surname": { "type": "string", "example": "Okafor" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "David", "nullable": true }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "enum": [ "Male", "Female", "Other" ], "example": "Male" }, "date_of_birth": { "type": "string", "format": "date", "example": "1998-05-10" }, "snap_picture": { "description": "Learner snap picture (jpg, jpeg, png)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Learner updated successfully" }, "401": { "description": "Unauthenticated" }, "404": { "description": "Learner not found" }, "422": { "description": "Validation error" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/delete-programmes/{id}": { "delete": { "tags": [ "Api" ], "summary": "Delete a Programme", "description": "Deletes a programme by ID, including all associated subjects. Returns 404 if the programme is not found.", "operationId": "deleteProgramme", "parameters": [ { "name": "id", "in": "path", "description": "ID of the programme to delete", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Programme and its subjects deleted successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Programme and its subjects deleted successfully." } }, "type": "object" } } } }, "404": { "description": "Programme not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Programme not found." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/delete-subjects/{id}": { "delete": { "tags": [ "Api" ], "summary": "Delete Subject", "description": "Deletes a subject by its ID. Returns 404 if the subject is not found.", "operationId": "deleteSubject", "parameters": [ { "name": "id", "in": "path", "description": "ID of the subject to delete", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Subject deleted successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Subject deleted successfully." } }, "type": "object" } } } }, "404": { "description": "Subject not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Subject not found." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/centre/{id}": { "get": { "tags": [ "Api" ], "summary": "Get Centre by ID", "description": "Retrieves a specific centre including profile, programmes, learners statistics, facilitators statistics and certificate information.", "operationId": "getCentreById", "parameters": [ { "name": "id", "in": "path", "description": "ID of the centre", "required": true, "schema": { "type": "integer", "example": 15 } } ], "responses": { "200": { "description": "Centre retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Centre retrieved successfully" }, "data": { "properties": { "centre": { "properties": { "id": { "type": "integer", "example": 15 }, "centre_id": { "type": "string", "example": "NMEC/ANAMB/00001" }, "registered_name": { "type": "string", "example": "Awka Community Learning Centre" }, "email": { "type": "string", "example": "centre@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "community_type": { "type": "string", "example": "Community" }, "ownership": { "type": "string", "example": "Private" }, "zone": { "type": "string", "example": "South East" }, "state": { "type": "string", "example": "Anambra" }, "lga": { "type": "string", "example": "Awka South" }, "ward": { "type": "string", "example": "Ward 3" }, "latitude": { "type": "string", "example": "6.2100" }, "longitude": { "type": "string", "example": "7.0700" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "boolean", "example": true }, "picture": { "type": "string", "example": "https://example.com/uploads/centre.png" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-10 10:20:30" } }, "type": "object" }, "profile": { "properties": { "state_of_centre": { "type": "string", "example": "Anambra" }, "centre_address": { "type": "string", "example": "123 Centre Road" }, "centre_ownership": { "type": "string", "example": "Private" } }, "type": "object", "nullable": true }, "programmes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Literacy Programme" }, "description": { "type": "string", "example": "Basic adult literacy programme" } }, "type": "object" } }, "statistics": { "properties": { "total_learners": { "type": "integer", "example": 120 }, "total_facilitators": { "type": "integer", "example": 6 } }, "type": "object" }, "certificate": { "properties": { "id": { "type": "integer", "example": 5 }, "centre_id": { "type": "string", "example": "NMEC/ANAMB/00001" }, "certificate_number": { "type": "string", "example": "CERT-2026-001" } }, "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Centre not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Centre not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state-agency-admin/centre/{id}": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get Centre by ID (State Agency Admin)", "description": "Allows a State Agency Admin to retrieve a centre by ID. The centre must belong to the same state as the authenticated State Agency Admin.", "operationId": "getCentreByIdStateAgencyAdmin", "parameters": [ { "name": "id", "in": "path", "description": "ID of the centre", "required": true, "schema": { "type": "integer", "example": 15 } } ], "responses": { "200": { "description": "Centre retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Centre retrieved successfully" }, "data": { "properties": { "centre": { "properties": { "id": { "type": "integer", "example": 15 }, "centre_id": { "type": "string", "example": "NMEC/ANAMB/00001" }, "registered_name": { "type": "string", "example": "Awka Community Learning Centre" }, "email": { "type": "string", "example": "centre@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "community_type": { "type": "string", "example": "Community" }, "ownership": { "type": "string", "example": "Private" }, "zone": { "type": "string", "example": "South East" }, "state": { "type": "string", "example": "Anambra" }, "lga": { "type": "string", "example": "Awka South" }, "ward": { "type": "string", "example": "Ward 3" }, "latitude": { "type": "string", "example": "6.2100" }, "longitude": { "type": "string", "example": "7.0700" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "boolean", "example": true }, "picture": { "type": "string", "example": "https://example.com/uploads/centre.png" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-10 10:20:30" } }, "type": "object" }, "profile": { "description": "Centre profile information", "type": "object", "nullable": true }, "programmes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Adult Literacy Programme" }, "description": { "type": "string", "example": "Basic literacy programme" } }, "type": "object" } }, "statistics": { "properties": { "total_learners": { "type": "integer", "example": 120 }, "total_facilitators": { "type": "integer", "example": 6 } }, "type": "object" }, "certificate": { "description": "Centre certificate information", "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "404": { "description": "Centre not found in the state", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Centre not found in your state" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre-admin/list-all-subjects": { "get": { "tags": [ "Centre" ], "summary": "Get all subjects", "description": "Returns a list of all available subjects.", "operationId": "getAllSubjects", "responses": { "200": { "description": "List of all subjects", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "List of all subjects" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Mathematics" }, "description": { "type": "string", "example": "Basic Math concepts" }, "curriculum": { "type": "string", "example": "Curriculum content here" }, "programme_id": { "type": "integer", "example": 2 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-07-01T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-07-02T15:00:00Z" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/national-officers/{userId}/edit-profile": { "put": { "tags": [ "Api" ], "summary": "Edit National Officer profile (Super Admin only)", "operationId": "editNationalOfficerProfileSuper", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "passport": { "type": "string", "format": "binary" }, "signature": { "type": "string", "format": "binary" }, "gender": { "type": "string" }, "marital_status": { "type": "string" }, "staff_id": { "type": "string" }, "dob": { "type": "string", "format": "date" }, "year_of_employment": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success" }, "422": { "description": "No valid fields" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/national-officer/profile": { "get": { "tags": [ "National Officers" ], "summary": "Get National Officer Profile", "description": "Retrieve the authenticated National Officer's user and profile information.", "operationId": "getNationalOfficerProfile", "responses": { "200": { "description": "Profile retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "National Officer profile retrieved successfully" }, "user": { "properties": { "id": { "type": "integer", "example": 5 }, "surname": { "type": "string", "example": "Okafor" }, "first_name": { "type": "string", "example": "Chioma" }, "middle_name": { "type": "string", "example": "Grace" }, "email": { "type": "string", "example": "chioma@gmail.com" }, "phone": { "type": "string", "example": "08012345678" }, "roles": { "type": "array", "items": { "type": "string", "example": "National Officer" } } }, "type": "object" }, "profile": { "properties": { "gender": { "type": "string", "example": "female" }, "marital_status": { "type": "string", "example": "single" }, "staff_id": { "type": "string", "example": "NAT12345" }, "dob": { "type": "string", "format": "date", "example": "1990-04-10" }, "year_of_employment": { "type": "integer", "example": 2015 }, "passport": { "type": "string", "example": "passports/abc.jpg" }, "signature": { "type": "string", "example": "signatures/def.jpg" }, "passport_url": { "type": "string", "format": "url", "example": "http://yourdomain.com/storage/passports/abc.jpg" }, "signature_url": { "type": "string", "format": "url", "example": "http://yourdomain.com/storage/signatures/def.jpg" } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state-agency-admin/profile": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get State Agency Admin Profile", "description": "Retrieve the authenticated State Agency Admin's user and profile information.", "operationId": "getStateAgencyAdminProfile", "responses": { "200": { "description": "Profile retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "State Agency Admin profile retrieved successfully" }, "user": { "properties": { "id": { "type": "integer", "example": 3 }, "surname": { "type": "string", "example": "Abdullahi" }, "first_name": { "type": "string", "example": "Zainab" }, "middle_name": { "type": "string", "example": "T." }, "email": { "type": "string", "example": "zainab@gmail.com" }, "phone": { "type": "string", "example": "08023456789" }, "roles": { "type": "array", "items": { "type": "string", "example": "State Agency Admin" } } }, "type": "object" }, "profile": { "properties": { "gender": { "type": "string", "example": "female" }, "marital_status": { "type": "string", "example": "married" }, "nin": { "type": "string", "example": "12345678901" }, "staff_id": { "type": "string", "example": "STA99988" }, "dob": { "type": "string", "format": "date", "example": "1986-03-15" }, "year_of_employment": { "type": "integer", "example": 2012 }, "state": { "type": "string", "example": "Kaduna" }, "passport": { "type": "string", "example": "passports/zainab.jpg" }, "signature": { "type": "string", "example": "signatures/zainab.png" }, "passport_url": { "type": "string", "format": "url", "example": "http://yourdomain.com/storage/passports/zainab.jpg" }, "signature_url": { "type": "string", "format": "url", "example": "http://yourdomain.com/storage/signatures/zainab.png" } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/get-centre-admin-learners": { "get": { "tags": [ "Centre" ], "summary": "Retrieve all learners for the authenticated centre admin", "description": "Returns a list of learners along with their profiles and programme information. Requires centre admin authentication.", "operationId": "getCentreLearners", "responses": { "200": { "description": "Successful retrieval of learners", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_learners": { "type": "integer", "example": 15 }, "learners": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "johndoe@example.com" }, "profile": { "properties": { "age": { "type": "integer", "example": 20 }, "gender": { "type": "string", "example": "male" } }, "type": "object" }, "programme": { "properties": { "id": { "type": "integer", "example": 101 }, "name": { "type": "string", "example": "Computer Science" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre-admin/facilitators/{facilitatorId}/programs": { "put": { "tags": [ "Centre" ], "summary": "Assign one or multiple programmes to an approved facilitator", "description": "Centre Admin can assign programmes only to facilitators with status 'approved'. Accepts single or multiple programme IDs in an array.", "operationId": "a88e86bbbc9f6cd969480e855207cac7", "parameters": [ { "name": "facilitatorId", "in": "path", "description": "ID of the facilitator", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "programmes" ], "properties": { "programmes": { "description": "Array of programme IDs. Can contain one or multiple IDs.", "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Programs assigned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Programs assigned successfully." }, "facilitator": { "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "Tolu Arokodare" }, "email": { "type": "string", "example": "tolu@gmail.com" }, "status": { "type": "string", "example": "approved" }, "programmes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Basic Literacy" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Only approved facilitators can be assigned" }, "404": { "description": "Facilitator not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state-admin/certificates": { "get": { "tags": [ "State Agency Admin" ], "summary": "Retrieve all certificates for the State Agency Admin", "description": "Returns all certificates associated with the State Agency Admin's state. Requires State Agency Admin role.", "operationId": "getStateAdminCertificates", "responses": { "200": { "description": "Certificates retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "state": { "type": "string", "example": "Delta" }, "total_certificates": { "type": "integer", "example": 2 }, "certificates": { "type": "array", "items": { "properties": { "certificate_id": { "type": "string", "example": "ABC20260001" }, "registered_name": { "type": "string", "example": "ABC Learning Centre" }, "email": { "type": "string", "example": "abc@gmail.com" }, "phone": { "type": "string", "example": "+2348012341678" }, "centre_id": { "type": "string", "example": "abc2025004" }, "status": { "type": "string", "example": "approved" }, "approval_date": { "type": "string", "format": "date-time", "example": "2026-03-04T05:30:52" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "photo": { "type": "string", "example": "centre/photos/photo.jpg" }, "signature": { "type": "string", "example": "centre/signatures/signature.jpg" }, "state_of_centre": { "type": "string", "example": "Delta" }, "lga_of_centre": { "type": "string", "example": "Delta LGA" }, "centre_address": { "type": "string", "example": "123 Example Street" }, "programmes": { "type": "array", "items": { "type": "string" }, "example": [ "Literacy", "Philosophy" ] }, "establishment_year": { "type": "integer", "example": 2025 }, "centre_ownership": { "type": "string", "example": "Private" }, "days_of_operation": { "type": "array", "items": { "type": "string" }, "example": [ "Monday", "Tuesday" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-04T05:30:52" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-03-04T05:30:52" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized action", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthorized action." } }, "type": "object" } } } }, "404": { "description": "Admin profile not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Admin profile not found." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre-admin/certificate": { "get": { "tags": [ "Centre" ], "summary": "Retrieve the Centre Admin's certificate", "description": "Returns the certificate for the authenticated Centre Admin based on their centre_id.", "operationId": "getMyCertificate", "responses": { "200": { "description": "Certificate retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "certificate": { "properties": { "certificate_id": { "type": "string", "example": "ABC20260001" }, "registered_name": { "type": "string", "example": "ABC Learning Centre" }, "email": { "type": "string", "example": "abc@gmail.com" }, "phone": { "type": "string", "example": "+2348012341678" }, "centre_id": { "type": "string", "example": "abc2025004" }, "status": { "type": "string", "example": "approved" }, "approval_date": { "type": "string", "format": "date-time", "example": "2026-03-04T05:30:52" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "photo": { "type": "string", "example": "centre/photos/photo.jpg" }, "signature": { "type": "string", "example": "centre/signatures/signature.jpg" }, "state_of_centre": { "type": "string", "example": "Delta" }, "lga_of_centre": { "type": "string", "example": "Delta LGA" }, "centre_address": { "type": "string", "example": "123 Example Street" }, "programmes": { "type": "array", "items": { "type": "string" }, "example": [ "Literacy", "Philosophy" ] }, "establishment_year": { "type": "integer", "example": 2025 }, "centre_ownership": { "type": "string", "example": "Private" }, "days_of_operation": { "type": "array", "items": { "type": "string" }, "example": [ "Monday", "Tuesday" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-04T05:30:52" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-03-04T05:30:52" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized action", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthorized action." } }, "type": "object" } } } }, "404": { "description": "Certificate not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Certificate not found for your centre." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/facilitator/edit-profile": { "post": { "tags": [ "Facilitator" ], "summary": "Edit Facilitator Profile", "description": "Allows an authenticated facilitator to update personal and profile information including snap picture.", "operationId": "editFacilitatorProfile", "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "properties": { "surname": { "type": "string", "example": "John" }, "first_name": { "type": "string", "example": "Doe" }, "middle_name": { "type": "string", "example": "A" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "male" }, "date_of_birth": { "type": "string", "format": "date", "example": "1990-05-10" }, "snap_picture": { "description": "Facilitator profile picture (jpg, jpeg, png max 2MB)", "type": "string", "format": "binary" }, "marital_status": { "type": "string", "example": "Single" }, "state_of_origin": { "type": "string", "example": "Lagos" }, "lga_of_origin": { "type": "string", "example": "Ikeja" }, "home_town": { "type": "string", "example": "Ikeja" }, "state_of_residence": { "type": "string", "example": "Abuja" }, "lga_of_residence": { "type": "string", "example": "Gwagwalada" }, "residential_address": { "type": "string", "example": "12 Example Street" }, "nin": { "type": "string", "example": "12345678901" }, "course_of_study": { "type": "string", "example": "Computer Science" }, "highest_qualification_dates": { "type": "string", "example": "2018-2022" } }, "type": "object" } } } }, "responses": { "200": { "description": "Facilitator profile updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Facilitator profile updated successfully" }, "facilitator": { "properties": { "surname": { "type": "string", "example": "John" }, "first_name": { "type": "string", "example": "Doe" }, "middle_name": { "type": "string", "example": "A" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "male" }, "date_of_birth": { "type": "string", "example": "1990-05-10" } }, "type": "object" }, "profile": { "type": "object" }, "snap_picture_url": { "type": "string", "example": "http://localhost/facilitator_snaps/facilitator_snap_12345.jpg" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/user-statistics": { "get": { "tags": [ "Api" ], "summary": "Get total number of users by role with status breakdown (Super Admin only)", "description": "Returns total count and status counts for National Admin, State Admin, Centre Admin, Learners, and Facilitators. Accessible by Super Admin only.", "operationId": "getUserStatistics", "responses": { "200": { "description": "User statistics fetched successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "National Officer": { "properties": { "total": { "type": "integer", "example": 10 }, "statuses": { "properties": { "pending": { "type": "integer", "example": 2 }, "approved": { "type": "integer", "example": 7 }, "rejected": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden. Only Super Admin can access this" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/learners-per-centre": { "get": { "tags": [ "Api" ], "summary": "Get total learners per centre", "description": "Returns the total number of learners enrolled in each centre. Accessible only by Super Admin.", "operationId": "49b9d4e0b64fa528b71aa0942aa74f6d", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "properties": { "registered_name": { "type": "string", "example": "ABC Learning Centre" }, "centre_id": { "type": "string", "example": "abc2025001" }, "total_learners": { "type": "integer", "example": 10 } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthorized. Only Super Admin can access this." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/assign-learners": { "post": { "tags": [ "Centre" ], "summary": "Assign learners to a facilitator", "description": "Allows a Centre Admin to assign one or more learners under their centre to a specific facilitator.", "operationId": "276bdd92131b2d15e169d3ed83c658ef", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "facilitator_id", "learner_ids" ], "properties": { "facilitator_id": { "description": "ID of the facilitator to assign learners to", "type": "integer", "example": 4 }, "learner_ids": { "description": "Array of learner IDs to be assigned", "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Learners successfully assigned", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Learners successfully assigned to facilitator" }, "assigned_learner_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] } }, "type": "object" } } } }, "403": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "errors": { "type": "object", "example": { "facilitator_id": [ "The selected facilitator id is invalid." ] } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/facilitator/{id}/programmes": { "get": { "tags": [ "Facilitator" ], "summary": "Get facilitator's programmes", "description": "Retrieve the number of programmes and their names assigned to a specific facilitator", "operationId": "976eb01b7a4ab7b246c84d98ff3e9931", "parameters": [ { "name": "id", "in": "path", "description": "Facilitator ID", "required": true, "schema": { "type": "integer", "example": 5 } } ], "responses": { "200": { "description": "Facilitator programmes retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "facilitator_id": { "type": "integer", "example": 5 }, "programme_count": { "type": "integer", "example": 2 }, "programmes": { "type": "array", "items": { "type": "string", "example": "Basic Literacy" } } }, "type": "object" } } } }, "404": { "description": "Facilitator not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Facilitator not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/facilitator/{id}/learners-count": { "get": { "tags": [ "Facilitator" ], "summary": "Get the number of learners assigned to a facilitator", "description": "Returns the total number of learners assigned to a specific facilitator along with their IDs.", "operationId": "getFacilitatorLearnerCount", "parameters": [ { "name": "id", "in": "path", "description": "Facilitator ID", "required": true, "schema": { "type": "integer", "example": 5 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "facilitator_id": { "type": "integer", "example": 5 }, "total_learners": { "type": "integer", "example": 2 }, "learner_ids": { "type": "array", "items": { "type": "integer", "example": 1 } } }, "type": "object" } } } }, "404": { "description": "Facilitator not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Facilitator not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/facilitators": { "get": { "tags": [ "Centre" ], "summary": "Get all facilitators for a Centre Admin", "description": "Allows a Centre Admin to fetch all facilitators assigned to their centre.", "operationId": "getAllFacilitators", "responses": { "200": { "description": "List of facilitators", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "facilitators": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 5 }, "facilitator_id": { "type": "string", "example": "2026159781" }, "first_name": { "type": "string", "example": "Tom" }, "surname": { "type": "string", "example": "Osagie" }, "middle_name": { "type": "string", "example": "Aslem" }, "email": { "type": "string", "example": "tom@gmail.com" }, "phone": { "type": "string", "example": "+2348012845678" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "boolean", "example": true }, "profile": { "properties": { "photo": { "type": "string", "example": "facilitator_photos/photo_1772596258.jpg" }, "gender": { "type": "string", "example": "Male" }, "centre_of_choice": { "type": "integer", "example": 14 } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthorized. Only Centre Admin can access this." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/facilitators": { "get": { "tags": [ "Api" ], "summary": "Get all facilitators for Super Admin", "description": "Allows Super Admin to fetch all facilitators in the system.", "operationId": "getAllFacilitatorsAdmin", "responses": { "200": { "description": "List of facilitators", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "facilitators": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 5 }, "facilitator_id": { "type": "string", "example": "2026159781" }, "first_name": { "type": "string", "example": "Tom" }, "surname": { "type": "string", "example": "Osagie" }, "middle_name": { "type": "string", "example": "Aslem" }, "email": { "type": "string", "example": "tom@gmail.com" }, "phone": { "type": "string", "example": "+2348012845678" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "boolean", "example": true }, "profile": { "properties": { "photo": { "type": "string", "example": "facilitator_photos/photo_1772596258.jpg" }, "gender": { "type": "string", "example": "Male" }, "centre_of_choice": { "type": "integer", "example": 14 } }, "type": "object" }, "total_learners": { "type": "integer", "example": 25 }, "total_programmes": { "type": "integer", "example": 3 } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthorized. Only Super Admin can access this." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/facilitator/centre": { "get": { "tags": [ "Facilitator" ], "summary": "Get the centre of the authenticated facilitator", "description": "Returns the details of the centre that the authenticated facilitator belongs to.", "operationId": "getCentreForFacilitator", "responses": { "200": { "description": "Centre retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "facilitator_id": { "type": "string", "example": "NMEC/ANAMB/00001/F0001" }, "facilitator_name": { "type": "string", "example": "Mary Emeka" }, "centre": { "properties": { "id": { "type": "integer", "example": 1 }, "centre_id": { "type": "string", "example": "NMEC/ANAMB/00001" }, "registered_name": { "type": "string", "example": "Anambra Centre" }, "email": { "type": "string", "example": "info@anambra-centre.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "status": { "type": "string", "example": "approved" }, "latitude": { "type": "string", "example": "6.2146" }, "longitude": { "type": "string", "example": "6.7916" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-07T20:52:39" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. Facilitator not authenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthorized. Facilitator access only." } }, "type": "object" } } } }, "404": { "description": "Facilitator has no assigned centre", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "No centre assigned to this facilitator." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/facilitator/profile": { "get": { "tags": [ "Facilitator" ], "summary": "View authenticated facilitator profile", "description": "Returns the authenticated facilitator's main details and profile information", "operationId": "viewFacilitatorProfile", "responses": { "200": { "description": "Profile retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "facilitator": { "properties": { "facilitator_id": { "type": "string", "example": "2026159781" }, "surname": { "type": "string", "example": "Osagie" }, "first_name": { "type": "string", "example": "Tom" }, "middle_name": { "type": "string", "example": "Aslem" }, "email": { "type": "string", "example": "tom@gmail.com" }, "phone": { "type": "string", "example": "+2348012845678" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "boolean", "example": true }, "email_verified_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "profile": { "properties": { "photo": { "type": "string", "example": "facilitator_photos/photo.jpg" }, "phone": { "type": "string", "example": "+2348012845678" }, "gender": { "type": "string", "example": "Male" }, "marital_status": { "type": "string", "example": "Single" }, "state_of_origin": { "type": "string", "example": "Lagos" }, "lga_of_origin": { "type": "string", "example": "Ikeja" }, "home_town": { "type": "string", "example": "Ikeja" }, "state_of_residence": { "type": "string", "example": "Abuja" }, "lga_of_residence": { "type": "string", "example": "Gwagwalada" }, "residential_address": { "type": "string", "example": "No 12 Example Street" }, "last_sch_attended": { "type": "string", "example": "University of Lagos" }, "reason_for_leaving": { "type": "string", "example": "Graduated" }, "centre_of_choice": { "type": "integer", "example": 14 }, "any_other_info": { "type": "string", "example": "Additional notes" }, "date_of_birth": { "type": "string", "format": "date" }, "nin": { "type": "string", "example": "12345678901" }, "highest_qualification_dates": { "type": "string", "example": "2015-2019" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/learner/profile": { "get": { "tags": [ "Learner" ], "summary": "Get authenticated learner profile", "description": "Returns the authenticated learner details with centre, programme and profile information", "operationId": "viewLearnerProfile", "responses": { "200": { "description": "Profile retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "learner": { "properties": { "learner_id": { "type": "string", "example": "NMEC/ANAMB/00001/0001" }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Smith" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Male" }, "status": { "type": "string", "example": "pending" }, "profile_completed": { "type": "boolean", "example": true }, "centre": { "properties": { "id": { "type": "integer", "example": 15 }, "registered_name": { "type": "string", "example": "Lagos Learning Centre" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" }, "centre_id": { "type": "string", "example": "lag2025002" } }, "type": "object", "nullable": true }, "programme": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Basic Literacy" }, "description": { "type": "string", "example": "Your basic literacy skills start here" } }, "type": "object", "nullable": true } }, "type": "object" }, "profile": { "properties": { "photo": { "type": "string", "example": "learner_photos/photo.jpg" }, "marital_status": { "type": "string", "example": "Single" }, "state_of_origin": { "type": "string", "example": "Anambra" }, "lga_of_origin": { "type": "string", "example": "Awka South" }, "home_town": { "type": "string", "example": "Awka" }, "state_of_residence": { "type": "string", "example": "Lagos" }, "lga_of_residence": { "type": "string", "example": "Ikeja" }, "residential_address": { "type": "string", "example": "12 Example Street" }, "last_sch_attended": { "type": "string", "example": "University of Lagos" }, "reason_for_leaving": { "type": "string", "example": "Graduated" }, "any_other_info": { "type": "string", "example": "No additional information" }, "nin": { "type": "string", "example": "12345678901" }, "highest_qualification_dates": { "type": "string", "example": "BSc 2021" }, "signature": { "type": "string", "example": "learner_signatures/signature.png" } }, "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/facilitator/learners/gender-count": { "get": { "tags": [ "Facilitator" ], "summary": "Get gender count of learners assigned to the authenticated facilitator", "description": "Returns the number of male, female, and other learners assigned to the logged-in facilitator based on programme and centre. Useful for dashboards and charts.", "operationId": "getLearnersGenderCount", "responses": { "200": { "description": "Gender counts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "male": { "type": "integer", "example": 12 }, "female": { "type": "integer", "example": 15 }, "other": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/learners/gender-count": { "get": { "tags": [ "Centre" ], "summary": "Get gender count of learners in the authenticated centre", "description": "Returns the number of male and female learners assigned to the logged-in centre. Useful for charting purposes.", "operationId": "getLearnersGenderCountByCentre", "responses": { "200": { "description": "Gender counts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "male": { "type": "integer", "example": 25 }, "female": { "type": "integer", "example": 30 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/enrollment-chart": { "get": { "tags": [ "Centre" ], "summary": "Get learner enrollment chart for the authenticated centre", "description": "Returns the number of learners enrolled per week or per month for the centre. Useful for charting enrollment trends.", "operationId": "getEnrollmentChartByCentre", "parameters": [ { "name": "period", "in": "query", "description": "Chart period: weekly or monthly (default: weekly)", "required": false, "schema": { "type": "string", "default": "weekly", "enum": [ "weekly", "monthly" ] } } ], "responses": { "200": { "description": "Enrollment data retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "period": { "type": "string", "example": "weekly" }, "data": { "type": "object", "example": { "Year 2026 Week 9": 5, "Year 2026 Week 10": 8, "Year 2026 Week 11": 12 } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/programmes": { "post": { "tags": [ "Centre" ], "summary": "Assign programmes to centre", "description": "Allows a Centre Admin to assign multiple programmes created by the Super Admin to their centre.", "operationId": "addProgrammesToCentre", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "programme_ids" ], "properties": { "programme_ids": { "description": "Array of programme IDs to assign to the centre", "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Programmes assigned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Programmes assigned to centre successfully." }, "total_programmes": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/programmes/count": { "get": { "tags": [ "Centre" ], "summary": "Get total number of programmes assigned to centre", "description": "Returns the total number of programmes the authenticated centre admin is running.", "operationId": "getCentreProgrammesCount", "responses": { "200": { "description": "Total programmes fetched successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_programmes": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/learners/count": { "get": { "tags": [ "Centre" ], "summary": "Get total number of learners under the centre", "description": "Returns the total number of learners assigned to the authenticated centre admin.", "operationId": "getCentreLearnersCount", "responses": { "200": { "description": "Total learners fetched successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_learners": { "type": "integer", "example": 25 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/facilitators/count": { "get": { "tags": [ "Centre" ], "summary": "Get total number of facilitators under the centre", "description": "Returns the total number of facilitators assigned to the authenticated centre admin.", "operationId": "getCentreFacilitatorsCount", "responses": { "200": { "description": "Total facilitators fetched successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_facilitators": { "type": "integer", "example": 12 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/learners/reset-password": { "post": { "tags": [ "Centre" ], "summary": "Reset a learner's password to default", "description": "Allows a Centre Admin to reset a learner's password to the default password 'PassWord123!'.", "operationId": "163f5686481a39b62aa53c26fd03b335", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "learner_id" ], "properties": { "learner_id": { "description": "ID of the learner whose password is being reset", "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Password reset successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Learner's password has been reset successfully." }, "default_password": { "type": "string", "example": "PassWord123!" } }, "type": "object" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The learner_id field is required." }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/facilitators/reset-password": { "post": { "tags": [ "Centre" ], "summary": "Reset a facilitator's password to default", "description": "Allows a Centre Admin to reset a facilitator's password to the default password 'PassWord123!'.", "operationId": "abd42ab418fa6f2cb56b2af992040836", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "facilitator_id" ], "properties": { "facilitator_id": { "description": "ID of the facilitator whose password is being reset", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "Password reset successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Facilitator's password has been reset successfully." }, "default_password": { "type": "string", "example": "PassWord123!" } }, "type": "object" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The facilitator_id field is required." }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/programmes/{id}/subjects": { "get": { "tags": [ "Api" ], "summary": "Get all subjects assigned to a programme", "description": "Retrieve all subjects linked to a specific programme", "operationId": "getProgrammeSubjects", "parameters": [ { "name": "id", "in": "path", "description": "Programme ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Subjects retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "programme_id": { "type": "integer", "example": 1 }, "subjects": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Mathematics" }, "description": { "type": "string", "example": "Basic mathematics" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Programme not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/programmes/{id}/subjects/{subject_id}": { "delete": { "tags": [ "Api" ], "summary": "Remove subject from programme", "description": "Detach a subject from a programme", "operationId": "removeSubjectFromProgramme", "parameters": [ { "name": "id", "in": "path", "description": "Programme ID", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "subject_id", "in": "path", "description": "Subject ID", "required": true, "schema": { "type": "integer", "example": 2 } } ], "responses": { "200": { "description": "Subject removed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Subject removed from programme successfully" } }, "type": "object" } } } }, "404": { "description": "Programme or Subject not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/subjects": { "get": { "tags": [ "Api" ], "summary": "Get all subjects", "description": "Retrieve all subjects available in the system", "operationId": "getSubjects", "responses": { "200": { "description": "Subjects retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "subjects": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Mathematics" }, "description": { "type": "string", "example": "Basic Mathematics" }, "curriculum": { "type": "string", "example": "Primary curriculum" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/get-centre-certificate": { "get": { "tags": [ "Certificate" ], "summary": "Get certificate for a specific centre", "description": "Retrieve the certificate details for a given centre using its centre_id", "operationId": "getCentreCertificate", "parameters": [ { "name": "centre_id", "in": "query", "description": "The unique ID of the centre", "required": true, "schema": { "type": "string", "example": "NMEC/ANAMB/00001" } } ], "responses": { "200": { "description": "Certificate found successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "certificate": { "type": "object", "example": { "id": 1, "centre_id": "NMEC/ANAMB/00001", "certificate_number": "CERT/2025/001", "issued_at": "2025-06-30", "valid_until": "2026-06-30", "created_at": "2025-06-21 16:59:35", "updated_at": "2025-06-21 16:59:35" } } }, "type": "object" } } } }, "404": { "description": "Certificate not found for this centre", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Certificate not found for this centre." } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The centre_id field is required." }, "errors": { "properties": { "centre_id": { "type": "array", "items": { "type": "string", "example": "The selected centre_id is invalid." } } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/centre/profile": { "get": { "tags": [ "Centre" ], "summary": "Retrieve the authenticated centre admin's full profile", "description": "Returns the authenticated centre admin's profile along with related data such as programmes, learners, facilitators, and certificate. Requires centre admin authentication.", "operationId": "getFullCentreProfile", "responses": { "200": { "description": "Successfully retrieved centre profile", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "centre": { "properties": { "id": { "type": "integer", "example": 1 }, "registered_name": { "type": "string", "example": "Bright Futures Centre" }, "email": { "type": "string", "example": "centre@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "community_type": { "type": "string", "example": "Urban" }, "profile_completed": { "type": "boolean", "example": true }, "picture": { "type": "string", "example": "https://example.com/images/centre.jpg" }, "profile": { "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "middle_name": { "type": "string", "example": "Michael" }, "gender": { "type": "string", "example": "male" }, "state_of_origin": { "type": "string", "example": "Lagos" }, "programmes": { "type": "array", "items": { "type": "string", "example": "Computer Science" } } }, "type": "object" }, "programmes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 101 }, "name": { "type": "string", "example": "Computer Science" } }, "type": "object" } }, "learners": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 201 }, "name": { "type": "string", "example": "Jane Learner" } }, "type": "object" } }, "facilitators": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 301 }, "name": { "type": "string", "example": "Mr. Facilitator" } }, "type": "object" } }, "certificate": { "properties": { "certificate_number": { "type": "string", "example": "CERT-123456" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/programmes-with-subjects": { "get": { "tags": [ "Centre" ], "summary": "Get all programmes under the authenticated centre with their subjects", "description": "Returns a list of all programmes assigned to the currently authenticated Centre Admin, including the subjects under each programme.", "operationId": "828d7c518d8beecba7f5230dd191e2d0", "responses": { "200": { "description": "Successful response with programmes and subjects", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_programmes": { "type": "integer", "example": 2 }, "programmes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 6 }, "name": { "type": "string", "example": "Software Engineering" }, "description": { "type": "string", "example": "Programme for learning software development" }, "subjects": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "Mathematics" }, "description": { "type": "string", "example": "This subject covers algebra, geometry, etc." }, "curriculum": { "type": "string", "example": "Nigerian Secondary Curriculum 2024" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated - invalid or missing token", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/approved-learners": { "get": { "tags": [ "Centre" ], "summary": "Get all approved learners for the authenticated centre", "description": "Returns a list of all learners whose status is 'approved' under the currently authenticated Centre Admin", "operationId": "41f46a0e72ae0deb9acd68ebf43f0652", "responses": { "200": { "description": "Successful response with approved learners", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_learners": { "type": "integer", "example": 3 }, "learners": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "learner_id": { "type": "string", "example": "2025643498" }, "surname": { "type": "string", "example": "Emeka" }, "first_name": { "type": "string", "example": "Pero" }, "middle_name": { "type": "string", "example": "Ayaya" }, "email": { "type": "string", "example": "emeka@gmail.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "integer", "example": 1 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/approved-facilitators": { "get": { "tags": [ "Centre" ], "summary": "Get all approved facilitators for the authenticated centre", "description": "Returns a list of all facilitators whose status is 'approved' under the currently authenticated Centre Admin", "operationId": "04dcaa3eb5239c6ef74f366e0e5eefa3", "responses": { "200": { "description": "Successful response with approved facilitators", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_facilitators": { "type": "integer", "example": 3 }, "facilitators": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 5 }, "facilitator_id": { "type": "string", "example": "2026159781" }, "surname": { "type": "string", "example": "Osagie" }, "first_name": { "type": "string", "example": "Tom" }, "middle_name": { "type": "string", "example": "Aslem" }, "email": { "type": "string", "example": "tom@gmail.com" }, "phone": { "type": "string", "example": "+2348012845678" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/create-zonal-admin": { "post": { "tags": [ "Api" ], "summary": "Create Zonal Admin", "description": "Super Admin creates a Zonal Admin for a geopolitical zone. Each zone can only have one Zonal Admin.", "operationId": "c9965a6bc12299a02352caa25be0ba66", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "surname", "first_name", "email", "phone", "name_of_zone", "state_of_zone", "lga_of_zone" ], "properties": { "surname": { "type": "string", "example": "Adeyemi" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Olu" }, "email": { "type": "string", "format": "email", "example": "zonaladmin@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "name_of_zone": { "type": "string", "enum": [ "North Central", "North West", "North East", "South South", "South East", "South West" ], "example": "South East" }, "state_of_zone": { "type": "string", "example": "Anambra" }, "lga_of_zone": { "type": "string", "example": "Awka South" } }, "type": "object" } } } }, "responses": { "200": { "description": "Zonal Admin account created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Zonal Admin account created successfully" }, "user": { "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "John Adeyemi" }, "email": { "type": "string", "example": "zonaladmin@example.com" }, "name_of_zone": { "type": "string", "example": "South East" }, "state_of_zone": { "type": "string", "example": "Anambra" }, "lga_of_zone": { "type": "string", "example": "Awka South" }, "roles": { "type": "array", "items": { "type": "string", "example": "Zonal Admin" } } }, "type": "object" } }, "type": "object" } } } }, "409": { "description": "Zone already has a Zonal Admin", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "A Zonal Admin already exists for this zone." } }, "type": "object" } } } }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/complete-zonal-admin-profile": { "post": { "tags": [ "Zonal Admin" ], "summary": "Complete Zonal Admin Profile", "description": "Allows an authenticated Zonal Admin to update their profile information and upload passport and signature images.", "operationId": "747b348ec6bac42ef93bdbbb01541fe0", "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "properties": { "gender": { "type": "string", "example": "Male" }, "marital_status": { "type": "string", "example": "Single" }, "staff_id": { "type": "string", "example": "ZA1234" }, "dob": { "type": "string", "format": "date", "example": "1990-05-15" }, "year_of_employment": { "type": "integer", "example": 2015 }, "passport": { "description": "Passport image (jpg, jpeg, png, max 2MB)", "type": "string", "format": "binary" }, "signature": { "description": "Signature image (jpg, jpeg, png, max 2MB)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profile updated successfully." }, "user": { "properties": { "id": { "type": "integer", "example": 10 }, "surname": { "type": "string", "example": "Okafor" }, "first_name": { "type": "string", "example": "Emeka" }, "middle_name": { "type": "string", "example": "James" }, "email": { "type": "string", "example": "zonaladmin@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "status": { "type": "boolean", "example": true } }, "type": "object" }, "profile": { "properties": { "user_id": { "type": "integer", "example": 10 }, "gender": { "type": "string", "example": "Male" }, "marital_status": { "type": "string", "example": "Single" }, "staff_id": { "type": "string", "example": "ZA1234" }, "dob": { "type": "string", "example": "1990-05-15" }, "year_of_employment": { "type": "integer", "example": 2015 }, "passport": { "type": "string", "example": "passports/passport_uuid.jpg" }, "signature": { "type": "string", "example": "signatures/signature_uuid.png" } }, "type": "object" }, "passport_url": { "type": "string", "example": "https://api.nmec.top/storage/passports/passport_uuid.jpg" }, "signature_url": { "type": "string", "example": "https://api.nmec.top/storage/signatures/signature_uuid.png" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Bearer token missing or invalid" }, "422": { "description": "Validation errors", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed." }, "errors": { "type": "object", "example": { "passport": [ "The passport must be an image." ], "year_of_employment": [ "The year_of_employment must be a 4 digit year." ] } } }, "type": "object" } } } }, "500": { "description": "Unexpected server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admin/profile": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get Zonal Admin Profile", "description": "Retrieve the authenticated Zonal Admin's account information and profile details.", "operationId": "2e551c22d43894fdac30adc4a752a007", "responses": { "200": { "description": "Zonal Admin profile retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Zonal Admin profile retrieved successfully" }, "user": { "properties": { "id": { "type": "integer", "example": 7 }, "surname": { "type": "string", "example": "Okafor" }, "first_name": { "type": "string", "example": "Emeka" }, "middle_name": { "type": "string", "example": "James" }, "email": { "type": "string", "example": "zonaladmin@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "name_of_zone": { "type": "string", "example": "South East" }, "state_of_zone": { "type": "string", "example": "Anambra" }, "lga_of_zone": { "type": "string", "example": "Awka South" }, "status": { "type": "boolean", "example": true }, "roles": { "type": "array", "items": { "type": "string", "example": "Zonal Admin" } } }, "type": "object" }, "profile": { "properties": { "gender": { "type": "string", "example": "Male" }, "marital_status": { "type": "string", "example": "Single" }, "staff_id": { "type": "string", "example": "ZA1234" }, "dob": { "type": "string", "format": "date", "example": "1990-05-15" }, "year_of_employment": { "type": "integer", "example": 2015 }, "passport": { "type": "string", "example": "passports/passport_uuid.jpg" }, "signature": { "type": "string", "example": "signatures/signature_uuid.png" }, "passport_url": { "type": "string", "example": "https://api.nmec.top/storage/passports/passport_uuid.jpg" }, "signature_url": { "type": "string", "example": "https://api.nmec.top/storage/signatures/signature_uuid.png" } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Bearer token missing or invalid" }, "404": { "description": "Profile not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admin/edit-profile": { "post": { "tags": [ "Zonal Admin" ], "summary": "Update logged-in Zonal Admin profile", "description": "Allows an authenticated Zonal Admin to update their own profile, including personal information, passport, and signature images.", "operationId": "editZonalAdminProfile", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "surname": { "type": "string", "maxLength": 50, "example": "Doe" }, "first_name": { "type": "string", "maxLength": 50, "example": "Jane" }, "middle_name": { "type": "string", "maxLength": 50, "example": "Mary" }, "gender": { "type": "string", "enum": [ "male", "female", "Other" ], "example": "female" }, "marital_status": { "type": "string", "example": "Single" }, "staff_id": { "type": "string", "maxLength": 20, "example": "ZA-00123" }, "dob": { "type": "string", "format": "date", "example": "1990-08-15" }, "year_of_employment": { "type": "integer", "example": 2018 }, "passport": { "description": "Passport image file (jpg, jpeg, png)", "type": "string", "format": "binary" }, "signature": { "description": "Signature image file (jpg, jpeg, png)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Profile updated successfully." }, "user": { "properties": { "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "Jane" }, "middle_name": { "type": "string", "example": "Mary" } }, "type": "object" }, "profile": { "properties": { "gender": { "type": "string", "example": "female" }, "marital_status": { "type": "string", "example": "Single" }, "staff_id": { "type": "string", "example": "ZA-00123" }, "dob": { "type": "string", "format": "date", "example": "1990-08-15" }, "year_of_employment": { "type": "integer", "example": 2018 }, "passport": { "type": "string", "example": "passports/passport_uuid.jpg" }, "signature": { "type": "string", "example": "signatures/signature_uuid.png" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "No valid fields provided or validation failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "No valid fields provided for update." } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Zonal Admin profile not found." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre-details": { "post": { "tags": [ "Centre" ], "summary": "Create or update centre details", "description": "Allows an authenticated centre admin to submit or update centre details including operational days and time.", "operationId": "storeCentreDetails", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "town", "centre_address", "year_of_establishment", "time_of_operation", "days_of_operation", "neighborhood", "is_owned" ], "properties": { "town": { "type": "string", "maxLength": 255, "example": "Umuokpu" }, "centre_address": { "type": "string", "example": "No 23, Main Street, Umuokpu" }, "year_of_establishment": { "type": "integer", "example": 2005 }, "time_of_operation": { "type": "array", "items": { "type": "string" }, "example": [ "Morning", "Evening" ] }, "days_of_operation": { "type": "array", "items": { "type": "string" }, "example": [ "Monday", "Tuesday", "Wednesday" ] }, "neighborhood": { "type": "string", "maxLength": 255, "example": "Market Area" }, "is_owned": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Centre details submitted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Centre details submitted successfully." }, "centre_details": { "properties": { "id": { "type": "integer", "example": 1 }, "centre_id": { "type": "integer", "example": 5 }, "town": { "type": "string", "example": "Umuokpu" }, "centre_address": { "type": "string", "example": "No 23, Main Street, Umuokpu" }, "year_of_establishment": { "type": "integer", "example": 2005 }, "time_of_operation": { "type": "array", "items": { "type": "string" }, "example": [ "Morning", "Evening" ] }, "days_of_operation": { "type": "array", "items": { "type": "string" }, "example": [ "Monday", "Tuesday", "Wednesday" ] }, "neighborhood": { "type": "string", "example": "Market Area" }, "is_owned": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-07T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-03-07T12:00:00Z" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation error" }, "errors": { "type": "object", "example": { "town": [ "The town field is required." ], "time_of_operation": [ "The time of operation field is required." ] } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state-admin/learners": { "get": { "tags": [ "State Agency Admin" ], "summary": "View learners in the State Admin's state", "description": "Retrieve a list of learners whose centres are located in the same state as the authenticated State Agency Admin.", "operationId": "viewLearners", "responses": { "200": { "description": "Learners retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "state": { "type": "string", "example": "Lagos" }, "learners": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "learner_id": { "type": "string", "example": "NMEC/LAGOS/00001/0001" }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Michael" }, "email": { "type": "string", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "boolean", "example": true }, "centre": { "properties": { "id": { "type": "integer", "example": 1 }, "registered_name": { "type": "string", "example": "NMEC Centre 1" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" } }, "type": "object" }, "profile": { "properties": { "marital_status": { "type": "string", "example": "Single" }, "state_of_origin": { "type": "string", "example": "Lagos" }, "lga_of_origin": { "type": "string", "example": "Ikeja" }, "home_town": { "type": "string", "example": "Ojodu" }, "residential_address": { "type": "string", "example": "123 Street, Lagos" }, "date_of_birth": { "type": "string", "format": "date", "example": "1990-01-01" }, "nin": { "type": "string", "example": "12345678901" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/facilitator/learners": { "get": { "tags": [ "Facilitator" ], "summary": "Get all learners assigned to the authenticated facilitator", "description": "Retrieve all learners assigned to the currently authenticated facilitator based on programme and centre.", "operationId": "getAssignedLearners", "responses": { "200": { "description": "List of assigned learners retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_assigned_learners": { "type": "integer", "example": 5 }, "learners": { "type": "array", "items": { "properties": { "learner_id": { "type": "string", "example": "LMEC/ANAMB/00001/L0001" }, "name": { "type": "string", "example": "Jane Doe" }, "email": { "type": "string", "format": "email", "example": "jane.doe@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "enum": [ "Male", "Female", "Other" ], "example": "Female" }, "profile_completed": { "type": "boolean", "example": true }, "centre": { "properties": { "id": { "type": "integer", "example": 15 }, "registered_name": { "type": "string", "example": "Xyz Learning Centre" }, "email": { "type": "string", "example": "xyz@gmail.com" }, "phone": { "type": "string", "example": "+2348014345678" }, "centre_id": { "type": "string", "example": "NMEC/ANAMB/00001" } }, "type": "object", "nullable": true }, "profile": { "properties": { "photo": { "type": "string", "example": "learner_photos/1712345678_photo.jpg", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "example": "2005-06-15", "nullable": true }, "state_of_origin": { "type": "string", "example": "Anambra", "nullable": true }, "lga_of_origin": { "type": "string", "example": "Awka South", "nullable": true }, "home_town": { "type": "string", "example": "Awka", "nullable": true }, "state_of_residence": { "type": "string", "example": "Lagos", "nullable": true }, "lga_of_residence": { "type": "string", "example": "Ikeja", "nullable": true }, "nin": { "type": "string", "example": "12345678901", "nullable": true }, "highest_qualification_dates": { "type": "array", "items": { "type": "string", "format": "date" }, "example": [ "2021-06-01", "2023-05-20" ], "nullable": true } }, "type": "object", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - facilitator not authenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthorized. Facilitator access only." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/facilitator/change-password": { "post": { "tags": [ "Facilitator" ], "summary": "Change Facilitator Password", "description": "Allows an authenticated facilitator to change their password by providing the current password and new password.", "operationId": "changePasswordFacilitator", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "current_password", "new_password", "new_password_confirmation" ], "properties": { "current_password": { "description": "Current password of the facilitator", "type": "string", "format": "password", "example": "oldpassword123" }, "new_password": { "description": "New password (minimum 6 characters)", "type": "string", "format": "password", "example": "newpassword123" }, "new_password_confirmation": { "description": "Confirmation of the new password", "type": "string", "format": "password", "example": "newpassword123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password changed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Password changed successfully." } }, "type": "object" } } } }, "401": { "description": "Unauthorized. Facilitator access only.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized. Facilitator access only." } }, "type": "object" } } } }, "422": { "description": "Validation failed or current password incorrect", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Current password is incorrect." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/facilitators/gender-count": { "get": { "tags": [ "Centre" ], "summary": "Get facilitator counts by gender for the authenticated centre", "description": "Returns the total number of male, female, and overall facilitators for the centre of the currently authenticated centre admin.", "operationId": "a9775a68529a71210f927c7c105c8b9b", "responses": { "200": { "description": "Successfully retrieved facilitator counts", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "male_facilitators": { "type": "integer", "example": 5 }, "female_facilitators": { "type": "integer", "example": 3 }, "total_facilitators": { "type": "integer", "example": 8 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/all/centres/national": { "get": { "tags": [ "National Officers" ], "summary": "Get paginated centres (National Officer only)", "description": "Retrieve a paginated list of centres along with the total number of centres. Accessible only to authenticated users with the 'National Officer' role.", "operationId": "51786352a9846d13bd8a4b18587a6950", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of centres per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Paginated centres retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_centres": { "type": "integer", "example": 6 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 7 }, "registered_name": { "type": "string", "example": "ABC Learning Centre" }, "email": { "type": "string", "example": "centre@gmail.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "centre_id": { "type": "string", "example": "abc2025001" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" }, "ward": { "type": "string", "example": "Ward 1" }, "picture": { "type": "string", "example": "centre_pictures/abc.jpg" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden: Not a National Officer", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: You do not have permission to view this resource" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admins/national": { "get": { "tags": [ "National Officers" ], "summary": "Get all Zonal Admins (National Officer only)", "description": "Retrieve a paginated list of Zonal Admins along with the total number of zones. Accessible only to National Officers.", "operationId": "8192449cafab697764a9b605fd3103a2", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of Zonal Admins per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Paginated Zonal Admins retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_zones": { "type": "integer", "example": 6 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 37 }, "name": { "type": "string", "example": "John Adeyemi" }, "email": { "type": "string", "example": "zonaladmin@gmail.com" }, "phone": { "type": "string", "example": "+2348012945678" }, "zone": { "type": "string", "example": "South East" }, "state_of_zone": { "type": "string", "example": "Anambra" }, "lga_of_zone": { "type": "string", "example": "Awka South" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden: Not a National Officer", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: You do not have permission to view this resource" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state-agency-admins/national": { "get": { "tags": [ "National Officers" ], "summary": "Get all State Agency Admins (National Officer only)", "description": "Retrieve a paginated list of State Agency Admins along with the total count. Accessible only to authenticated users with the 'National Officer' role.", "operationId": "bbf7d01f668ebe0a912c3d86dda3060f", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of State Agency Admins per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Paginated State Agency Admins retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_state_agency_admins": { "type": "integer", "example": 25 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 3 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 21 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "user@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "state": { "type": "string", "example": "Delta" }, "gender": { "type": "string", "example": "male" }, "year_of_employment": { "type": "integer", "example": 2025 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden: Not a National Officer", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: You do not have permission to view this resource" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/facilitators/national": { "get": { "tags": [ "National Officers" ], "summary": "Get all Facilitators (National Officer only)", "description": "Retrieve a paginated list of all Facilitators along with the total count. Accessible only to authenticated users with the 'National Officer' role.", "operationId": "ae2a200fa5f263dfffe71bd122add6c1", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of Facilitators per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Paginated Facilitators retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_facilitators": { "type": "integer", "example": 150 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 15 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 7 }, "facilitator_id": { "type": "string", "example": "FAC2025001" }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Michael" }, "email": { "type": "string", "example": "facilitator@gmail.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "male" }, "status": { "type": "string", "example": "approved" }, "centre_of_choice": { "type": "string", "example": "ABC Learning Centre" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden: Not a National Officer", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: You do not have permission to view this resource" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/learners/national": { "get": { "tags": [ "National Officers" ], "summary": "Get all Learners (National Officer only)", "description": "Retrieve a paginated list of all Learners along with the total count. Accessible only to authenticated users with the 'National Officer' role.", "operationId": "d1c5c2206975fae9cf35ca90a7aa91a9", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of Learners per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Paginated Learners retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_learners": { "type": "integer", "example": 1000 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 100 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 7 }, "learner_id": { "type": "string", "example": "LRN2025001" }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Michael" }, "email": { "type": "string", "example": "learner@gmail.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "male" }, "status": { "type": "string", "example": "active" }, "centre_of_choice": { "type": "string", "example": "ABC Learning Centre" }, "program_id": { "type": "integer", "example": 5 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden: Not a National Officer", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: You do not have permission to view this resource" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/programmes/national": { "get": { "tags": [ "National Officers" ], "summary": "Get all Programmes with Subjects (National Officer only)", "description": "Retrieve a paginated list of all Programmes along with their Subjects. Accessible only to authenticated users with the 'National Officer' role.", "operationId": "99ed715c2ef58761283e605c00e724b9", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of programmes per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Paginated Programmes with Subjects retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_programmes": { "type": "integer", "example": 6 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Basic Literacy" }, "description": { "type": "string", "example": "Your basic literacy skills start here" }, "subjects": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "English Literacy" }, "description": { "type": "string", "example": "Learn basic English literacy skills" }, "curriculum": { "type": "string", "example": "Literacy Curriculum 101" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden: Not a National Officer", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: You do not have permission to view this resource" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/national/zonal/state-agency-admins": { "get": { "tags": [ "National Officers" ], "summary": "Get all State Agency Admins in a specific zone", "description": "Retrieve all State Agency Admins created under a specific Zonal Admin. Only accessible by National Officers.", "operationId": "21bbba45b4d7cdfa474cf014b1db875c", "parameters": [ { "name": "zonal_admin_id", "in": "query", "description": "The ID of the Zonal Admin to filter State Agency Admins", "required": true, "schema": { "type": "integer", "example": 37 } }, { "name": "per_page", "in": "query", "description": "Number of results per page", "required": false, "schema": { "type": "integer", "default": 10, "example": 10 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_state_agency_admins": { "type": "integer", "example": 25 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 3 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 21 }, "user_id": { "type": "integer", "example": 21 }, "zonal_admin_id": { "type": "integer", "example": 37 }, "gender": { "type": "string", "example": "male" }, "marital_status": { "type": "string", "example": "Single" }, "passport": { "type": "string", "example": "passports/XsImvRkQvDyLK9L3UJOcS5ZoavJ1kFpErJJHkBAj" }, "signature": { "type": "string", "example": "signatures/7gsYvF4qAV4C7druA3jaIH4OXGwt82ARqWNDgAp" }, "nin": { "type": "string", "example": "4567973999" }, "staff_id": { "type": "string", "example": "NO-007" }, "dob": { "type": "string", "format": "date", "example": "2025-07-19" }, "year_of_employment": { "type": "integer", "example": 2025 }, "state": { "type": "string", "example": "Delta" }, "user": { "properties": { "id": { "type": "integer", "example": 21 }, "surname": { "type": "string", "example": "Okorowata" }, "first_name": { "type": "string", "example": "Chioma" }, "middle_name": { "type": "string", "example": "Augustine" }, "email": { "type": "string", "example": "user@example.com" }, "phone": { "type": "string", "example": "08012345678" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: You do not have permission to view this resource" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/national/learners-by-centre": { "get": { "tags": [ "National Officers" ], "summary": "Get all learners in a specific centre", "description": "Retrieve all learners registered under a specific Centre. Only accessible by National Officers.", "operationId": "d54b0ce29d8be981e0324f2bab2ecb6b", "parameters": [ { "name": "centre_id", "in": "query", "description": "The ID of the Centre", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of results per page", "required": false, "schema": { "type": "integer", "default": 10, "example": 10 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_learners": { "type": "integer", "example": 120 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 12 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 101 }, "surname": { "type": "string", "example": "Okafor" }, "first_name": { "type": "string", "example": "Ada" }, "middle_name": { "type": "string", "example": "Ngozi" }, "email": { "type": "string", "example": "ada.okafor@gmail.com" }, "phone": { "type": "string", "example": "08012345809" }, "date_of_birth": { "type": "string", "format": "date", "example": "2005-07-02" }, "gender": { "type": "string", "example": "female" }, "snap_picture": { "type": "string", "example": "path/to/photo.jpg" }, "centre": { "properties": { "id": { "type": "integer", "example": 1 }, "registered_name": { "type": "string", "example": "Community Learning Centre" } }, "type": "object" }, "programme": { "properties": { "id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "Vocational Education" } }, "type": "object" }, "facilitators": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 21 }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: You do not have permission to view this resource" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/national/facilitators-by-centre": { "get": { "tags": [ "National Officers" ], "summary": "Get all facilitators in a specific centre", "description": "Retrieve all facilitators registered under a specific Centre. Only accessible by National Officers.", "operationId": "21e59928a0567ef2f10a75c128080aa3", "parameters": [ { "name": "centre_id", "in": "query", "description": "The ID of the Centre", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of results per page", "required": false, "schema": { "type": "integer", "default": 10, "example": 10 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_facilitators": { "type": "integer", "example": 50 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 5 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 21 }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Michael" }, "email": { "type": "string", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "gender": { "type": "string", "example": "Male" }, "date_of_birth": { "type": "string", "format": "date", "example": "1990-05-15" }, "snap_picture": { "type": "string", "example": "path/to/photo.jpg" }, "centre": { "properties": { "id": { "type": "integer", "example": 1 }, "registered_name": { "type": "string", "example": "Community Learning Centre" } }, "type": "object" }, "programmes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "Vocational Education" } }, "type": "object" } }, "learners": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 101 }, "surname": { "type": "string", "example": "Okafor" }, "first_name": { "type": "string", "example": "Ada" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: You do not have permission to view this resource" } }, "type": "object" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "The centre_id field is required." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/national/learner-gender-statistics": { "get": { "tags": [ "National Officers" ], "summary": "Get total number of male and female learners", "description": "Retrieve the total number of male and female learners in the system. Accessible only by users with the National Officer role.", "operationId": "fe5c97c4551d618a3d1884b24fa56cda", "responses": { "200": { "description": "Successful response with total male and female learners", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "male": { "type": "integer", "example": 1200 }, "female": { "type": "integer", "example": 1350 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: You do not have permission to view this resource" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/national/facilitator-gender-statistics": { "get": { "tags": [ "National Officers" ], "summary": "Get total number of male and female facilitators", "description": "Retrieve the total number of male and female facilitators in the system. Accessible only by users with the National Officer role.", "operationId": "25a1f48a46e57c552239759ceb050002", "responses": { "200": { "description": "Successful response with total male and female facilitators", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "male": { "type": "integer", "example": 150 }, "female": { "type": "integer", "example": 170 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: You do not have permission to view this resource" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal/state-admins/count": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get total State Agency Admins in Zonal Admin's zone", "description": "Returns the total number of State Agency Admins under the logged-in Zonal Admin", "operationId": "b7f8fbdc4c73693bed0afde26dbc0d6c", "responses": { "200": { "description": "Total State Agency Admins returned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_state_agency_admins": { "type": "integer", "example": 15 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: Only Zonal Admins can view this data" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal/state-admins/gender-stats": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get gender stats of State Agency Admins in Zonal Admin's zone", "description": "Returns the total number of male and female State Agency Admins under the logged-in Zonal Admin", "operationId": "8fb89367dcedd384b552129affea9907", "responses": { "200": { "description": "Gender stats returned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "male": { "type": "integer", "example": 10 }, "female": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: Only Zonal Admins can view this data" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state-admin/approved-centres/count": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get Total Approved Centres", "description": "Allows a State Agency Admin to retrieve the total number of approved centres in their state.", "operationId": "getApprovedCentresCount", "responses": { "200": { "description": "Total approved centres retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "approved_centres": { "type": "integer", "example": 15 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: Only State Agency Admins can access this" } }, "type": "object" } } } }, "404": { "description": "State not found for admin", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "State information not found for this admin" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admin/state-agency-admins": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get all State Agency Admins under the authenticated Zonal Admin", "description": "Returns a list of state agency admins assigned to the authenticated Zonal Admin. Requires Zonal Admin role.", "operationId": "getStateAgencyAdmins", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "zonal_admin_id": { "type": "integer", "example": 5 }, "user_id": { "type": "integer", "example": 10 }, "user": { "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "role": { "type": "string", "example": "State Agency Admin" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden - Only Zonal Admins can access this", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: Only Zonal Admins can access this" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admin/state-agency-admins/{id}": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get a specific State Agency Admin by ID under the authenticated Zonal Admin", "description": "Returns the state agency admin details for a given ID if they belong to the logged-in Zonal Admin.", "operationId": "getStateAgencyAdminById", "parameters": [ { "name": "id", "in": "path", "description": "ID of the State Agency Admin", "required": true, "schema": { "type": "integer", "example": 3 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "id": { "type": "integer", "example": 3 }, "zonal_admin_id": { "type": "integer", "example": 37 }, "user_id": { "type": "integer", "example": 40 }, "user": { "properties": { "name": { "type": "string", "example": "Jane Doe" }, "email": { "type": "string", "example": "jane@example.com" }, "role": { "type": "string", "example": "State Agency Admin" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden - Only Zonal Admins can access this", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: Only Zonal Admins can access this" } }, "type": "object" } } } }, "404": { "description": "State Agency Admin not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "State Agency Admin not found or does not belong to you" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal/update/state-agency-admins/{id}": { "post": { "tags": [ "Zonal Admin" ], "summary": "Update a specific State Agency Admin under the authenticated Zonal Admin", "description": "Allows the Zonal Admin to update the details of a specific State Agency Admin assigned to them, including personal info, files, and employment data.", "operationId": "updateStateAgencyAdmin", "parameters": [ { "name": "id", "in": "path", "description": "ID of the State Agency Admin", "required": true, "schema": { "type": "integer", "example": 3 } } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "properties": { "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Michael" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "enum": [ "Male", "Female", "male", "female" ], "example": "Male" }, "marital_status": { "type": "string", "example": "Single" }, "nin": { "type": "string", "example": "12345678901" }, "staff_id": { "type": "string", "example": "SA-001" }, "dob": { "type": "string", "format": "date", "example": "1990-05-20" }, "year_of_employment": { "type": "integer", "example": 2025 }, "state": { "type": "string", "example": "Delta" }, "passport": { "description": "Passport image (jpg, jpeg, png)", "type": "string", "format": "binary" }, "signature": { "description": "Signature image (jpg, jpeg, png)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successfully updated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "State Agency Admin updated successfully" }, "data": { "properties": { "user": { "properties": { "id": { "type": "integer", "example": 3 }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Michael" }, "phone": { "type": "string", "example": "+2348012345678" } }, "type": "object" }, "profile": { "properties": { "id": { "type": "integer", "example": 3 }, "gender": { "type": "string", "example": "male" }, "marital_status": { "type": "string", "example": "Single" }, "passport_url": { "type": "string", "example": "http://localhost/passports/1689171234_passport.jpg" }, "signature_url": { "type": "string", "example": "http://localhost/signatures/1689171234_signature.jpg" }, "nin": { "type": "string", "example": "12345678901" }, "staff_id": { "type": "string", "example": "SA-001" }, "dob": { "type": "string", "format": "date", "example": "1990-05-20" }, "year_of_employment": { "type": "integer", "example": 2025 }, "state": { "type": "string", "example": "Delta" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: Only Zonal Admin can update" } }, "type": "object" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "State Agency Admin not found or not under you" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Validation error" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Update failed" }, "error": { "type": "string", "example": "Exception message" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal/delete/state-agency-admins/{id}": { "delete": { "tags": [ "Zonal Admin" ], "summary": "Delete a specific State Agency Admin under the authenticated Zonal Admin", "description": "Allows the Zonal Admin to delete a State Agency Admin assigned to them.", "operationId": "deleteStateAgencyAdmin", "parameters": [ { "name": "id", "in": "path", "description": "ID of the State Agency Admin", "required": true, "schema": { "type": "integer", "example": 3 } } ], "responses": { "200": { "description": "Successfully deleted", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "State Agency Admin deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: Only Zonal Admins can access this" } }, "type": "object" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "State Agency Admin not found or does not belong to you" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal/state-agency-admins/reset-password": { "post": { "tags": [ "Zonal Admin" ], "summary": "Reset password for a State Agency Admin", "description": "Allows the authenticated Zonal Admin to reset the password of a State Agency Admin under their supervision.", "operationId": "resetStateAgencyAdminPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "state_admin_id": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "responses": { "200": { "description": "Password reset successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "State Agency Admin password has been reset successfully." }, "default_password": { "type": "string", "example": "PassWord123!" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: Only Zonal Admins can reset passwords" } }, "type": "object" } } } }, "404": { "description": "State Agency Admin not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "State Agency Admin not found or does not belong to you" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admin/centres": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get Centres Under Zonal Admin", "description": "Returns all centres in states managed by the authenticated Zonal Admin.", "operationId": "getCentresUnderZone", "responses": { "200": { "description": "Centres retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_centres": { "type": "integer", "example": 5 }, "centres": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 7 }, "registered_name": { "type": "string", "example": "ABC Learning Centre" }, "state": { "type": "string", "example": "Delta" }, "lga": { "type": "string", "example": "Ughelli" }, "phone": { "type": "string", "example": "+2348012345678" }, "status": { "type": "string", "example": "pending" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admin/centres/{id}": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get centre details by ID", "description": "Allows a Zonal Admin to retrieve details of a centre under their zone. Includes profile, programmes, learners, facilitators, and certificate.", "operationId": "getCentreZoneById", "parameters": [ { "name": "id", "in": "path", "description": "Centre ID", "required": true, "schema": { "type": "integer", "example": 7 } } ], "responses": { "200": { "description": "Centre retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "centre": { "properties": { "id": { "type": "integer", "example": 7 }, "registered_name": { "type": "string", "example": "ABC Learning Centre" }, "community_type": { "type": "string", "example": "Private" }, "ownership": { "type": "string", "example": "Private" }, "email": { "type": "string", "example": "centre@gmail.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "centre_id": { "type": "string", "example": "abc2025001" }, "state": { "type": "string", "example": "Delta" }, "lga": { "type": "string", "example": "Ughelli" }, "ward": { "type": "string", "example": "Ward 3" }, "status": { "type": "string", "example": "pending" }, "profile": { "description": "Centre profile details", "type": "object" }, "programmes": { "type": "array", "items": { "type": "object" } }, "learners": { "type": "array", "items": { "type": "object" } }, "facilitators": { "type": "array", "items": { "type": "object" } }, "certificate": { "description": "Centre certificate details", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: Only Zonal Admins can access this resource" } }, "type": "object" } } } }, "404": { "description": "Centre not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Centre not found or not under your zone" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal/get/facilitators": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get list of facilitators under the zone", "description": "Returns all facilitators whose centres belong to states managed by the authenticated Zonal Admin.", "operationId": "getFacilitatorsUnderZone", "responses": { "200": { "description": "Facilitators retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_facilitators": { "type": "integer", "example": 5 }, "facilitators": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 3 }, "facilitator_id": { "type": "string", "example": "FAC-2025001" }, "surname": { "type": "string", "example": "Okoro" }, "first_name": { "type": "string", "example": "James" }, "email": { "type": "string", "example": "james@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "centre_of_choice": { "type": "integer", "example": 7 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal/facilitators/{id}": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get facilitator details by ID", "description": "Allows a Zonal Admin to retrieve facilitator details only if the facilitator belongs to a centre within the Zonal Admin's zone.", "operationId": "getFacilitatorZoneById", "parameters": [ { "name": "id", "in": "path", "description": "Facilitator ID", "required": true, "schema": { "type": "integer", "example": 12 } } ], "responses": { "200": { "description": "Facilitator retrieved successfully", "content": { "application/json": { "schema": { "properties": { "facilitator": { "properties": { "id": { "type": "integer", "example": 12 }, "surname": { "type": "string", "example": "Ade" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "status": { "type": "string", "example": "active" }, "gender": { "type": "string", "example": "male" }, "date_of_birth": { "type": "string", "example": "1990-05-10" }, "centre": { "properties": { "id": { "type": "integer", "example": 4 }, "name": { "type": "string", "example": "Ikeja Learning Centre" }, "state": { "type": "string", "example": "Lagos" } }, "type": "object" }, "profile": { "properties": { "qualification": { "type": "string", "example": "B.Sc Education" }, "experience_years": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Facilitator not found or not in the zonal admin's zone", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facilitator not found in your zone" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admin/learners": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get list of learners under the zone", "description": "Allows a Zonal Admin to retrieve a paginated list of learners whose centres are located in states under the Zonal Admin's zone.", "operationId": "getLearnersUnderZone", "parameters": [ { "name": "page", "in": "query", "description": "Pagination page number", "required": false, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Learners retrieved successfully", "content": { "application/json": { "schema": { "properties": { "learners": { "properties": { "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 150 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 5 }, "learner_id": { "type": "string", "example": "LRN-1023" }, "surname": { "type": "string", "example": "Ade" }, "first_name": { "type": "string", "example": "Mary" }, "middle_name": { "type": "string", "example": "Grace" }, "phone": { "type": "string", "example": "08012345678" }, "email": { "type": "string", "example": "mary@example.com" }, "gender": { "type": "string", "example": "female" }, "centre": { "properties": { "id": { "type": "integer", "example": 4 }, "registered_name": { "type": "string", "example": "Ikeja Learning Centre" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" } }, "type": "object" }, "programme": { "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Digital Literacy" } }, "type": "object" }, "profile": { "properties": { "address": { "type": "string", "example": "12 Allen Avenue" }, "education_level": { "type": "string", "example": "Secondary School" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Zonal admin profile not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Zonal admin profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admin/learners/{id}": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get learner details by ID", "description": "Allows a Zonal Admin to retrieve the details of a learner only if the learner belongs to a centre within the Zonal Admin's zone.", "operationId": "getLearnerById", "parameters": [ { "name": "id", "in": "path", "description": "Learner ID", "required": true, "schema": { "type": "integer", "example": 7 } } ], "responses": { "200": { "description": "Learner retrieved successfully", "content": { "application/json": { "schema": { "properties": { "learner": { "properties": { "id": { "type": "integer", "example": 7 }, "learner_id": { "type": "string", "example": "LRN-1023" }, "surname": { "type": "string", "example": "Ade" }, "first_name": { "type": "string", "example": "Mary" }, "middle_name": { "type": "string", "example": "Grace" }, "phone": { "type": "string", "example": "08012345678" }, "email": { "type": "string", "example": "mary@example.com" }, "gender": { "type": "string", "example": "female" }, "date_of_birth": { "type": "string", "example": "1998-05-10" }, "centre": { "properties": { "id": { "type": "integer", "example": 4 }, "registered_name": { "type": "string", "example": "Ikeja Learning Centre" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" } }, "type": "object" }, "programme": { "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Digital Literacy" } }, "type": "object" }, "profile": { "properties": { "address": { "type": "string", "example": "12 Allen Avenue" }, "education_level": { "type": "string", "example": "Secondary School" } }, "type": "object" }, "facilitators": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 3 }, "surname": { "type": "string", "example": "John" }, "first_name": { "type": "string", "example": "Peter" }, "email": { "type": "string", "example": "john@example.com" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Learner not found or not in the zonal admin's zone", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Learner not found in your zone" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admin/state-agencies/count": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get total state agencies in zonal admin zone", "description": "Returns the total number of State Agency Admins under the authenticated Zonal Admin.", "operationId": "getTotalStateAgencies", "responses": { "200": { "description": "Total state agencies retrieved successfully", "content": { "application/json": { "schema": { "properties": { "total_state_agencies": { "type": "integer", "example": 2 } }, "type": "object" } } } }, "404": { "description": "Zonal admin profile not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Zonal admin profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admin/statistics/summary": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get zonal admin dashboard summary", "description": "Returns total number of state agencies, centres, facilitators and learners under the authenticated zonal admin.", "operationId": "getZoneSummary", "responses": { "200": { "description": "Dashboard summary retrieved successfully", "content": { "application/json": { "schema": { "properties": { "summary": { "properties": { "total_state_agencies": { "type": "integer", "example": 2 }, "total_centres": { "type": "integer", "example": 14 }, "total_facilitators": { "type": "integer", "example": 63 }, "total_learners": { "type": "integer", "example": 520 } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Zonal admin profile not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Zonal admin profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admin/learner-enrollment-per-state": { "get": { "tags": [ "Zonal Admin" ], "summary": "Learner enrollment per state", "description": "Returns the number of learners enrolled in each state within the zonal admin's zone.", "operationId": "getLearnerEnrollmentPerState", "responses": { "200": { "description": "Learner enrollment per state retrieved successfully", "content": { "application/json": { "schema": { "properties": { "learner_enrollment_per_state": { "type": "array", "items": { "properties": { "state": { "type": "string", "example": "Delta" }, "total_learners": { "type": "integer", "example": 120 } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Zonal admin profile not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Zonal admin profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admin/centre-certification-status": { "get": { "tags": [ "Zonal Admin" ], "summary": "Centre certification status summary", "description": "Returns the number of centres with Approved, Pending, and Rejected certification statuses within the zonal admin's zone.", "operationId": "getCentreCertificationStatus", "responses": { "200": { "description": "Certification status retrieved successfully", "content": { "application/json": { "schema": { "properties": { "centre_certification_status": { "type": "array", "items": { "properties": { "status": { "type": "string", "example": "approved" }, "total": { "type": "integer", "example": 15 } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Zonal admin profile not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Zonal admin profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/learners/{id}": { "get": { "tags": [ "Centre" ], "summary": "Get learner by ID (Centre Admin)", "description": "Allows a centre admin to retrieve a learner belonging to their centre.", "operationId": "centreGetLearnerById", "parameters": [ { "name": "id", "in": "path", "description": "Learner ID", "required": true, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Learner retrieved successfully", "content": { "application/json": { "schema": { "properties": { "learner": { "properties": { "id": { "type": "integer", "example": 10 }, "learner_id": { "type": "string", "example": "LRN-1001" }, "surname": { "type": "string", "example": "Okoro" }, "first_name": { "type": "string", "example": "Daniel" }, "phone": { "type": "string", "example": "08012345678" }, "email": { "type": "string", "example": "daniel@example.com" }, "gender": { "type": "string", "example": "male" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Learner not found in this centre", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Learner not found in this centre" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Centre" ], "summary": "Delete learner", "description": "Allows a centre admin to delete a learner belonging to their centre.", "operationId": "deleteLearner", "parameters": [ { "name": "id", "in": "path", "description": "Learner ID", "required": true, "schema": { "type": "integer", "example": 12 } } ], "responses": { "200": { "description": "Learner deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Learner deleted successfully" } }, "type": "object" } } } }, "404": { "description": "Learner not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Learner not found in this centre" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/summary-statistics": { "get": { "tags": [ "Centre" ], "summary": "Get Summary Statistics for Centre", "description": "Returns the total number of facilitators and learners for the logged-in centre admin.", "operationId": "3d15fb87332c06762cabf75ee35d3e05", "responses": { "200": { "description": "Summary statistics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "total_facilitators": { "type": "integer", "example": 12 }, "total_learners": { "type": "integer", "example": 54 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal-admin/gender-summary": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get Gender Summary for Learners and Facilitators", "description": "Returns the total number of male and female learners and facilitators under the logged-in zonal admin.", "operationId": "578b6dad3a8268c670282189e28a940f", "responses": { "200": { "description": "Gender summary retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "learners": { "properties": { "male": { "type": "integer", "example": 45 }, "female": { "type": "integer", "example": 60 } }, "type": "object" }, "facilitators": { "properties": { "male": { "type": "integer", "example": 20 }, "female": { "type": "integer", "example": 15 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre-admin/gender-summary": { "get": { "tags": [ "Centre" ], "summary": "Get Gender Summary for Learners and Facilitators in Centre", "description": "Returns the total number of male and female learners and facilitators for the logged-in centre admin", "operationId": "8ebe985f2b549a41edb3243329570865", "responses": { "200": { "description": "Gender summary retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "learners": { "properties": { "male": { "type": "integer", "example": 12 }, "female": { "type": "integer", "example": 15 } }, "type": "object" }, "facilitators": { "properties": { "male": { "type": "integer", "example": 3 }, "female": { "type": "integer", "example": 2 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/national-officer/summary/statistics": { "get": { "tags": [ "National Officers" ], "summary": "Get National Summary Statistics", "description": "Returns total counts of State Agencies, Centres, Facilitators, Learners, and Zones in the system", "operationId": "c9a54b11b6f5aafb2c83a3efa9287669", "responses": { "200": { "description": "Summary retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "total_state_agencies": { "type": "integer", "example": 36 }, "total_centres": { "type": "integer", "example": 120 }, "total_facilitators": { "type": "integer", "example": 450 }, "total_learners": { "type": "integer", "example": 7800 }, "total_zones": { "type": "integer", "example": 6 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/national-officer/summary-gender": { "get": { "tags": [ "National Officers" ], "summary": "Get National Summary with Gender Breakdown", "description": "Returns total counts and gender summary of State Agencies, Centres, Facilitators, Learners, and Zones", "operationId": "7656f8eabd2faf6b9e17a4c0d952fe8d", "responses": { "200": { "description": "Summary retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "total_state_agencies": { "type": "integer", "example": 36 }, "total_centres": { "type": "integer", "example": 120 }, "total_facilitators": { "type": "integer", "example": 450 }, "total_learners": { "type": "integer", "example": 7800 }, "total_zones": { "type": "integer", "example": 6 }, "facilitator_gender_summary": { "properties": { "male": { "type": "integer", "example": 300 }, "female": { "type": "integer", "example": 150 } }, "type": "object" }, "learner_gender_summary": { "properties": { "male": { "type": "integer", "example": 4000 }, "female": { "type": "integer", "example": 3800 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state/learner/{id}": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get learner details by ID", "description": "Fetches a learner's information along with their profile and centre details. Only accessible by authenticated state admins.", "operationId": "getLearnerByIdState", "parameters": [ { "name": "id", "in": "path", "description": "ID of the learner to fetch", "required": true, "schema": { "type": "integer", "example": 3 } } ], "responses": { "200": { "description": "Learner fetched successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "learner": { "properties": { "id": { "type": "integer", "example": 3 }, "learner_id": { "type": "string", "example": "NMEC/ANAMB/00001/0001" }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Michael" }, "phone": { "type": "string", "example": "+2348012345678" }, "email": { "type": "string", "example": "john@example.com" }, "gender": { "type": "string", "example": "Male" }, "date_of_birth": { "type": "string", "format": "date", "example": "2000-05-10" }, "profile_completed": { "type": "boolean", "example": true }, "profile": { "properties": { "marital_status": { "type": "string", "example": "Single" }, "state_of_origin": { "type": "string", "example": "Anambra" }, "lga_of_origin": { "type": "string", "example": "Awka South" }, "home_town": { "type": "string", "example": "Nibo" }, "state_of_residence": { "type": "string", "example": "Lagos" }, "lga_of_residence": { "type": "string", "example": "Ikeja" }, "residential_address": { "type": "string", "example": "12 Allen Avenue Ikeja" }, "last_sch_attended": { "type": "string", "example": "University of Lagos" }, "reason_for_leaving": { "type": "string", "example": "Completed program" }, "any_other_info": { "type": "string", "example": "Interested in advanced training" }, "nin": { "type": "string", "example": "12345678901" }, "highest_qualification_dates": { "type": "string", "example": "BSc 2021" }, "photo": { "type": "string", "example": "learner_photos/photo.jpg" }, "signature": { "type": "string", "example": "learner_signatures/signature.jpg" } }, "type": "object" }, "centre": { "properties": { "centre_id": { "type": "string", "example": "NMEC/ANAMB/00001" }, "registered_name": { "type": "string", "example": "ABC Learning Centre" }, "community_type": { "type": "string", "example": "Urban" }, "ownership": { "type": "string", "example": "Private" }, "state": { "type": "string", "example": "Anambra" }, "lga": { "type": "string", "example": "Awka South" }, "ward": { "type": "string", "example": "Umuokpu Ward" }, "zone": { "type": "string", "example": "South East" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "You do not have access to this learner" } }, "type": "object" } } } }, "404": { "description": "Learner not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Learner not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin-summary": { "get": { "tags": [ "Api" ], "summary": "Get system summary statistics", "description": "Returns a summary of total National Officers, Zonal Admins, State Agency Admins, Centre Admins, Learners, and Facilitators. Accessible only to Super Admin.", "operationId": "superAdminSummary", "responses": { "200": { "description": "Summary retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "summary": { "properties": { "national_officers": { "type": "integer", "example": 5 }, "zonal_admins": { "type": "integer", "example": 6 }, "state_agency_admins": { "type": "integer", "example": 36 }, "centre_admins": { "type": "integer", "example": 120 }, "learners": { "type": "integer", "example": 850 }, "facilitators": { "type": "integer", "example": 95 } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/update": { "put": { "tags": [ "Centre" ], "summary": "Update Centre details", "description": "Allows an authenticated Centre Admin to update their centre information, including personal and location details, and optionally update the centre picture.", "operationId": "updateCentre", "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "properties": { "registered_name": { "type": "string", "example": "New Learning Centre" }, "community_type": { "type": "string", "enum": [ "Rural", "Urban" ], "example": "Urban" }, "ownership": { "type": "string", "enum": [ "Private", "Government" ], "example": "Private" }, "phone": { "type": "string", "example": "+2348012345678" }, "zone": { "type": "string", "enum": [ "North Central", "North East", "North West", "South East", "South South", "South West" ], "example": "South East" }, "state": { "type": "string", "example": "Anambra" }, "lga": { "type": "string", "example": "Awka South" }, "ward": { "type": "string", "example": "Umuokpu Ward" }, "latitude": { "type": "number", "format": "float", "example": 6.5243999999999999772626324556767940521240234375 }, "longitude": { "type": "number", "format": "float", "example": 3.37919999999999998152588887023739516735076904296875 }, "picture": { "description": "Optional centre picture", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Centre updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Centre updated successfully" }, "centre": { "properties": { "centre_id": { "type": "string", "example": "NMEC/ANAMB/00001" }, "registered_name": { "type": "string", "example": "New Learning Centre" }, "community_type": { "type": "string", "example": "Urban" }, "ownership": { "type": "string", "example": "Private" }, "phone": { "type": "string", "example": "+2348012345678" }, "zone": { "type": "string", "example": "South East" }, "state": { "type": "string", "example": "Anambra" }, "lga": { "type": "string", "example": "Awka South" }, "ward": { "type": "string", "example": "Umuokpu Ward" }, "latitude": { "type": "number", "example": 6.5243999999999999772626324556767940521240234375 }, "longitude": { "type": "number", "example": 3.37919999999999998152588887023739516735076904296875 }, "picture": { "type": "string", "example": "http://localhost/centre_pictures/centre_uuid.jpg" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/update/facilitators/{id}": { "post": { "tags": [ "Centre" ], "summary": "Update Facilitator basic registration details", "description": "Allows a Centre Admin to update only the basic registration details of a facilitator created under their centre.", "operationId": "updateFacilitator", "parameters": [ { "name": "id", "in": "path", "description": "ID of the Facilitator to update", "required": true, "schema": { "type": "integer", "example": 5 } } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "properties": { "surname": { "type": "string", "example": "Okafor" }, "first_name": { "type": "string", "example": "Chinedu" }, "middle_name": { "type": "string", "example": "Emeka", "nullable": true }, "email": { "type": "string", "format": "email", "example": "chinedu.okafor@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "enum": [ "Male", "Female", "Other" ], "example": "Male" }, "date_of_birth": { "type": "string", "format": "date", "example": "1992-07-15" }, "snap_picture": { "description": "Upload facilitator photo (jpg, jpeg, png)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Facilitator updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Facilitator updated successfully" }, "facilitator": { "properties": { "facilitator_id": { "type": "string", "example": "NMEC/LAG/00001/F0001" }, "surname": { "type": "string", "example": "Okafor" }, "first_name": { "type": "string", "example": "Chinedu" }, "middle_name": { "type": "string", "example": "Emeka" }, "email": { "type": "string", "example": "chinedu.okafor@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Male" }, "date_of_birth": { "type": "string", "format": "date", "example": "1992-07-15" }, "snap_picture_url": { "type": "string", "example": "https://example.com/facilitator_snaps/photo.jpg" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: Only Centre Admins can access this" } }, "type": "object" } } } }, "404": { "description": "Facilitator Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Facilitator not found or does not belong to your centre" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Update failed. Please try again." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/zonal-admins": { "get": { "tags": [ "Api" ], "summary": "Retrieve all Zonal Admins", "description": "Allows the Super Admin to retrieve a list of all users with the Zonal Admin role along with their profiles.", "operationId": "getAllZonalAdmins", "responses": { "200": { "description": "Successfully retrieved Zonal Admins", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total": { "type": "integer", "example": 5 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "johndoe@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "profile": { "description": "Zonal Admin profile details", "properties": { "id": { "type": "integer", "example": 1 }, "zonal_id": { "type": "integer", "example": 3 }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-10T16:52:40Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-03-10T16:52:40Z" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Forbidden: Only Super Admins can access this", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: Only Super Admins can access this" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/learners": { "get": { "tags": [ "Api" ], "summary": "Retrieve all Learners", "description": "Allows the Super Admin to retrieve a paginated list of all learners along with their centre and programme details. Supports optional `per_page` query parameter for pagination.", "operationId": "getAllLearners", "parameters": [ { "name": "per_page", "in": "query", "description": "Number of learners per page (pagination). Default is 10.", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Successfully retrieved learners", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total": { "type": "integer", "example": 50 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 5 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "learner_id": { "type": "string", "example": "LNR-001" }, "name": { "type": "string", "example": "Chinedu Obi" }, "email": { "type": "string", "example": "chinedu@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Male" }, "status": { "type": "string", "example": "active" }, "profile_completed": { "type": "boolean", "example": true }, "snap_picture": { "type": "string", "example": "http://localhost/facilitators/photo.jpg" }, "centre": { "properties": { "id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "Awka Learning Centre" }, "state": { "type": "string", "example": "Anambra" }, "lga": { "type": "string", "example": "Awka South" } }, "type": "object" }, "programme": { "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Literacy Programme" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Forbidden: Only Super Admins can access this", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Forbidden: Only Super Admins can access this" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/sync-offline-data": { "post": { "tags": [ "Centre" ], "summary": "Sync offline facilitators and learners data to the server", "description": "Syncs data created offline for facilitators and learners. Generates `facilitator_id` and `learner_id` automatically if not provided.", "operationId": "syncOfflineData", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "device_id" ], "properties": { "device_id": { "description": "Device identifier", "type": "string", "example": "UP1A.231005.007" }, "facilitators": { "type": "array", "items": { "properties": { "surname": { "type": "string", "example": "Hk" }, "first_name": { "type": "string", "example": "Jj" }, "middle_name": { "type": "string", "example": "Bbhh" }, "phone": { "type": "string", "example": "356948072" }, "email": { "type": "string", "example": "hgjgg@njjns" }, "gender": { "type": "string", "enum": [ "Male", "Female", "Other" ], "example": "Female" }, "date_of_birth": { "type": "string", "format": "date", "example": "2026-01-01" }, "offline_id": { "type": "string", "example": "F1773397503647" }, "snap_picture": { "type": "string", "example": null, "nullable": true }, "created_offline_at": { "type": "string", "format": "date-time", "example": "2026-03-13 10:25:03" } }, "type": "object" } }, "learners": { "type": "array", "items": { "properties": { "surname": { "type": "string", "example": "Gb" }, "first_name": { "type": "string", "example": "Uhh" }, "middle_name": { "type": "string", "example": "" }, "phone": { "type": "string", "example": "2880088000" }, "email": { "type": "string", "example": "ggg@ghjn.com" }, "gender": { "type": "string", "enum": [ "Male", "Female", "Other" ], "example": "Male" }, "date_of_birth": { "type": "string", "format": "date", "example": "2025-12-03" }, "program_id": { "type": "integer", "example": 12 }, "offline_id": { "type": "string", "example": "L1773364312900" }, "snap_picture": { "type": "string", "example": null, "nullable": true }, "created_offline_at": { "type": "string", "format": "date-time", "example": "2026-03-13 01:11:52" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "All data synced successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "synced": { "type": "object" }, "failed": { "type": "object" } }, "type": "object" } } } }, "207": { "description": "Partial success: some records failed to sync", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "partial_success" }, "synced": { "type": "object" }, "failed": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/programmes/{programmeId}": { "delete": { "tags": [ "Centre" ], "summary": "Remove programme assigned to the authenticated centre", "description": "Allows a Centre Admin to remove a programme that was previously assigned to their centre. This only detaches the programme from the centre and does not delete the programme from the system.", "operationId": "removeProgrammeFromCentre", "parameters": [ { "name": "programmeId", "in": "path", "description": "ID of the programme to remove from the centre", "required": true, "schema": { "type": "integer", "example": 3 } } ], "responses": { "200": { "description": "Programme removed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Programme removed successfully from centre" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "404": { "description": "Programme not found or not assigned to centre", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Programme not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/facilitators/{facilitatorId}/programmes/{programmeId}": { "delete": { "tags": [ "Centre" ], "summary": "Remove a programme assigned to a facilitator", "description": "Allows a Centre Admin to remove a programme previously assigned to a facilitator in their centre. This action only detaches the programme from the facilitator and does not delete the programme from the system.", "operationId": "removeProgrammeFromFacilitator", "parameters": [ { "name": "facilitatorId", "in": "path", "description": "ID of the facilitator", "required": true, "schema": { "type": "integer", "example": 5 } }, { "name": "programmeId", "in": "path", "description": "ID of the programme to remove", "required": true, "schema": { "type": "integer", "example": 3 } } ], "responses": { "200": { "description": "Programme removed successfully from facilitator", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Programme removed successfully from facilitator" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Unauthorized action", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthorized action" } }, "type": "object" } } } }, "404": { "description": "Facilitator or programme not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Programme not assigned to this facilitator" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/search-facilitators": { "get": { "tags": [ "Centre" ], "summary": "Search facilitators belonging to a centre", "operationId": "531a38c64ac1161f89c13482ddf4e571", "parameters": [ { "name": "search", "in": "query", "description": "Search by facilitator_id, name, email, or phone", "required": false, "schema": { "type": "string", "example": "John" } } ], "responses": { "200": { "description": "Facilitators retrieved successfully" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/search-learners": { "get": { "tags": [ "Centre" ], "summary": "Search learners belonging to a centre", "operationId": "90ae82fac87a1022099c11e00a73472b", "parameters": [ { "name": "search", "in": "query", "description": "Search by learner_id, name, email, or phone", "required": false, "schema": { "type": "string", "example": "Mary" } } ], "responses": { "200": { "description": "Learners retrieved successfully" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/learner/{id}": { "get": { "tags": [ "Api" ], "summary": "Get a learner by ID (Super Admin only)", "description": "Retrieve a learner's full details using their learner_id. Accessible only to Super Admins.", "operationId": "getLearnerByIdSuper", "parameters": [ { "name": "id", "in": "path", "description": "The unique learner_id of the learner", "required": true, "schema": { "type": "string", "example": "1" } } ], "responses": { "200": { "description": "Learner found successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "learner": { "properties": { "id": { "type": "string", "example": "1" }, "name": { "type": "string", "example": "John Doe" }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "M" }, "email": { "type": "string", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "program_id": { "type": "integer", "example": 4 }, "centre_of_choice": { "type": "string", "example": "Centre Name" }, "gender": { "type": "string", "example": "Male" }, "date_of_birth": { "type": "string", "format": "date", "example": "2005-06-15" }, "profile_completed": { "type": "boolean", "example": true }, "snap_picture_url": { "type": "string", "example": "http://example.com/snapshots/123.jpg" }, "status": { "type": "string", "example": "approved" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Learner not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Learner not found." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/edit-zonal-admin/{id}": { "put": { "tags": [ "Api" ], "summary": "Edit Zonal Admin", "description": "Allows Super Admin to update one or more Zonal Admin fields", "operationId": "editZonalAdmin", "parameters": [ { "name": "id", "in": "path", "description": "Zonal Admin User ID", "required": true, "schema": { "type": "integer", "example": 21 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "surname": { "type": "string", "example": "Okorowata" }, "first_name": { "type": "string", "example": "Chioma" }, "middle_name": { "type": "string", "example": "Augustine" }, "email": { "type": "string", "format": "email", "example": "chioma@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "name_of_zone": { "type": "string", "enum": [ "North Central", "North West", "North East", "South South", "South East", "South West" ], "example": "South East" }, "state_of_zone": { "type": "string", "example": "Imo" }, "lga_of_zone": { "type": "string", "example": "Owerri" } }, "type": "object" } } } }, "responses": { "200": { "description": "Zonal Admin updated successfully" }, "404": { "description": "Zonal Admin not found" }, "422": { "description": "Validation Error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/zonal-admin/{id}": { "get": { "tags": [ "Api" ], "summary": "Get Zonal Admin by ID", "description": "Retrieve a Zonal Admin along with their profile information", "operationId": "getZonalAdminById", "parameters": [ { "name": "id", "in": "path", "description": "Zonal Admin User ID", "required": true, "schema": { "type": "integer", "example": 21 } } ], "responses": { "200": { "description": "Zonal Admin retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Zonal Admin retrieved successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 21 }, "surname": { "type": "string", "example": "Okorowata" }, "first_name": { "type": "string", "example": "Chioma" }, "middle_name": { "type": "string", "example": "Augustine" }, "email": { "type": "string", "example": "user@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "name_of_zone": { "type": "string", "example": "South East" }, "state_of_zone": { "type": "string", "example": "Imo" }, "lga_of_zone": { "type": "string", "example": "Owerri" }, "zonal_admin_profile": { "properties": { "gender": { "type": "string", "example": "Female" }, "marital_status": { "type": "string", "example": "Single" }, "staff_id": { "type": "string", "example": "ZA001" }, "dob": { "type": "string", "format": "date", "example": "1990-05-12" }, "year_of_employment": { "type": "string", "example": "2023" }, "passport": { "type": "string", "example": "passport.jpg" }, "signature": { "type": "string", "example": "signature.png" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Zonal Admin not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Zonal Admin not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/delete-zonal-admin/{id}": { "delete": { "tags": [ "Api" ], "summary": "Delete Zonal Admin", "description": "Allows Super Admin to delete a Zonal Admin along with related State Agency Admins and their profile images", "operationId": "deleteZonalAdmin", "parameters": [ { "name": "id", "in": "path", "description": "Zonal Admin User ID", "required": true, "schema": { "type": "integer", "example": 21 } } ], "responses": { "200": { "description": "Zonal Admin and related State Agency Admins deleted successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Zonal Admin and related State Agency Admins deleted successfully" } }, "type": "object" } } } }, "404": { "description": "Zonal Admin not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Zonal Admin not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/super-admin/state-agency-admin/{id}": { "get": { "tags": [ "Api" ], "summary": "Get State Agency Admin by ID", "description": "Allows Super Admin to retrieve a State Agency Admin by ID including their profile details and the Zonal Admin they belong to", "operationId": "getStateAgencyAdminByIdSuper", "parameters": [ { "name": "id", "in": "path", "description": "State Agency Admin User ID", "required": true, "schema": { "type": "integer", "example": 12 } } ], "responses": { "200": { "description": "State Agency Admin retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "id": { "type": "integer", "example": 12 }, "surname": { "type": "string", "example": "Okafor" }, "first_name": { "type": "string", "example": "Chinedu" }, "middle_name": { "type": "string", "example": "James" }, "email": { "type": "string", "example": "stateadmin@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "roles": { "type": "array", "items": { "type": "string", "example": "State Agency Admin" } }, "profile": { "properties": { "gender": { "type": "string", "example": "Male" }, "marital_status": { "type": "string", "example": "Single" }, "passport": { "type": "string", "example": "http://localhost/passports/passport_xxx.jpg" }, "signature": { "type": "string", "example": "http://localhost/signatures/signature_xxx.png" }, "nin": { "type": "string", "example": "12345678901" }, "staff_id": { "type": "string", "example": "SA123" }, "dob": { "type": "string", "format": "date", "example": "1992-04-12" }, "year_of_employment": { "type": "integer", "example": 2023 }, "state": { "type": "string", "example": "Lagos" } }, "type": "object" }, "zonal_admin": { "properties": { "id": { "type": "integer", "example": 4 }, "surname": { "type": "string", "example": "Adeyemi" }, "first_name": { "type": "string", "example": "Tunde" }, "middle_name": { "type": "string", "example": "Olu" }, "email": { "type": "string", "example": "zonaladmin@example.com" }, "phone": { "type": "string", "example": "08098765432" }, "name_of_zone": { "type": "string", "example": "South West" }, "state_of_zone": { "type": "string", "example": "Lagos" }, "lga_of_zone": { "type": "string", "example": "Ikeja" } }, "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "State Agency Admin not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "State Agency Admin not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/assign-learner-programme": { "post": { "tags": [ "Centre" ], "summary": "Assign Learner to Programme", "description": "Allows a Centre Admin to assign a learner to a programme that belongs to the centre.", "operationId": "assignLearnerToProgramme", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "learner_id", "programme_id" ], "properties": { "learner_id": { "description": "ID of the learner to assign", "type": "integer", "example": 12 }, "programme_id": { "description": "ID of the programme", "type": "integer", "example": 3 } }, "type": "object" } } } }, "responses": { "200": { "description": "Learner assigned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Learner assigned to programme successfully" }, "learner": { "properties": { "id": { "type": "integer", "example": 12 }, "programme_id": { "type": "integer", "example": 3 }, "centre_of_choice": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Programme does not belong to the centre", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Programme does not belong to this centre" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/change-learner-programme": { "post": { "tags": [ "Centre" ], "summary": "Promote or Demote Learner to Another Programme", "description": "Allows a Centre Admin to change a learner's programme (promote or demote) within the same centre.", "operationId": "changeLearnerProgramme", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "learner_id", "programme_id" ], "properties": { "learner_id": { "description": "ID of the learner", "type": "integer", "example": 15 }, "programme_id": { "description": "ID of the new programme", "type": "integer", "example": 4 } }, "type": "object" } } } }, "responses": { "200": { "description": "Learner programme updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Learner programme updated successfully" }, "data": { "properties": { "learner_id": { "type": "integer", "example": 15 }, "old_programme": { "type": "string", "example": "Basic Literacy" }, "new_programme": { "type": "string", "example": "Digital Literacy" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Learner already in the programme", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Learner is already in this programme" } }, "type": "object" } } } }, "403": { "description": "Programme does not belong to this centre", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Programme does not belong to this centre" } }, "type": "object" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/assign-facilitator-programme": { "post": { "tags": [ "Centre" ], "summary": "Assign Facilitator to Programme", "description": "Allows a Centre Admin to assign a facilitator to a programme. Once assigned, the facilitator automatically inherits all learners currently enrolled in that programme.", "operationId": "assignFacilitatorToProgramme", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "facilitator_id", "programme_id" ], "properties": { "facilitator_id": { "description": "ID of the facilitator to assign", "type": "integer", "example": 5 }, "programme_id": { "description": "ID of the programme", "type": "integer", "example": 2 } }, "type": "object" } } } }, "responses": { "200": { "description": "Facilitator assigned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Facilitator assigned to programme successfully" }, "data": { "properties": { "facilitator_id": { "type": "integer", "example": 5 }, "programme_id": { "type": "integer", "example": 2 }, "learners_assigned": { "type": "integer", "example": 15 } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Programme does not belong to the centre", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Programme does not belong to this centre" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "example": { "facilitator_id": [ "The facilitator id field is required." ], "programme_id": [ "The programme id field is required." ] } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/centres-enrollment": { "get": { "tags": [ "Api" ], "summary": "Get all centres with enrollment stats", "description": "Retrieve a list of all centres with the total number of learners for each centre and total centres count.", "operationId": "7e874b27f816d07947f18039fd4e08f8", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "total_centres": { "type": "integer", "example": 25 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 7 }, "name": { "type": "string", "example": "ABC Learning Centre" }, "community_type": { "type": "string", "example": "Rural" }, "ownership": { "type": "string", "example": "Private" }, "email": { "type": "string", "example": "centre@gmail.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "centre_id": { "type": "string", "example": "abc2025001" }, "status": { "type": "string", "example": "pending" }, "total_learners": { "type": "integer", "example": 15 }, "created_at": { "type": "string", "format": "date-time", "example": "2025-06-21 16:59:35" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/centres-enrollment-per-month": { "get": { "tags": [ "Api" ], "summary": "Get monthly enrolment statistics for each centre", "description": "Retrieve the number of learners enrolled per centre, grouped by year and month.", "operationId": "777c9eb4ba957b90883cf666b2692236", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Monthly enrolment data per centre", "type": "object", "additionalProperties": { "type": "array", "items": { "properties": { "year": { "type": "integer", "example": 2025 }, "month": { "type": "integer", "example": 6 }, "total_enrolled": { "type": "integer", "example": 5 } }, "type": "object" } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/centres-by-state": { "get": { "tags": [ "Api" ], "summary": "Get centres grouped by state", "description": "Retrieve all centres grouped by state including the total number of centres in each state.", "operationId": "31dd20e161acb5904f064131d7685eee", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "state": { "type": "string", "example": "Lagos" }, "total_centres": { "type": "integer", "example": 3 }, "centres": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 7 }, "registered_name": { "type": "string", "example": "ABC Learning Centre" }, "centre_id": { "type": "string", "example": "abc2025001" }, "community_type": { "type": "string", "example": "Rural" }, "ownership": { "type": "string", "example": "Private" }, "lga": { "type": "string", "example": "Ikeja" }, "ward": { "type": "string", "example": "Ward 2" }, "status": { "type": "string", "example": "pending" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/sector-distribution": { "get": { "tags": [ "Api" ], "summary": "Get sector distribution of centres", "description": "Returns the number of centres grouped by sector (Private and Public). Government ownership is categorized as Public.", "operationId": "cd8505f77970e444edb6dbd54fa597e2", "responses": { "200": { "description": "Sector distribution retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "List of sectors with total number of centres", "type": "array", "items": { "properties": { "sector": { "description": "Sector type (Private or Public)", "type": "string", "example": "Private" }, "total_centres": { "description": "Total number of centres in the sector", "type": "integer", "example": 5 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/program-enrollment-distribution": { "get": { "tags": [ "Api" ], "summary": "Get program enrollment distribution", "description": "Returns the list of programs and the number of students enrolled in each program.", "operationId": "8f341dfc66ce0d146c4207bd68a04019", "responses": { "200": { "description": "Program enrollment distribution retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "List of programs with total students enrolled", "type": "array", "items": { "properties": { "id": { "description": "Program ID", "type": "integer", "example": 1 }, "name": { "description": "Program name", "type": "string", "example": "Literacy Program" }, "total_students": { "description": "Total number of students enrolled in the program", "type": "integer", "example": 12 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/programs/enrollment/monthly": { "get": { "tags": [ "Api" ], "summary": "Get program enrollment distribution by month", "description": "Returns the number of students enrolled in each program, grouped by month with human-readable month names.", "operationId": "1bcb32beeb54d2aaedd470a735eaaca3", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Literacy Program" }, "year": { "type": "integer", "example": 2026 }, "month": { "type": "string", "example": "January" }, "total_students": { "type": "integer", "example": 12 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/programs-with-learners-centres": { "get": { "tags": [ "Api" ], "summary": "Get all programs with learners and their centres", "description": "Retrieve a list of all programs along with their enrolled learners and the centres those learners belong to. This endpoint provides a comprehensive view of program enrollments and associated centre information.", "operationId": "getProgramsWithLearnersAndCenters", "responses": { "200": { "description": "Successful response with programs, learners, and centres", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "program_id": { "type": "integer", "example": 1 }, "program_name": { "type": "string", "example": "Computer Science" }, "learners": { "type": "array", "items": { "properties": { "learner_id": { "type": "string", "example": "2025643498" }, "name": { "type": "string", "example": "Emeka Pero Ayaya" }, "email": { "type": "string", "example": "learner@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "status": { "type": "string", "example": "approved" }, "centre": { "properties": { "centre_id": { "type": "string", "example": "abc2025001" }, "registered_name": { "type": "string", "example": "ABC Learning Centre" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" }, "ward": { "type": "string", "example": "Ward 1" } }, "type": "object", "nullable": true } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal server error" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/program-enrollment-counts": { "get": { "tags": [ "Api" ], "summary": "Get program enrollment counts", "description": "Returns a list of programs along with the total number of learners enrolled in each program.", "operationId": "22c004db45e684870a607fd899c6366a", "responses": { "200": { "description": "Successful response with programs and learner counts", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "program_id": { "type": "integer", "example": 1 }, "program_name": { "type": "string", "example": "Basic Literacy" }, "total_learners": { "type": "integer", "example": 25 } }, "type": "object" } } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal Server Error" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/learners-by-gender-centre": { "get": { "tags": [ "Api" ], "summary": "Get learners grouped by gender per centre", "description": "Returns a list of centres with learners grouped by gender, including learner details and program information.", "operationId": "getLearnersByGenderPerCentre", "responses": { "200": { "description": "Successful retrieval of learners by gender per centre", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "centre_id": { "type": "string", "example": "abc2025001" }, "centre_name": { "type": "string", "example": "ABC Learning Centre" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" }, "ward": { "type": "string", "example": "Ward 1" }, "learners_by_gender": { "properties": { "Female": { "properties": { "total": { "type": "integer", "example": 10 }, "learners": { "type": "array", "items": { "properties": { "learner_id": { "type": "string", "example": "2025643498" }, "name": { "type": "string", "example": "Emeka Pero Ayaya" }, "email": { "type": "string", "example": "emeka@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "status": { "type": "string", "example": "approved" }, "program_id": { "type": "integer", "example": 4 } }, "type": "object" } } }, "type": "object" }, "Male": { "properties": { "total": { "type": "integer", "example": 5 }, "learners": { "type": "array", "items": { "properties": { "learner_id": { "type": "string", "example": "NMEC/ANAMB/00001/0002" }, "name": { "type": "string", "example": "Doe John Michael" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+2348012345673" }, "status": { "type": "string", "example": "pending" }, "program_id": { "type": "integer", "example": 1 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Something went wrong" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/zonal/centres/enrollment": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get all centres enrollment stats for authenticated zonal admin", "description": "Retrieve all centres under the authenticated zonal admin's zone along with total learners per centre.", "operationId": "02facc88699b5abacb905a1abedc5946", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "zone": { "type": "string", "example": "South East" }, "total_centres": { "type": "integer", "example": 5 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 7 }, "name": { "type": "string", "example": "ABC Learning Centre" }, "community_type": { "type": "string", "example": "Urban" }, "ownership": { "type": "string", "example": "Private" }, "email": { "type": "string", "example": "centre@gmail.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "centre_id": { "type": "string", "example": "abc2025001" }, "status": { "type": "string", "example": "active" }, "total_learners": { "type": "integer", "example": 25 }, "state": { "type": "string", "example": "Delta" }, "lga": { "type": "string", "example": "Awka South" }, "created_at": { "type": "string", "format": "date-time", "example": "2025-06-21 16:59:35" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Zonal admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Zonal admin profile not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/zonal/programs/enrollment": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get program enrollment distribution for authenticated zonal admin", "description": "Returns the list of programs along with the total number of students enrolled in each program and the centres offering the program for the zonal admin's zone.", "operationId": "ec99f7a6b2ca0374f4798c3e92ccebdf", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "zone": { "type": "string", "example": "South East" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Adult Literacy Program" }, "total_students": { "type": "integer", "example": 120 }, "centres": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 7 }, "name": { "type": "string", "example": "ABC Learning Centre" }, "state": { "type": "string", "example": "Delta" }, "lga": { "type": "string", "example": "Awka South" }, "total_learners": { "type": "integer", "example": 25 } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Zonal admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Zonal admin profile not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/zonal/programs/enrollment/monthly": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get monthly program enrollment distribution for zonal admin", "description": "Returns monthly student enrollment per program for the authenticated zonal admin based on centres within their zone. No year filtering is applied.", "operationId": "95f2f5e365893c6c4451c9db7bb282ef", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "zone": { "type": "string", "example": "South East" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Adult Literacy Program" }, "total_students": { "type": "integer", "example": 120 }, "monthly": { "type": "array", "items": { "properties": { "month": { "type": "string", "example": "Jan" }, "total_students": { "type": "integer", "example": 10 } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Zonal admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Zonal admin profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/zonal/sector-distribution": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get sector distribution for zonal admin", "description": "Returns the distribution of centres by sector (Private and Public) for the authenticated zonal admin. Government ownership is categorized as Public. Data is filtered based on states under the zonal admin.", "operationId": "b153143748f3c8d0e5a4600d78f7c6bb", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "zone": { "type": "string", "example": "South East" }, "total_centres": { "type": "integer", "example": 12 }, "data": { "type": "array", "items": { "properties": { "sector": { "type": "string", "example": "Private" }, "total_centres": { "type": "integer", "example": 9 } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Zonal admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Zonal admin profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Bearer token required", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/zonal/programs-learners-centres": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get all programs with learners and their centres (Zonal Admin)", "description": "Returns all programs with their learners and associated centres, filtered by the authenticated zonal admin's states. Only learners whose centres fall within the zonal admin's states are included.", "operationId": "a25dc53cbd094e5daa5b2d23b7aa2a46", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "zone": { "type": "string", "example": "South West" }, "total_programs": { "type": "integer", "example": 3 }, "total_learners": { "type": "integer", "example": 120 }, "data": { "type": "array", "items": { "properties": { "program_id": { "type": "integer", "example": 1 }, "program_name": { "type": "string", "example": "ICT Training" }, "total_learners": { "type": "integer", "example": 45 }, "learners": { "type": "array", "items": { "properties": { "learner_id": { "type": "string", "example": "NMEC/001/0001" }, "name": { "type": "string", "example": "John Doe Smith" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "status": { "type": "string", "example": "approved" }, "centre": { "properties": { "centre_id": { "type": "string", "example": "CTR/001" }, "registered_name": { "type": "string", "example": "ABC Training Centre" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" }, "ward": { "type": "string", "example": "Ward 3" } }, "type": "object", "nullable": true } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Zonal admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Zonal admin profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/zone/program-enrollment-counts": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get total learners enrolled per program (Zonal Admin)", "description": "Returns a list of programs along with the total number of learners enrolled in each program, filtered by the zonal admin's states.", "operationId": "d3078ea6de0f482e6b0a6c0dec378116", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "zone": { "type": "string", "example": "South West" }, "total_programs": { "type": "integer", "example": 5 }, "total_learners": { "type": "integer", "example": 120 }, "data": { "type": "array", "items": { "properties": { "program_id": { "type": "integer", "example": 1 }, "program_name": { "type": "string", "example": "ICT Training" }, "total_learners": { "type": "integer", "example": 45 } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Zonal admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Zonal admin profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/zonal/learners-by-gender-per-centre": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get learners grouped by gender per centre (Zonal Admin)", "description": "Returns a list of centres under the zonal admin's states along with learners grouped by gender.", "operationId": "6462daf5407490f9f4871cdbe52f4fde", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "zone": { "type": "string", "example": "South East" }, "total_centres": { "type": "integer", "example": 10 }, "data": { "type": "array", "items": { "properties": { "centre_id": { "type": "string", "example": "CENTRE/001/0001" }, "centre_name": { "type": "string", "example": "ABC Learning Centre" }, "state": { "type": "string", "example": "Delta" }, "lga": { "type": "string", "example": "Awka South" }, "ward": { "type": "string", "example": "Umuokpu Ward" }, "learners_by_gender": { "properties": { "Male": { "properties": { "total": { "type": "integer", "example": 12 }, "learners": { "type": "array", "items": { "properties": { "learner_id": { "type": "string", "example": "NMEC/ANAMB/00001/0001" }, "name": { "type": "string", "example": "John Doe Michael" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "status": { "type": "string", "example": "approved" }, "program_id": { "type": "integer", "example": 1 } }, "type": "object" } } }, "type": "object" }, "Female": { "properties": { "total": { "type": "integer", "example": 8 }, "learners": { "type": "array", "items": { "properties": { "learner_id": { "type": "string", "example": "NMEC/ANAMB/00001/0002" }, "name": { "type": "string", "example": "Jane Doe Mary" }, "email": { "type": "string", "example": "jane@example.com" }, "phone": { "type": "string", "example": "+2348012345679" }, "status": { "type": "string", "example": "pending" }, "program_id": { "type": "integer", "example": 2 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Zonal admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Zonal admin profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/zonal/centre-enrollment-per-month": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get learners enrolled per centre grouped by year and month (Zonal Admin)", "description": "Returns the number of learners enrolled per centre in the zonal admin's states, grouped by year and month.", "operationId": "958f1ec1e64bdd2e01da56fd51615d02", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "zone": { "type": "string", "example": "South East" }, "data": { "type": "object", "additionalProperties": { "type": "array", "items": { "properties": { "year": { "type": "integer", "example": 2026 }, "month": { "type": "string", "example": "March" }, "total_enrolled": { "type": "integer", "example": 25 } }, "type": "object" } } } }, "type": "object" } } } }, "404": { "description": "Zonal admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Zonal admin profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/state/centre-enrollment/monthly": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get learners enrolled per centre grouped by year and month for the State Agency Admin's state", "description": "Retrieve the number of learners enrolled per centre, grouped by year and month, filtered to the state assigned to the logged-in State Agency Admin.", "operationId": "662898229f2aa009d131dfcc5c0f34c7", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "state": { "type": "string", "example": "Delta" }, "data": { "type": "object", "additionalProperties": { "type": "array", "items": { "properties": { "year": { "type": "integer", "example": 2026 }, "month": { "type": "string", "example": "March" }, "total_enrolled": { "type": "integer", "example": 25 } }, "type": "object" }, "property": null } } }, "type": "object" } } } }, "404": { "description": "State Agency Admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "State Agency Admin profile not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/state/centres-enrollment": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get all centres with total learners count for the State Agency Admin's state", "description": "Retrieve a list of all centres within the logged-in State Agency Admin's state, including the total number of learners per centre and the total number of centres.", "operationId": "ef8190b6d8c32b6dade84074d874333d", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "total_centres": { "type": "integer", "example": 12 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Community Skills Centre" }, "community_type": { "type": "string", "example": "Urban" }, "ownership": { "type": "string", "example": "Government" }, "email": { "type": "string", "example": "centre@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "centre_id": { "type": "string", "example": "CEN-001" }, "status": { "type": "string", "example": "active" }, "total_learners": { "type": "integer", "example": 150 }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-17 13:45:12" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "State Agency Admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "State Agency Admin profile not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/state/programs-enrollment": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get program enrollment distribution for State Agency Admin", "description": "Retrieve a list of all programs along with the total number of learners enrolled in each program and the centres offering the program for the State Agency Admin's state.", "operationId": "getProgramEnrollmentDistribution", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "state": { "type": "string", "example": "Delta" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Program A" }, "total_students": { "type": "integer", "example": 120 }, "centres": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Centre 1" }, "state": { "type": "string", "example": "Delta" }, "lga": { "type": "string", "example": "Warri South" }, "total_learners": { "type": "integer", "example": 50 } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "State Agency Admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "State Agency Admin profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/state/programs-enrollment-monthly": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get monthly program enrollment distribution for State Agency Admin", "description": "Retrieve a list of programs with the monthly total number of students enrolled and centres offering the program for the State Agency Admin's state.", "operationId": "getProgramEnrollmentDistributionMonthly", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "state": { "type": "string", "example": "Delta" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Program A" }, "total_students": { "type": "integer", "example": 120 }, "centres": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Centre 1" }, "state": { "type": "string", "example": "Delta" }, "lga": { "type": "string", "example": "Warri South" }, "total_learners": { "type": "integer", "example": 50 }, "monthly": { "type": "array", "items": { "properties": { "year": { "type": "integer", "example": 2026 }, "month": { "type": "string", "example": "Jan" }, "total_learners": { "type": "integer", "example": 10 } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "State Agency Admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "State Agency Admin profile not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/state/centres/sector-distribution": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get number of centres grouped by sector for the State Agency Admin's state", "operationId": "313b7284656c3105d8ff23f1f39d55a2", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "state": { "type": "string", "example": "Lagos" }, "data": { "type": "array", "items": { "properties": { "sector": { "type": "string", "example": "Public" }, "total_centres": { "type": "integer", "example": 10 } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "State Agency Admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "State Agency Admin profile not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/state/programs-with-learners": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get all programs with learners and their centres for the State Agency Admin's state", "description": "Returns a list of programs with learners and their associated centres filtered by the admin's state.", "operationId": "4deca012cd37e581a71483361ad85bd5", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "state": { "type": "string", "example": "Lagos" }, "total_programs": { "type": "integer", "example": 5 }, "total_learners": { "type": "integer", "example": 120 }, "data": { "type": "array", "items": { "properties": { "program_id": { "type": "integer", "example": 1 }, "program_name": { "type": "string", "example": "Adult Literacy" }, "total_learners": { "type": "integer", "example": 25 }, "learners": { "type": "array", "items": { "properties": { "learner_id": { "type": "integer", "example": 101 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "status": { "type": "string", "example": "active" }, "centre": { "properties": { "centre_id": { "type": "string", "example": "lag2025003" }, "registered_name": { "type": "string", "example": "Lagos Education Centre" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" }, "ward": { "type": "string", "example": "Ward 5" } }, "type": "object", "nullable": true } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "State Agency Admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "State Agency Admin profile not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/state/programs-enrollment-counts": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get programs with total learners for State Agency Admin's state", "description": "Returns a list of programs along with the total number of learners enrolled in each program filtered by the admin's state.", "operationId": "c6c96d9c75b8eb0259bee6dc87e228d2", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "program_id": { "type": "integer", "example": 1 }, "program_name": { "type": "string", "example": "Adult Literacy" }, "total_learners": { "type": "integer", "example": 25 } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "State Agency Admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "State Agency Admin profile not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/state/learners-by-gender": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get learners grouped by gender per centre for State Agency Admin's state", "description": "Returns all centres in the State Agency Admin's state with learners grouped by gender.", "operationId": "186fccf41744b475e61f5c1a85e6aa9d", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "state": { "type": "string", "example": "Delta" }, "total_centres": { "type": "integer", "example": 5 }, "data": { "type": "array", "items": { "properties": { "centre_id": { "type": "string", "example": "abc2025001" }, "centre_name": { "type": "string", "example": "ABC Learning Centre" }, "state": { "type": "string", "example": "Delta" }, "lga": { "type": "string", "example": "Awka South" }, "ward": { "type": "string", "example": "Umuokpu Ward" }, "learners_by_gender": { "properties": { "Male": { "properties": { "total": { "type": "integer", "example": 12 }, "learners": { "type": "array", "items": { "properties": { "learner_id": { "type": "string", "example": "L001" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "status": { "type": "string", "example": "active" }, "program_id": { "type": "integer", "example": 1 } }, "type": "object" } } }, "type": "object" }, "Female": { "properties": { "total": { "type": "integer", "example": 8 }, "learners": { "type": "array", "items": { "properties": { "learner_id": { "type": "string", "example": "L002" }, "name": { "type": "string", "example": "Jane Doe" }, "email": { "type": "string", "example": "jane@example.com" }, "phone": { "type": "string", "example": "+2348098765432" }, "status": { "type": "string", "example": "active" }, "program_id": { "type": "integer", "example": 2 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "State Agency Admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "State Agency Admin profile not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/centres/status-counts": { "get": { "tags": [ "Api" ], "summary": "Get total number of centres grouped by status", "description": "Returns the total number of centres with 'approved', 'pending', and 'rejected' status", "operationId": "0352cc5a2a67f60ca343572db7744ed1", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "approved": { "type": "integer", "example": 10 }, "pending": { "type": "integer", "example": 5 }, "rejected": { "type": "integer", "example": 2 } }, "type": "object" }, "total_centres": { "type": "integer", "example": 17 } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/zone/centres/status-counts": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get total number of centres by status for Zonal Admin", "description": "Returns the total number of centres with 'approved', 'pending', and 'rejected' status in the logged-in Zonal Admin's zone", "operationId": "7c35136326715c6dca386cb91673174e", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "zone": { "type": "string", "example": "South West" }, "data": { "properties": { "approved": { "type": "integer", "example": 10 }, "pending": { "type": "integer", "example": 5 }, "rejected": { "type": "integer", "example": 2 } }, "type": "object" }, "total_centres": { "type": "integer", "example": 17 } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Zonal admin profile not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/state/centres/status-counts": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get centre status counts for a State Agency Admin", "description": "Returns the total number of centres with 'approved', 'pending', and 'rejected' status for the state of the authenticated State Agency Admin.", "operationId": "getCentreStatusCountsByState", "responses": { "200": { "description": "Successful response with counts of centres by status", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "state": { "type": "string", "example": "Lagos" }, "data": { "properties": { "approved": { "type": "integer", "example": 5 }, "pending": { "type": "integer", "example": 3 }, "rejected": { "type": "integer", "example": 1 } }, "type": "object" }, "total_centres": { "type": "integer", "example": 9 } }, "type": "object" } } } }, "404": { "description": "State Agency Admin profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "State Agency Admin profile not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/centre/programs/enrollment-distribution": { "get": { "tags": [ "Centre" ], "summary": "Get program enrollment distribution for the authenticated centre", "description": "Returns the total number of learners enrolled per program in the centre of the authenticated Centre Admin.", "operationId": "getProgramEnrollmentDistributionForCentre", "responses": { "200": { "description": "Successful response with programs and learner counts", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "centre_id": { "type": "integer", "example": 15 }, "centre_name": { "type": "string", "example": "ABC Learning Centre" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Computer Science" }, "total_students": { "type": "integer", "example": 50 } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Centre profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Centre profile not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/stats/centre/programs/monthly-enrollment": { "get": { "tags": [ "Centre" ], "summary": "Get monthly program enrollment distribution for the authenticated centre", "description": "Returns each program linked to the authenticated centre along with monthly learner enrollment counts.", "operationId": "f74fafb746f164c6e84a511859b26a00", "responses": { "200": { "description": "Success - Returns monthly enrollment distribution", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "centre_id": { "type": "integer", "example": 7 }, "centre_name": { "type": "string", "example": "ABC Learning Centre" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Youth Skills Program" }, "monthly_enrollments": { "description": "List of monthly enrollment counts for the program", "type": "array", "items": { "properties": { "year": { "type": "integer", "example": 2026 }, "month": { "type": "integer", "example": 3 }, "total": { "type": "integer", "example": 12 } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Centre profile not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Centre profile not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/get/all/facilitators": { "get": { "tags": [ "Api" ], "summary": "Get all facilitators with programmes and learners", "description": "Returns a paginated list of facilitators including their assigned programmes and learners under those programmes", "operationId": "getAllFacilitators3", "parameters": [ { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total": { "type": "integer", "example": 50 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 5 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "facilitator_id": { "type": "string", "example": "FAC12345" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Male" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "boolean", "example": true }, "snap_picture": { "type": "string", "example": "https://example.com/image.jpg" }, "centre": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "ABC Learning Centre" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" } }, "type": "object" }, "programmes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Basic Literacy" } }, "type": "object" } }, "learners": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "learner_id": { "type": "string", "example": "2025643498" }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Michael" }, "email": { "type": "string", "example": "john@gmail.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Male" }, "date_of_birth": { "type": "string", "format": "date", "example": "2005-06-15" }, "snap_picture": { "type": "string", "example": "https://example.com/image.jpg" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "boolean", "example": true } }, "type": "object" } }, "statistics": { "properties": { "total_learners": { "type": "integer", "example": 20 } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/get/facilitators/{id}": { "get": { "tags": [ "Api" ], "summary": "Get facilitator by ID", "description": "Returns a facilitator with assigned programmes and learners under those programmes", "operationId": "getFacilitatorById2", "parameters": [ { "name": "id", "in": "path", "description": "Facilitator ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "facilitator_id": { "type": "string", "example": "FAC12345" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Male" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "boolean", "example": true }, "snap_picture": { "type": "string", "example": "https://example.com/image.jpg" }, "centre": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "ABC Learning Centre" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" } }, "type": "object" }, "programmes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Basic Literacy" } }, "type": "object" } }, "learners": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "learner_id": { "type": "string", "example": "2025643498" }, "surname": { "type": "string", "example": "Doe" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "Michael" }, "email": { "type": "string", "example": "john@gmail.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Male" }, "date_of_birth": { "type": "string", "format": "date", "example": "2005-06-15" }, "snap_picture": { "type": "string", "example": "https://example.com/image.jpg" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "boolean", "example": true } }, "type": "object" } }, "statistics": { "properties": { "total_learners": { "type": "integer", "example": 20 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Facilitator not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/zonal/facilitators": { "get": { "tags": [ "Zonal Admin" ], "summary": "Get facilitators in zonal admin zone", "description": "Returns all facilitators belonging to centres within the zonal admin's assigned state and LGA", "operationId": "getZonalFacilitators", "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Successful response" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/state/facilitators": { "get": { "tags": [ "State Agency Admin" ], "summary": "Get facilitators in state (State Agency Admin)", "description": "Returns all facilitators belonging to centres within the state of the logged-in State Agency Admin", "operationId": "getStateFacilitators", "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Successful response" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/facilitators/all": { "get": { "tags": [ "Centre" ], "summary": "Get facilitators in a centre", "description": "Returns all facilitators belonging to the authenticated centre admin", "operationId": "getCentreFacilitators5", "parameters": [ { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Successful response" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/facilitatorById/{id}": { "get": { "tags": [ "Centre" ], "summary": "Get a facilitator by ID for the authenticated centre", "description": "Returns a single facilitator including their programmes and learners, but only if the facilitator belongs to the authenticated centre.", "operationId": "271906c0af80b38d3856d3bc04b8c71b", "parameters": [ { "name": "id", "in": "path", "description": "ID of the facilitator", "required": true, "schema": { "type": "integer", "example": 4 } } ], "responses": { "200": { "description": "Facilitator found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "centre": { "properties": { "id": { "type": "integer", "example": 15 }, "name": { "type": "string", "example": "ABC Training Centre" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" } }, "type": "object" }, "data": { "properties": { "id": { "type": "integer", "example": 4 }, "facilitator_id": { "type": "string", "example": "CENTRE/001/F0001" }, "name": { "type": "string", "example": "John M Doe" }, "email": { "type": "string", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Male" }, "status": { "type": "string", "example": "pending" }, "profile_completed": { "type": "boolean", "example": false }, "snap_picture": { "type": "string", "example": "http://example.com/facilitator_snaps/1773205698_f_6959.png" }, "centre": { "properties": { "id": { "type": "integer", "example": 15 }, "name": { "type": "string", "example": "ABC Training Centre" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "example": "Ikeja" } }, "type": "object" }, "programmes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Computer Basics" } }, "type": "object" } }, "learners": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 101 }, "learner_id": { "type": "string", "example": "LEARN/2025/001" }, "surname": { "type": "string", "example": "Smith" }, "first_name": { "type": "string", "example": "Jane" }, "middle_name": { "type": "string", "example": "A" }, "email": { "type": "string", "example": "jane.smith@example.com" }, "phone": { "type": "string", "example": "+2348012345678" }, "gender": { "type": "string", "example": "Female" }, "date_of_birth": { "type": "string", "format": "date", "example": "2000-01-01" }, "snap_picture": { "type": "string", "example": "http://example.com/learner_snaps/101.png" }, "status": { "type": "string", "example": "active" }, "profile_completed": { "type": "boolean", "example": true } }, "type": "object" } }, "statistics": { "properties": { "total_learners": { "type": "integer", "example": 25 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Facilitator not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Facilitator not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centres/state/{state}": { "get": { "tags": [ "Api" ], "summary": "Get all centres by state", "description": "Retrieve all centres filtered by state (case-insensitive). Example: Delta, delta, DELTA all return the same result.", "operationId": "151cd647db3a4c36be95c72495d24d17", "parameters": [ { "name": "state", "in": "path", "description": "State name (case-insensitive)", "required": true, "schema": { "type": "string", "example": "Delta" } } ], "responses": { "200": { "description": "Centres retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_centres": { "type": "integer", "example": 2 }, "centres": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 15 }, "registered_name": { "type": "string", "example": "Xyz Learning Centre" }, "centre_id": { "type": "string", "example": "NMEC/ANAMB/00001" }, "state": { "type": "string", "example": "Delta" }, "lga": { "type": "string", "example": "Awka South" }, "ward": { "type": "string", "example": "Umuokpu Ward" }, "phone": { "type": "string", "example": "+2348012345678" }, "email": { "type": "string", "example": "xyz@gmail.com" }, "status": { "type": "string", "example": "approved" }, "profile_completed": { "type": "boolean", "example": true }, "picture": { "type": "string", "example": "http://localhost:8000/centre_pictures/image.png" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "No centres found for this state", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "No centres found for this state." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centres/states/count": { "get": { "tags": [ "Api" ], "summary": "Get all states with total number of centres", "description": "Returns a list of states and the total number of centres in each state.", "operationId": "getStatesWithCentreCount", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "total_states": { "type": "integer", "example": 3 }, "data": { "type": "array", "items": { "properties": { "state": { "type": "string", "example": "Lagos" }, "total_centres": { "type": "integer", "example": 20 } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/facilitator/{id}/learner/programme/stats": { "get": { "tags": [ "Facilitator" ], "summary": "Get facilitator statistics", "description": "Returns total programmes and total learners assigned to a facilitator", "operationId": "getFacilitatorStats", "parameters": [ { "name": "id", "in": "path", "description": "Facilitator ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "facilitator_id": { "type": "integer", "example": 1 }, "total_programmes": { "type": "integer", "example": 5 }, "total_learners": { "type": "integer", "example": 120 } }, "type": "object" } } } }, "404": { "description": "Facilitator not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Facilitator not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/facilitators/{id}/programmes-learners": { "get": { "tags": [ "Facilitator" ], "summary": "Get facilitator programmes with learners", "description": "Returns all programmes assigned to a facilitator along with their learners filtered by the facilitator's centre.", "operationId": "getFacilitatorProgrammesWithLearners", "parameters": [ { "name": "id", "in": "path", "description": "Facilitator ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "facilitator_id": { "type": "integer", "example": 1 }, "centre_id": { "type": "string", "example": "NMEC/ANAMB/00001" }, "total_programmes": { "type": "integer", "example": 2 }, "programmes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Web Development" }, "total_learners": { "type": "integer", "example": 3 }, "learners": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "learner_id": { "type": "string", "example": "LRN001" }, "name": { "type": "string", "example": "Doe John Smith" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "phone": { "type": "string", "example": "08012345678" }, "gender": { "type": "string", "enum": [ "male", "female", "other" ], "example": "male" }, "status": { "type": "string", "example": "active" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Facilitator not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Facilitator not found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/learners/{id}/programme-details": { "get": { "tags": [ "Learner" ], "summary": "Get learner programme details", "description": "Returns a learner's programme, including subjects and assigned facilitators", "operationId": "getLearnerProgrammeDetails", "parameters": [ { "name": "id", "in": "path", "description": "Learner ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "learner_id": { "type": "integer", "example": 1 }, "programme": { "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "Computer Science" }, "description": { "type": "string", "example": "A programme focused on computing and software development" }, "subjects": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Data Structures" }, "description": { "type": "string", "example": "Study of data organization and algorithms" } }, "type": "object" } }, "facilitators": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "John Doe Smith" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "08012345678" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Learner not found or no programme assigned", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Learner not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/centre/facilitators/{id}": { "delete": { "tags": [ "Centre" ], "summary": "Delete a facilitator under the authenticated centre", "description": "Deletes a facilitator, including all assigned programmes, learner relationships, and profile files. Only facilitators belonging to the authenticated centre can be deleted.", "operationId": "deleteFacilitator", "parameters": [ { "name": "id", "in": "path", "description": "ID of the facilitator to delete", "required": true, "schema": { "type": "integer", "example": 4 } } ], "responses": { "200": { "description": "Facilitator deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facilitator deleted successfully along with all assigned programmes and learner associations." } }, "type": "object" } } } }, "404": { "description": "Facilitator not found in this centre", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facilitator not found in this centre" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Forbidden: You do not have permission to delete this facilitator" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "tags": [ { "name": "Api", "description": "Api" }, { "name": "Unprotected", "description": "Unprotected" }, { "name": "National Officers", "description": "National Officers" }, { "name": "Centre", "description": "Centre" }, { "name": "Zonal Admin", "description": "Zonal Admin" }, { "name": "State Agency Admin", "description": "State Agency Admin" }, { "name": "Learner", "description": "Learner" }, { "name": "Facilitator", "description": "Facilitator" }, { "name": "Certificate", "description": "Certificate" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "description": "Enter JWT with Bearer prefix", "name": "Authorization", "in": "header", "scheme": "bearer", "bearerFormat": "JWT" } } } }