{"name":"Orange Cat LMS REST API","version":"2.4.0","description":"Enterprise Learning & Talent Management System API Specifications","baseUrl":"http://localhost:5000","endpoints":[{"method":"POST","path":"/api/employees/upsert","category":"Employees","summary":"Upsert Employee (Create or Update)","description":"Matches existing employee by id, employeeId, or email. If found, updates their details; otherwise creates a new profile record.","requestBody":{"employeeId":"1001","firstName":"Rahul","middleName":"Kumar","lastName":"Sharma","profilePhoto":"profile.jpg","dateOfBirth":"1998-05-15","gender":"Male","personalEmail":"rahul@gmail.com","phone":"9876543210","alternatePhone":"9876501234","presentAddress":"Kolkata, West Bengal","permanentAddress":"Howrah, West Bengal","city":"Kolkata","state":"West Bengal","pinCode":"700001","nationality":"Indian","emergencyContactName":"Amit Sharma","emergencyContactNumber":"9876543211","highestQualification":"Bachelor's Degree","maritalStatus":"Single","employeeCode":"EMP001","companyName":"ABC Technologies","department":"IT","designation":"Software Developer","jobRole":"Web Development","employmentType":"Full-Time","dateOfJoining":"2025-04-10","employmentStatus":"Active","reportingManagerId":"1005","workEmail":"rahul@company.com","workPhone":"03312345678","workLocation":"Kolkata Office","workMode":"Hybrid","totalExperience":3.5,"probationStatus":"Completed","workShift":"General","salary":35000,"noticePeriod":"30 Days","accountStatus":"Active","userRole":"Learner","presence":"present","bio":"Full-stack software developer specializing in modern web applications."}},{"method":"GET","path":"/api/employees","category":"Employees","summary":"Get All Employees (All 42 Fields)","description":"Retrieve full list of all employees returning all 42 fields per profile with optional query filters (search keyword, presence status, department, groupId).","queryParams":["search","presence","department","groupId"],"fields":["employeeId","firstName","middleName","lastName","profilePhoto","dateOfBirth","gender","personalEmail","phone","alternatePhone","presentAddress","permanentAddress","city","state","pinCode","nationality","emergencyContactName","emergencyContactNumber","highestQualification","maritalStatus","employeeCode","companyName","department","designation","jobRole","employmentType","dateOfJoining","employmentStatus","reportingManagerId","workEmail","workPhone","workLocation","workMode","totalExperience","probationStatus","workShift","salary","noticePeriod","accountStatus","userRole","createdAt","updatedAt","lastModified"]},{"method":"GET","path":"/api/employees/:id","category":"Employees","summary":"Get Single Employee Profile (All 42 Fields)","description":"Retrieve complete employee profile record returning all 42 standard fields by matching internal UUID (emp_1) or employeeId (1001 / OC-1001).","pathParams":["id"],"fields":["employeeId","firstName","middleName","lastName","profilePhoto","dateOfBirth","gender","personalEmail","phone","alternatePhone","presentAddress","permanentAddress","city","state","pinCode","nationality","emergencyContactName","emergencyContactNumber","highestQualification","maritalStatus","employeeCode","companyName","department","designation","jobRole","employmentType","dateOfJoining","employmentStatus","reportingManagerId","workEmail","workPhone","workLocation","workMode","totalExperience","probationStatus","workShift","salary","noticePeriod","accountStatus","userRole","createdAt","updatedAt","lastModified"]},{"method":"POST","path":"/api/employees/upload-csv","category":"Employees","summary":"Batch CSV Upload","description":"Upload multipart CSV file or raw CSV text to batch upsert all employee rows in a single operation."},{"method":"GET","path":"/api/employees/sample-csv","category":"Employees","summary":"Download Sample CSV Template","description":"Downloads standard UTF-8 CSV template pre-formatted with employee headers."},{"method":"POST","path":"/api/employees/:id/reset-password","category":"Employees","summary":"Reset Employee Password","description":"Generates a secure temporary password and updates the employee record."},{"method":"DELETE","path":"/api/employees/:id","category":"Employees","summary":"Delete Single Employee","description":"Deletes employee and unenrolls them from cohorts and courses."},{"method":"DELETE","path":"/api/employees/bulk/delete-all","category":"Employees","summary":"Delete All Employees (Guarded)","description":"Requires confirmKey \"DELETE ALL\" to wipe all employees after explicit confirmation."},{"method":"GET","path":"/api/courses","category":"Courses","summary":"Get All Courses","description":"Retrieve all learning courses enriched with enrolled employees, cohort groups, and YouTube video lesson links."},{"method":"POST","path":"/api/courses","category":"Courses","summary":"Create Learning Course","description":"Creates a new course module with code, title, duration, instructor, YouTube video URL, and cohort assignments."},{"method":"PUT","path":"/api/courses/:id","category":"Courses","summary":"Update Learning Course","description":"Updates course details, syllabus, YouTube video URL, and cohort assignments."},{"method":"POST","path":"/api/courses/:id/assign","category":"Courses","summary":"Assign Course to Group","description":"Assigns course to an employee cohort group and auto-enrolls all members with 0% initial progress."},{"method":"POST","path":"/api/courses/:id/progress","category":"Courses","summary":"Record Course Progress","description":"Updates employee student progress percentage (0-100%). Automatically marks as completed if 100%."},{"method":"DELETE","path":"/api/courses/:id","category":"Courses","summary":"Delete Course","description":"Permanently removes course and associated employee enrollments."},{"method":"GET","path":"/api/groups","category":"Groups","summary":"Get All Cohort Groups","description":"Retrieve list of employee squads and cohorts enriched with member employee objects and assigned courses."},{"method":"POST","path":"/api/groups","category":"Groups","summary":"Create Cohort Group","description":"Creates new group from employee checklist with signature color theme badge and description."},{"method":"PUT","path":"/api/groups/:id","category":"Groups","summary":"Update Cohort Group","description":"Updates group name, description, color, or member list."},{"method":"DELETE","path":"/api/groups/:id","category":"Groups","summary":"Delete Cohort Group","description":"Unbundles cohort group without deleting employee accounts."},{"method":"GET","path":"/api/auth/present-users","category":"Authentication & Presence","summary":"Get All Present Users","description":"Returns real-time list of all employees currently marked as present or remote."},{"method":"POST","path":"/api/auth/login","category":"Authentication & Presence","summary":"User Login / Switch Session","description":"Authenticates by employee ID or email. Supports autoMarkPresent parameter."},{"method":"POST","path":"/api/auth/clock-in","category":"Authentication & Presence","summary":"Clock In Employee","description":"Marks employee as present in real-time presence tracker."},{"method":"POST","path":"/api/auth/clock-out","category":"Authentication & Presence","summary":"Clock Out Employee","description":"Marks employee as offline."},{"method":"GET","path":"/api/custom-fields","category":"Custom Fields","summary":"Get Custom Field Definitions","description":"Returns list of dynamic employee attributes configured in the system."},{"method":"POST","path":"/api/custom-fields","category":"Custom Fields","summary":"Create Custom Field","description":"Defines a new attribute (type: text, number, date, select, boolean)."},{"method":"DELETE","path":"/api/custom-fields/:id","category":"Custom Fields","summary":"Delete Custom Field","description":"Removes custom attribute definition."},{"method":"GET","path":"/api/stats","category":"Analytics","summary":"Get Dashboard Overview Stats","description":"Returns live employee count, presence rate, course enrollments, cohort counts, and recent activity logs."},{"method":"GET","path":"/odata/v4","category":"OData Protocol","summary":"OData v4 Service Document","description":"Returns standard OData v4 Service Root Document listing available entity sets (Employees, JobDetails, PersonalDetails, CustomFields)."},{"method":"GET","path":"/odata/v4/$metadata","category":"OData Protocol","summary":"OData CSDL Metadata Schema","description":"Returns standard XML CSDL schema defining all 4 entity types (Employee, JobDetail, PersonalDetail, CustomField) with full navigation property bindings."},{"method":"GET","path":"/odata/v4/Employees","category":"OData Protocol","summary":"Query Employees (OData v4)","description":"Query employee entity set using standard OData query options: $select, $filter, $orderby, $top, $skip, $count=true, $search, and $expand (Job, Personal, Custom)."},{"method":"GET","path":"/odata/v4/JobDetails","category":"OData Protocol","summary":"Query JobDetails EntitySet","description":"Query dedicated JobDetails entity set containing job and organization enterprise attributes. Supports $expand=Personal to embed personal profile inline."},{"method":"GET","path":"/odata/v4/JobDetails/:id/Personal","category":"OData Protocol","summary":"Navigate from Job to Personal (OData Navigation)","description":"OData Navigation Property link traversing from an employee's JobDetail entity directly to their PersonalDetail entity. Available as Atom XML by default or JSON."},{"method":"GET","path":"/odata/v4/PersonalDetails","category":"OData Protocol","summary":"Query PersonalDetails EntitySet","description":"Query dedicated PersonalDetails entity set containing personal, demographic, and contact fields. Supports $expand=Custom to embed custom attributes inline."},{"method":"GET","path":"/odata/v4/PersonalDetails/:id/Custom","category":"OData Protocol","summary":"Navigate from Personal to Custom (OData Navigation)","description":"OData Navigation Property link traversing from an employee's PersonalDetail entity to their collection of CustomField attributes. Available as Atom XML feed by default or JSON."},{"method":"GET","path":"/odata/v4/Employees/:id/Job/Personal/Custom","category":"OData Protocol","summary":"Chained Traversal: Job -> Personal -> Custom","description":"Full multi-hop OData navigation property traversal traversing from Job to Personal to Custom fields in a single standard request."},{"method":"GET","path":"/odata/v4/CustomFields","category":"OData Protocol","summary":"Query CustomFields EntitySet","description":"Query dynamic enterprise custom attributes entity set across employees."},{"method":"POST","path":"/odata/v4/Employees","category":"OData Protocol","summary":"Create / Upsert Employee (OData v4)","description":"Creates or upserts an employee entity according to standard OData specification, returning OData context and Location header."},{"method":"POST","path":"/api/employees/bulk-upsert","category":"Employees","summary":"Batch JSON Upsert Employees","description":"Upsert multiple employees simultaneously from a JSON array or { employees: [...] } payload."},{"method":"GET","path":"/api/employees/export-json","category":"Employees","summary":"Export All Employees as JSON","description":"Downloads the entire employee directory formatted in standard JSON containing all 42 fields."}]}