{ "openapi": "3.0.0", "info": { "title": "Employee Engagement Platform API", "description": "API for managing employee engagement, quizzes, challenges, rewards, and more. Supports Super Admin, Admin, and Employee roles.", "contact": { "name": "API Support", "email": "support@employeeengagement.com" }, "version": "1.0.0" }, "servers": [ { "url": "http://localhost:8000/api/v1", "description": "Local development server" } ], "paths": { "/auth/register": { "post": { "tags": [ "Authentication" ], "summary": "Register new user", "description": "Complete API Documentation for Employee Engagement Platform\nMatches database schema with Super Admin, Admin, and Employee roles", "operationId": "1dfc833a5a5356f4e5b1d7ff3ec86923", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@company.com" }, "password": { "type": "string", "format": "password" }, "password_confirmation": { "type": "string" }, "department_id": { "type": "integer" }, "team_id": { "type": "integer" }, "designation": { "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "description": "User registered successfully" }, "422": { "description": "Validation error" } } } }, "/auth/login": { "post": { "tags": [ "Authentication" ], "summary": "User login", "operationId": "26e473ab4dcb30f1d28f9ae272d01e4a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful, returns token" }, "401": { "description": "Invalid credentials" } } } }, "/auth/logout": { "post": { "tags": [ "Authentication" ], "summary": "Logout user", "operationId": "b7d0578dc73b7cc9ca8b29efd6ed6fa0", "responses": { "200": { "description": "Logged out successfully" } }, "security": [ { "sanctum": [] } ] } }, "/auth/profile": { "get": { "tags": [ "Authentication" ], "summary": "Get current user profile", "operationId": "6f38ae6bf2f54065a20a326628114855", "responses": { "200": { "description": "User profile data" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Authentication" ], "summary": "Update current user profile", "operationId": "e68dc2bbc9a1551bde61bf253f0adf31", "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "avatar_url": { "type": "string" }, "designation": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated" } }, "security": [ { "sanctum": [] } ] } }, "/super-admin/admins": { "get": { "tags": [ "Super Admin" ], "summary": "List all admins", "description": "Super Admin only - Get all HR admins and sub admins", "operationId": "6cb71b390f9d79a508347f7c20577e47", "parameters": [ { "name": "role", "in": "query", "description": "Filter by role", "schema": { "type": "string", "enum": [ "super_admin", "hr_admin", "sub_admin" ] } } ], "responses": { "200": { "description": "List of admins" }, "403": { "description": "Forbidden - Super Admin only" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Super Admin" ], "summary": "Create new admin", "description": "Super Admin only - Create HR Admin or Sub Admin", "operationId": "f9226a2d01f5bdcd7fefb4b0404198f7", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id", "role" ], "properties": { "user_id": { "description": "Existing user ID to promote", "type": "integer" }, "role": { "type": "string", "enum": [ "hr_admin", "sub_admin" ] }, "permissions": { "description": "JSON permissions object", "type": "object", "example": { "manage_users": true, "manage_quizzes": true } } }, "type": "object" } } } }, "responses": { "201": { "description": "Admin created" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] } }, "/super-admin/admins/{id}": { "get": { "tags": [ "Super Admin" ], "summary": "Get admin details", "operationId": "290bb1b89d4a28636cc60a4a45bc001e", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Admin details" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Super Admin" ], "summary": "Update admin", "operationId": "361589838600f0c6d0eb099d8a49ae18", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "role": { "type": "string", "enum": [ "hr_admin", "sub_admin" ] }, "permissions": { "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Admin updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Super Admin" ], "summary": "Remove admin role", "operationId": "fe291c07bc3e756d2dd7ee28661cdebc", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Admin role removed" } }, "security": [ { "sanctum": [] } ] } }, "/super-admin/stats": { "get": { "tags": [ "Super Admin" ], "summary": "System statistics", "description": "Overall platform statistics for Super Admin", "operationId": "7bbc652fb33d40e6cb138ea7e6f8fe07", "responses": { "200": { "description": "System stats - users count, points distributed, etc." } }, "security": [ { "sanctum": [] } ] } }, "/users": { "get": { "tags": [ "Users" ], "summary": "Get all users", "description": "Admin only - List all employees", "operationId": "61098434258ea46c4b0e9be72dd81111", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } }, { "name": "search", "in": "query", "description": "Search by name or email", "schema": { "type": "string" } }, { "name": "department_id", "in": "query", "schema": { "type": "integer" } }, { "name": "team_id", "in": "query", "schema": { "type": "integer" } }, { "name": "role", "in": "query", "schema": { "type": "string", "enum": [ "employee", "admin", "super_admin" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive" ] } } ], "responses": { "200": { "description": "Paginated users list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Users" ], "summary": "Create user", "description": "Admin only - Create new employee", "operationId": "cec121d18d8f8a843db80e300d6d8b24", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password" ], "properties": { "name": { "type": "string", "maxLength": 150 }, "email": { "type": "string", "format": "email", "maxLength": 150 }, "password": { "type": "string", "minLength": 8 }, "department_id": { "type": "integer" }, "team_id": { "type": "integer" }, "designation": { "type": "string", "maxLength": 150 }, "avatar_url": { "type": "string" }, "role": { "type": "string", "default": "employee", "enum": [ "employee", "admin" ] }, "status": { "type": "string", "default": "active", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "User created" } }, "security": [ { "sanctum": [] } ] } }, "/users/{id}": { "get": { "tags": [ "Users" ], "summary": "Get user by ID", "operationId": "11e19e6a953af7aa6df7f312546b84b7", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "User details with department, team, points" }, "404": { "description": "User not found" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Users" ], "summary": "Update user", "operationId": "c2c6b4e46dd4f956158e97f1599c008c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "department_id": { "type": "integer" }, "team_id": { "type": "integer" }, "designation": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "User updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Users" ], "summary": "Delete user", "operationId": "2dc2b3731e5e4707f4305505356a11a6", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "User deleted" } }, "security": [ { "sanctum": [] } ] } }, "/users/{id}/points-history": { "get": { "tags": [ "Users" ], "summary": "User points history", "operationId": "cd9779afee878537c013f4c91bd03198", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Points transactions for user" } }, "security": [ { "sanctum": [] } ] } }, "/departments": { "get": { "tags": [ "Departments" ], "summary": "Get all departments", "operationId": "ac1cd34ffa6b03cbd432cdb89296f920", "responses": { "200": { "description": "Departments list with manager info" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Departments" ], "summary": "Create department", "operationId": "d277929c31e16e994400445270ff5e33", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 150 }, "manager_id": { "description": "User ID of department manager", "type": "integer" } }, "type": "object" } } } }, "responses": { "201": { "description": "Department created" } }, "security": [ { "sanctum": [] } ] } }, "/departments/{id}": { "get": { "tags": [ "Departments" ], "summary": "Get department", "operationId": "9f1e109de1d92481d5e654a8d530841f", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Department details with users" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Departments" ], "summary": "Update department", "operationId": "443b1b0b036db9cd2622a17fb6818e23", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "manager_id": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Department updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Departments" ], "summary": "Delete department", "operationId": "374557ec8a4f43b80e49b36621547664", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Department deleted" } }, "security": [ { "sanctum": [] } ] } }, "/teams": { "get": { "tags": [ "Teams" ], "summary": "Get all teams", "operationId": "8e0f83066445fa470c1f407ebb1be136", "parameters": [ { "name": "department_id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Teams list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Teams" ], "summary": "Create team", "operationId": "28b0eafdc0363001475afd841517209a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 150 }, "description": { "type": "string" }, "created_by": { "description": "Creator user ID", "type": "integer" } }, "type": "object" } } } }, "responses": { "201": { "description": "Team created" } }, "security": [ { "sanctum": [] } ] } }, "/teams/{id}": { "get": { "tags": [ "Teams" ], "summary": "Get team", "operationId": "f7b4a2148dca218b6796eb3e6f5b2d90", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Team details with members and total_points" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Teams" ], "summary": "Update team", "operationId": "87ded7a8f75b9a179512a07d5f923025", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Team updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Teams" ], "summary": "Delete team", "operationId": "69d877a13058f586add3d6421d141097", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Team deleted" } }, "security": [ { "sanctum": [] } ] } }, "/teams/{id}/members": { "post": { "tags": [ "Teams" ], "summary": "Add member to team", "operationId": "425cf5ca05da74efebfc08d39f01b00e", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id" ], "properties": { "user_id": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Member added" } }, "security": [ { "sanctum": [] } ] } }, "/quizzes": { "get": { "tags": [ "Quizzes" ], "summary": "Get all quizzes", "operationId": "0b43389399107ba2cf3c47289f3b6901", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "published", "expired" ] } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "difficulty", "in": "query", "schema": { "type": "string", "enum": [ "easy", "medium", "hard" ] } } ], "responses": { "200": { "description": "Quizzes list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Quizzes" ], "summary": "Create quiz", "description": "Admin only", "operationId": "c0edcb5d69390ced3f6231ea8bf04837", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "total_points" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "category": { "type": "string", "maxLength": 150 }, "difficulty": { "type": "string", "default": "easy", "enum": [ "easy", "medium", "hard" ] }, "total_points": { "type": "integer" }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "status": { "type": "string", "default": "draft", "enum": [ "draft", "published" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Quiz created" } }, "security": [ { "sanctum": [] } ] } }, "/quizzes/{id}": { "get": { "tags": [ "Quizzes" ], "summary": "Get quiz with questions", "operationId": "7b93bd6adb89a06627caf9df7640fcc6", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Quiz details with questions" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Quizzes" ], "summary": "Update quiz", "operationId": "7fab89fcb70b929bf9cab86b6763facb", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "expired" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Quiz updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Quizzes" ], "summary": "Delete quiz", "operationId": "0c323352e39fcb5098397a67259703de", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Quiz deleted" } }, "security": [ { "sanctum": [] } ] } }, "/quizzes/{quizId}/questions": { "get": { "tags": [ "Quiz Questions" ], "summary": "Get quiz questions", "operationId": "8eda502031ad41121c0079744498f0c9", "parameters": [ { "name": "quizId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of questions" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Quiz Questions" ], "summary": "Add question to quiz", "operationId": "679d4122562401350756973518912be8", "parameters": [ { "name": "quizId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "question_text", "options", "correct_option", "points" ], "properties": { "question_text": { "type": "string" }, "options": { "type": "array", "items": { "type": "object" } }, "correct_option": { "type": "string", "example": "A" }, "points": { "type": "integer", "default": 10 } }, "type": "object" } } } }, "responses": { "201": { "description": "Question added" } }, "security": [ { "sanctum": [] } ] } }, "/quizzes/{quizId}/questions/{id}": { "put": { "tags": [ "Quiz Questions" ], "summary": "Update question", "operationId": "2414219de2e829f33566daedef6afc92", "parameters": [ { "name": "quizId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "question_text": { "type": "string" }, "options": { "type": "array", "items": { "type": "object" } }, "correct_option": { "type": "string" }, "points": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Question updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Quiz Questions" ], "summary": "Delete question", "operationId": "fd6be78d8d2870dc4446d75c2d692366", "parameters": [ { "name": "quizId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Question deleted" } }, "security": [ { "sanctum": [] } ] } }, "/quiz-attempts": { "get": { "tags": [ "Quiz Attempts" ], "summary": "Get my quiz attempts", "operationId": "00a0999353ea84eeb4e355135749dbae", "responses": { "200": { "description": "User's quiz attempts" } }, "security": [ { "sanctum": [] } ] } }, "/quizzes/{id}/start": { "post": { "tags": [ "Quiz Attempts" ], "summary": "Start quiz attempt", "operationId": "35ca33122d93d19c77683a75d1d5f503", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Quiz started, returns questions" }, "400": { "description": "Already attempted or quiz not available" } }, "security": [ { "sanctum": [] } ] } }, "/quizzes/{id}/submit": { "post": { "tags": [ "Quiz Attempts" ], "summary": "Submit quiz answers", "operationId": "e432e4593cf0a49b2cf7a2899e20df9e", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "answers" ], "properties": { "answers": { "description": "question_id => selected_option", "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Quiz submitted, returns score and points earned" } }, "security": [ { "sanctum": [] } ] } }, "/quiz-attempts/{id}": { "get": { "tags": [ "Quiz Attempts" ], "summary": "Get attempt result", "operationId": "6b1e649ce838ad0d94059f3d7e5f97d0", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Attempt details with score" } }, "security": [ { "sanctum": [] } ] } }, "/challenges": { "get": { "tags": [ "Challenges" ], "summary": "Get all challenges", "operationId": "6df8e27af2caf9797915c810a4a89a42", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive", "expired" ] } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "individual", "team" ] } } ], "responses": { "200": { "description": "Challenges list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Challenges" ], "summary": "Create challenge", "description": "Admin only", "operationId": "bd7ff91fc24ebc79037937c25d3b79f4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "type", "points" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "individual", "team" ] }, "description": { "type": "string" }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "points": { "type": "integer" }, "status": { "type": "string", "default": "active", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Challenge created" } }, "security": [ { "sanctum": [] } ] } }, "/challenges/{id}": { "get": { "tags": [ "Challenges" ], "summary": "Get challenge", "operationId": "9a26145ebec279695fb4db26e5d4b288", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Challenge details" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Challenges" ], "summary": "Update challenge", "operationId": "f00c15493ecad9c017e840ee29837da1", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Challenge updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Challenges" ], "summary": "Delete challenge", "operationId": "8da86973460da6a83a6f52e71f5cc132", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Challenge deleted" } }, "security": [ { "sanctum": [] } ] } }, "/my-challenges": { "get": { "tags": [ "User Challenges" ], "summary": "Get my joined challenges", "operationId": "3253cd536c2e6f8c6170ecfa4985012d", "responses": { "200": { "description": "User's challenges with progress" } }, "security": [ { "sanctum": [] } ] } }, "/challenges/{id}/join": { "post": { "tags": [ "User Challenges" ], "summary": "Join challenge", "operationId": "92886be1bae979eb4b9a19b0c780cc8a", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "team_id": { "description": "Required for team challenges", "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Joined challenge" } }, "security": [ { "sanctum": [] } ] } }, "/challenges/{id}/progress": { "put": { "tags": [ "User Challenges" ], "summary": "Update challenge progress", "operationId": "ce164070a8402b64c943c3c74c5aec5b", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "progress": { "type": "integer", "maximum": 100, "minimum": 0 } }, "type": "object" } } } }, "responses": { "200": { "description": "Progress updated" } }, "security": [ { "sanctum": [] } ] } }, "/challenges/{id}/complete": { "post": { "tags": [ "User Challenges" ], "summary": "Mark challenge complete", "operationId": "f85fdaa812b0c60c4e92c8fc1575ea8d", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Challenge completed, points awarded" } }, "security": [ { "sanctum": [] } ] } }, "/rewards": { "get": { "tags": [ "Rewards" ], "summary": "Get rewards catalog", "operationId": "f96b676a5b212ae29e22cd225d77c747", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "physical", "digital" ] } } ], "responses": { "200": { "description": "Rewards list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Rewards" ], "summary": "Create reward", "description": "Admin only", "operationId": "43d5d85e7722ed97c1436a6fbbaf2f98", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "points_cost" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "points_cost": { "type": "integer" }, "stock": { "description": "-1 for unlimited", "type": "integer", "default": 0 }, "type": { "type": "string", "default": "physical", "enum": [ "physical", "digital" ] }, "image_url": { "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "description": "Reward created" } }, "security": [ { "sanctum": [] } ] } }, "/rewards/{id}": { "get": { "tags": [ "Rewards" ], "summary": "Get reward", "operationId": "6ec3aae08848be8693d66e870a4dcb1a", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Reward details" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Rewards" ], "summary": "Update reward", "operationId": "1494ae07d36204a7471b4ea14dadfe26", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "points_cost": { "type": "integer" }, "stock": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Reward updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Rewards" ], "summary": "Delete reward", "operationId": "7b2c2c7bdf88923ce2959646d50f9fa6", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Reward deleted" } }, "security": [ { "sanctum": [] } ] } }, "/my-rewards": { "get": { "tags": [ "User Rewards" ], "summary": "Get my redeemed rewards", "operationId": "6e5738e7e88d748f87654113c532cb22", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "delivered", "rejected" ] } } ], "responses": { "200": { "description": "User's redemptions" } }, "security": [ { "sanctum": [] } ] } }, "/rewards/{id}/redeem": { "post": { "tags": [ "User Rewards" ], "summary": "Redeem reward", "operationId": "7551322b60dd9cc507b0be747d453fe6", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Reward redeemed" }, "400": { "description": "Insufficient points or out of stock" } }, "security": [ { "sanctum": [] } ] } }, "/admin/redemptions": { "get": { "tags": [ "User Rewards" ], "summary": "Get all redemptions", "description": "Admin only", "operationId": "4dc3f53845675419c3f0c05c86ba365b", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "delivered", "rejected" ] } } ], "responses": { "200": { "description": "All redemptions" } }, "security": [ { "sanctum": [] } ] } }, "/admin/redemptions/{id}": { "put": { "tags": [ "User Rewards" ], "summary": "Update redemption status", "description": "Admin only", "operationId": "c8fdf09b8ace81b114dc782c7969f5e0", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "approved", "delivered", "rejected" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Redemption updated" } }, "security": [ { "sanctum": [] } ] } }, "/achievements": { "get": { "tags": [ "Achievements" ], "summary": "Get all achievements/badges", "operationId": "d597d92aad64345ae2ff499785d42328", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "quiz", "challenge", "general" ] } } ], "responses": { "200": { "description": "Achievements list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Achievements" ], "summary": "Create achievement", "description": "Admin only", "operationId": "81ea8e0f6c5d9745e2812207582bf31e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 150 }, "description": { "type": "string" }, "points": { "type": "integer", "default": 0 }, "badge_icon": { "type": "string" }, "type": { "type": "string", "default": "general", "enum": [ "quiz", "challenge", "general" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Achievement created" } }, "security": [ { "sanctum": [] } ] } }, "/achievements/{id}": { "get": { "tags": [ "Achievements" ], "summary": "Get achievement", "operationId": "1407f83d305eb3c013d4122f51d1d983", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Achievement details" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Achievements" ], "summary": "Update achievement", "operationId": "b0a319ccbf9e59a483e1b7da3b8ba614", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "points": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Achievement updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Achievements" ], "summary": "Delete achievement", "operationId": "68fb2c8628b1d721a926f1fc79ebe1a5", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Achievement deleted" } }, "security": [ { "sanctum": [] } ] } }, "/my-achievements": { "get": { "tags": [ "User Achievements" ], "summary": "Get my earned achievements", "operationId": "eb69901dfdd5dfcb3d0029f45357ef41", "responses": { "200": { "description": "User's achievements with earned_at" } }, "security": [ { "sanctum": [] } ] } }, "/admin/award-achievement": { "post": { "tags": [ "User Achievements" ], "summary": "Award achievement to user", "description": "Admin only", "operationId": "b4aeedb7308db9544980c8b908be112c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id", "achievement_id" ], "properties": { "user_id": { "type": "integer" }, "achievement_id": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Achievement awarded" } }, "security": [ { "sanctum": [] } ] } }, "/leaderboard": { "get": { "tags": [ "Leaderboard" ], "summary": "Get leaderboard", "operationId": "23bdf60932942fa2c8107ddc04eb4fba", "parameters": [ { "name": "period", "in": "query", "description": "weekly or monthly", "schema": { "type": "string", "enum": [ "weekly", "monthly", "all_time" ] } }, { "name": "week_no", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "department_id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Leaderboard with rank, user, points" } }, "security": [ { "sanctum": [] } ] } }, "/leaderboard/teams": { "get": { "tags": [ "Leaderboard" ], "summary": "Team leaderboard", "operationId": "5e2dd89a0bcc632ac6744cc3f2e7f914", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Teams ranked by total_points" } }, "security": [ { "sanctum": [] } ] } }, "/leaderboard/departments": { "get": { "tags": [ "Leaderboard" ], "summary": "Department leaderboard", "operationId": "e37f017a55d57423e5c5a9167fccb8c9", "responses": { "200": { "description": "Departments ranked" } }, "security": [ { "sanctum": [] } ] } }, "/leaderboard/my-rank": { "get": { "tags": [ "Leaderboard" ], "summary": "Get my rank", "operationId": "7f04b5f3bb4767561e51eb859eed404e", "responses": { "200": { "description": "Current user's rank and position" } }, "security": [ { "sanctum": [] } ] } }, "/points/history": { "get": { "tags": [ "Points" ], "summary": "Get my points history", "operationId": "aed2d689d586b641c2213b2bac3e2960", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "source_type", "in": "query", "schema": { "type": "string", "enum": [ "quiz", "challenge", "attendance", "redeem", "referral", "admin_adjust" ] } } ], "responses": { "200": { "description": "Points transactions with source details" } }, "security": [ { "sanctum": [] } ] } }, "/points/balance": { "get": { "tags": [ "Points" ], "summary": "Get my points balance", "operationId": "14e4debb87137cf31701b2060208cf66", "responses": { "200": { "description": "Current points balance" } }, "security": [ { "sanctum": [] } ] } }, "/admin/points/award": { "post": { "tags": [ "Points" ], "summary": "Award points to user", "description": "Admin only - manual points adjustment", "operationId": "569c2d41cd98dd912068be0dc4ec4150", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id", "change", "notes" ], "properties": { "user_id": { "type": "integer" }, "change": { "description": "Positive to add, negative to deduct", "type": "integer" }, "notes": { "type": "string", "maxLength": 512 } }, "type": "object" } } } }, "responses": { "200": { "description": "Points awarded/deducted" } }, "security": [ { "sanctum": [] } ] } }, "/attendance/checkin": { "post": { "tags": [ "Attendance" ], "summary": "Daily check-in", "operationId": "fcf713103a14f1461edc72dd14f61986", "responses": { "200": { "description": "Check-in successful, returns streak_count and points_awarded" }, "400": { "description": "Already checked in today" } }, "security": [ { "sanctum": [] } ] } }, "/attendance/history": { "get": { "tags": [ "Attendance" ], "summary": "Get attendance history", "operationId": "ee871aaee12c064f6dc96f2cde221a8e", "parameters": [ { "name": "month", "in": "query", "schema": { "type": "integer" } }, { "name": "year", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Attendance logs with dates and streaks" } }, "security": [ { "sanctum": [] } ] } }, "/attendance/streak": { "get": { "tags": [ "Attendance" ], "summary": "Get current streak", "operationId": "54c57b41a28fb7acfa9aeca42109d516", "responses": { "200": { "description": "Current streak count" } }, "security": [ { "sanctum": [] } ] } }, "/certifications": { "get": { "tags": [ "Certifications" ], "summary": "Get my certifications", "operationId": "ea52d73d7bae9df17876894b58fd7986", "responses": { "200": { "description": "User's certifications" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Certifications" ], "summary": "Add certification", "operationId": "413ba1e54ab25475972445c6e1a09565", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "issued_by": { "type": "string", "maxLength": 255 }, "completion_date": { "type": "string", "format": "date" }, "visibility": { "type": "string", "default": "org", "enum": [ "org", "team", "management" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Certification added" } }, "security": [ { "sanctum": [] } ] } }, "/certifications/{id}": { "get": { "tags": [ "Certifications" ], "summary": "Get certification", "operationId": "c2c1e823199632744763ca66a07ec152", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Certification details" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Certifications" ], "summary": "Update certification", "operationId": "bc80e93577f0f43c112a7ffe1d68e895", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "visibility": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Certification updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Certifications" ], "summary": "Delete certification", "operationId": "88b5d66c3922f1089d9aa1394ab90c9c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Certification deleted" } }, "security": [ { "sanctum": [] } ] } }, "/project-referrals": { "get": { "tags": [ "Project Referrals" ], "summary": "Get my project referrals", "operationId": "5ff9de57b2e10c53d456ac796d966e89", "responses": { "200": { "description": "User's referrals" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Project Referrals" ], "summary": "Submit project referral", "operationId": "e75d8d86a234db34793737dd057747a9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "project_name", "contact_name" ], "properties": { "project_name": { "type": "string", "maxLength": 255 }, "contact_name": { "type": "string", "maxLength": 255 }, "contact_info": { "description": "Contact details JSON", "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Referral submitted" } }, "security": [ { "sanctum": [] } ] } }, "/project-referrals/{id}": { "get": { "tags": [ "Project Referrals" ], "summary": "Get referral", "operationId": "69b52375e18a6068c56aa56c9561298b", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Referral details" } }, "security": [ { "sanctum": [] } ] } }, "/admin/project-referrals": { "get": { "tags": [ "Project Referrals" ], "summary": "Get all referrals", "description": "Admin only", "operationId": "76f20c2c668aa5e71d640aa1a5187767", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "completed", "rejected" ] } } ], "responses": { "200": { "description": "All referrals" } }, "security": [ { "sanctum": [] } ] } }, "/admin/project-referrals/{id}": { "put": { "tags": [ "Project Referrals" ], "summary": "Update referral status", "description": "Admin only", "operationId": "0d40b912f70150b9a44c46e07d40d5d1", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "approved", "completed", "rejected" ] }, "reward_points": { "description": "Points to award if approved", "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Referral updated" } }, "security": [ { "sanctum": [] } ] } }, "/reports": { "get": { "tags": [ "Reports" ], "summary": "Get saved reports", "description": "Admin only", "operationId": "b8f19c2d94ee0305696bcff03a8c8297", "parameters": [ { "name": "report_type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Saved reports list" } }, "security": [ { "sanctum": [] } ] } }, "/reports/generate": { "post": { "tags": [ "Reports" ], "summary": "Generate report", "description": "Admin only", "operationId": "8a00f8d4dae3e994f9754d7ccbba8be6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "report_type" ], "properties": { "report_type": { "type": "string", "enum": [ "engagement", "points", "users", "quizzes", "challenges" ] }, "parameters": { "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Report generated" } }, "security": [ { "sanctum": [] } ] } }, "/reports/{id}": { "get": { "tags": [ "Reports" ], "summary": "Get report", "operationId": "2fdc0f507bc1c43ffa5e1fc1592c6534", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Report data" } }, "security": [ { "sanctum": [] } ] } }, "/reports/engagement": { "get": { "tags": [ "Reports" ], "summary": "Engagement report", "operationId": "ebed2183f5197d2e936fc00822845bf7", "parameters": [ { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Engagement statistics" } }, "security": [ { "sanctum": [] } ] } }, "/reports/points-summary": { "get": { "tags": [ "Reports" ], "summary": "Points summary report", "operationId": "78f93991d903d6fb152cd3ca77018a16", "responses": { "200": { "description": "Points distribution report" } }, "security": [ { "sanctum": [] } ] } }, "/dashboard": { "get": { "tags": [ "Dashboard" ], "summary": "User dashboard", "operationId": "7e9aed6c6ba9fd14c04c82a1f5587718", "responses": { "200": { "description": "User stats - points, rank, recent activities, streak" } }, "security": [ { "sanctum": [] } ] } }, "/dashboard/admin": { "get": { "tags": [ "Dashboard" ], "summary": "Admin dashboard", "description": "Admin only", "operationId": "cab0e0cc348f0e22bb5520b031b17163", "responses": { "200": { "description": "Admin stats - total users, active quizzes, points distributed" } }, "security": [ { "sanctum": [] } ] } }, "/dashboard/super-admin": { "get": { "tags": [ "Dashboard" ], "summary": "Super Admin dashboard", "description": "Super Admin only", "operationId": "b09dc97464dbd423caf88b019baab420", "responses": { "200": { "description": "Full platform statistics" } }, "security": [ { "sanctum": [] } ] } }, "/health": { "get": { "tags": [ "System" ], "summary": "API Health check", "operationId": "0fa51370b87c40ebd9d8cb7f9ab38497", "responses": { "200": { "description": "API is healthy" } } } } }, "components": { "schemas": { "User": { "title": "User", "description": "User model", "properties": { "id": { "type": "integer", "example": 1 }, "employee_id": { "type": "string", "example": "EMP001", "nullable": true }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "department_id": { "type": "integer", "example": 1, "nullable": true }, "team_id": { "type": "integer", "example": 1, "nullable": true }, "designation": { "type": "string", "example": "Senior Developer", "nullable": true }, "avatar_url": { "type": "string", "example": "https://example.com/avatar.jpg", "nullable": true }, "total_points": { "type": "integer", "example": 100 }, "role": { "type": "string", "enum": [ "employee", "admin", "super_admin" ], "example": "employee" }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended" ], "example": "active" }, "last_login": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" } }, "type": "object" } }, "securitySchemes": { "sanctum": { "type": "http", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Authentication", "description": "Login, Register, Logout" }, { "name": "Super Admin", "description": "Super Admin - Manage Admins & System" }, { "name": "Users", "description": "User/Employee management" }, { "name": "Departments", "description": "Department management" }, { "name": "Teams", "description": "Team management" }, { "name": "Quizzes", "description": "Quiz management" }, { "name": "Quiz Questions", "description": "Quiz questions management" }, { "name": "Quiz Attempts", "description": "Quiz attempts and submissions" }, { "name": "Challenges", "description": "Challenge management" }, { "name": "User Challenges", "description": "Challenge participation" }, { "name": "Rewards", "description": "Rewards catalog" }, { "name": "User Rewards", "description": "Reward redemptions" }, { "name": "Achievements", "description": "Badges and achievements" }, { "name": "User Achievements", "description": "User earned achievements" }, { "name": "Leaderboard", "description": "Rankings and leaderboards" }, { "name": "Points", "description": "Points transactions" }, { "name": "Attendance", "description": "Daily check-in and streaks" }, { "name": "Certifications", "description": "User certifications" }, { "name": "Project Referrals", "description": "Project referral submissions" }, { "name": "Reports", "description": "Admin reports" }, { "name": "Dashboard", "description": "Dashboard statistics" }, { "name": "System", "description": "System" } ] }