{"openapi":"3.0.3","info":{"title":"Belkuchi Shishu Academy — EMS API Engine","version":"2.0.0","description":"Enterprise REST API backend for Belkuchi Shishu Academy (EMS). Features comprehensive modules for Academic Management, Attendance, Examination & Grading, SMS Notifications, Online Admissions, Student Billing, and User Role Administration.","contact":{"name":"EMS System Engineering Desk","email":"info@ems.edu.bd","url":"https://ems.edu.bd"},"license":{"name":"Proprietary","url":"https://ems.edu.bd/terms"}},"servers":[{"url":"http://localhost:8000","description":"Local Development Server"},{"url":"/api/v2","description":"API v2 Base (Current)"},{"url":"/api/v1","description":"API v1 Base (Legacy Compatibility)"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter your JWT access token (obtained from /api/v1/auth/login)"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Detailed error description"}}},"LoginRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","example":"admin@ems.edu.bd"},"password":{"type":"string","example":"admin123"}}},"LoginResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"token":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"user":{"type":"object","properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"System Admin"},"email":{"type":"string","example":"admin@ems.edu.bd"},"role":{"type":"string","example":"admin"},"sub_role":{"type":"string","example":"super_admin"}}}}},"AttendanceSubmission":{"type":"object","required":["class_name","attendance_date","records"],"properties":{"class_name":{"type":"string","example":"Computer Technology"},"semester":{"type":"string","example":"4th"},"subject_code":{"type":"string","example":"CST-401"},"attendance_date":{"type":"string","format":"date","example":"2026-09-08"},"records":{"type":"array","items":{"type":"object","properties":{"student_id":{"type":"integer","example":1},"status":{"type":"string","enum":["present","absent","late"],"example":"present"},"remarks":{"type":"string","example":""}}}}}},"ExamCreation":{"type":"object","required":["title","term","academic_year","class_name","start_date","end_date"],"properties":{"title":{"type":"string","example":"Final Examination 2026"},"term":{"type":"string","example":"Final"},"academic_year":{"type":"string","example":"2025-2026"},"class_name":{"type":"string","example":"Class 10"},"start_date":{"type":"string","format":"date","example":"2026-11-15"},"end_date":{"type":"string","format":"date","example":"2026-11-30"},"is_published":{"type":"boolean","example":false}}},"BatchMarksEntry":{"type":"object","required":["exam_id","subject_code","marks"],"properties":{"exam_id":{"type":"integer","example":1},"subject_code":{"type":"string","example":"MATH-101"},"marks":{"type":"array","items":{"type":"object","properties":{"student_id":{"type":"integer","example":1},"theory_obtained":{"type":"number","example":78.5},"practical_obtained":{"type":"number","example":45},"continuous_obtained":{"type":"number","example":22}}}}}},"SmsSettingsUpdate":{"type":"object","properties":{"provider":{"type":"string","enum":["mock","greenweb","mimsms","twilio"],"example":"mock"},"api_key":{"type":"string","example":"demo-api-key-xyz"},"sender_id":{"type":"string","example":"BELKUCHI-EMS"},"monthly_quota":{"type":"integer","example":1000},"auto_absent_alert_enabled":{"type":"boolean","example":true}}}}},"tags":[{"name":"Authentication","description":"User login, registration, session validation & password resets"},{"name":"Attendance Hub","description":"Student & teacher daily roll call, analytics & absent tracking"},{"name":"Examinations & Grading","description":"Exam sessions, mark entry terminals, tabulation & report cards"},{"name":"Routine & Schedule","description":"Class routine generator, timetable management & schedule slots"},{"name":"Online Admissions","description":"Public application submissions, review, conversion & PDF generation"},{"name":"Bills & Payments","description":"Fee invoices, payment tracking, receipts & dues summaries"},{"name":"SMS & Notifications","description":"SMS gateway configurations, automatic absent alerts & delivery logs"},{"name":"Users & Roles","description":"Student, teacher, parent, and staff directory management"},{"name":"Institutes & Academics","description":"Institute profiles, departments, subjects, faculty & academic calendar"},{"name":"Notices & Events","description":"Public announcements, circular bulletins & campus event schedules"},{"name":"Media & CMS","description":"Gallery albums, hero slider banners, blogs & file uploads"},{"name":"Reports & Analytics","description":"Executive dashboard summaries, system status & custom reports"}],"paths":{"/api/v1/auth/login":{"post":{"tags":["Authentication"],"summary":"Authenticate User","description":"Authenticates a user by email and password and returns a JWT Bearer token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"Authentication successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}},"401":{"description":"Invalid email or password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/auth/me":{"get":{"tags":["Authentication"],"summary":"Get Authenticated User","description":"Returns the profile data of the currently logged-in user.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Current profile data returned"},"401":{"description":"Unauthorized request"}}},"put":{"tags":["Authentication"],"summary":"Update Profile Details","description":"Update phone, address, and profile settings for authenticated user.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Updated Name"},"phone":{"type":"string","example":"+880 1812-000000"},"address":{"type":"string","example":"Belkuchi, Sirajganj"}}}}}},"responses":{"200":{"description":"Profile updated successfully"}}}},"/api/v1/attendance/submit":{"post":{"tags":["Attendance Hub"],"summary":"Submit Daily Class Attendance","description":"Submit roll-call attendance for a class session. Triggers SMS alerts to guardians of absent students if enabled.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttendanceSubmission"}}}},"responses":{"200":{"description":"Attendance batch saved successfully"}}}},"/api/v1/attendance/analytics":{"get":{"tags":["Attendance Hub"],"summary":"Get Attendance Analytics","description":"Fetches attendance rate breakdown across departments, classes, and date ranges.","security":[{"bearerAuth":[]}],"parameters":[{"name":"class_name","in":"query","schema":{"type":"string"},"description":"Filter by class/department"},{"name":"month","in":"query","schema":{"type":"string"},"description":"Month in YYYY-MM format"}],"responses":{"200":{"description":"Analytics data object returned"}}}},"/api/v1/exams":{"get":{"tags":["Examinations & Grading"],"summary":"List All Examinations","description":"Returns list of registered examination sessions and academic terms.","responses":{"200":{"description":"List of exams returned"}}},"post":{"tags":["Examinations & Grading"],"summary":"Create New Examination Session","description":"Registers a new examination session with date windows (Admin only).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExamCreation"}}}},"responses":{"200":{"description":"Exam session created"}}}},"/api/v1/exams/marks/batch":{"post":{"tags":["Examinations & Grading"],"summary":"Submit Batch Marks Entry","description":"Teacher entry terminal submission for theory, practical, and continuous evaluation marks.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchMarksEntry"}}}},"responses":{"200":{"description":"Batch marks recorded successfully"}}}},"/api/v1/admissions":{"get":{"tags":["Online Admissions"],"summary":"List Admission Applications","description":"Fetch student admission applications with status filtering.","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","rejected"]}}],"responses":{"200":{"description":"Applications returned"}}},"post":{"tags":["Online Admissions"],"summary":"Submit Online Admission Form","description":"Public endpoint to register candidate for new academic session.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["applicant_name","email","phone","department_choice"],"properties":{"applicant_name":{"type":"string","example":"Md. Al Amin"},"email":{"type":"string","example":"alamin@example.com"},"phone":{"type":"string","example":"+880 1711-998877"},"department_choice":{"type":"string","example":"Computer Technology"},"previous_school":{"type":"string","example":"Belkuchi High School"},"ssc_gpa":{"type":"string","example":"5.00"}}}}}},"responses":{"200":{"description":"Application registered successfully"}}}},"/api/v1/bills":{"get":{"tags":["Bills & Payments"],"summary":"List Student Invoices","description":"Fetches bills with payment status and dues records.","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["unpaid","paid","overdue"]}}],"responses":{"200":{"description":"Invoices array returned"}}},"post":{"tags":["Bills & Payments"],"summary":"Create Invoice","description":"Generate fee invoice for a student.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["student_id","title","amount","due_date"],"properties":{"student_id":{"type":"integer","example":1},"title":{"type":"string","example":"Semester Tuition Fee"},"amount":{"type":"number","example":4500},"due_date":{"type":"string","format":"date","example":"2026-10-15"}}}}}},"responses":{"200":{"description":"Invoice generated"}}}},"/api/v1/sms/settings":{"get":{"tags":["SMS & Notifications"],"summary":"Get SMS Gateway Settings","description":"Fetch SMS configuration, quota usage, and automated alert toggle.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"SMS settings data"}}},"post":{"tags":["SMS & Notifications"],"summary":"Update SMS Configuration","description":"Update provider API keys and quota settings.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsSettingsUpdate"}}}},"responses":{"200":{"description":"SMS settings updated"}}}},"/api/v1/sms/logs":{"get":{"tags":["SMS & Notifications"],"summary":"Get SMS Delivery Logs","description":"Returns historical log of SMS messages sent through the system.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"SMS delivery logs"}}}},"/api/v1/users":{"get":{"tags":["Users & Roles"],"summary":"List All Registered Users","description":"Admin query for users filtered by role (student, teacher, parent, admin, staff).","security":[{"bearerAuth":[]}],"parameters":[{"name":"role","in":"query","schema":{"type":"string"},"description":"Filter by role"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Search by name, email or ID"}],"responses":{"200":{"description":"User list returned"}}}},"/api/v1/notices":{"get":{"tags":["Notices & Events"],"summary":"Get Public Notices","description":"Retrieve published academic notices and departmental announcements.","parameters":[{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Notice list"}}},"post":{"tags":["Notices & Events"],"summary":"Publish Notice","description":"Publish a new official bulletin notice (Admin/Teacher).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","content"],"properties":{"title":{"type":"string","example":"Mid-Term Exam Schedule Published"},"category":{"type":"string","example":"Academic"},"content":{"type":"string","example":"Students are notified that the mid-term examinations..."},"is_important":{"type":"boolean","example":true}}}}}},"responses":{"200":{"description":"Notice published"}}}},"/api/v1/departments":{"get":{"tags":["Institutes & Academics"],"summary":"List Academic Departments","description":"Returns all academic departments and curricula.","responses":{"200":{"description":"Department list"}}}},"/api/v1/subjects":{"get":{"tags":["Institutes & Academics"],"summary":"List Curriculum Subjects","description":"Returns subjects list with credit points and semester breakdown.","responses":{"200":{"description":"Subjects list"}}}},"/api/v1/faculty":{"get":{"tags":["Institutes & Academics"],"summary":"List Teaching Faculty Members","description":"Directory of teacher profiles and departmental designations.","responses":{"200":{"description":"Faculty members list"}}}},"/api/v1/reports/summary":{"get":{"tags":["Reports & Analytics"],"summary":"System Executive Report","description":"High-level aggregation of student counts, financial metrics, and admission ratios.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Summary report generated"}}}}}}