{ "openapi": "3.0.0", "info": { "title": "Pathshalaa API", "description": "Comprehensive API documentation for Pathshalaa - An Educational Platform for Test Series, Student Management, and Tutor Dashboard", "contact": { "name": "Pathshalaa Support", "email": "support@pathshalaa.in" }, "license": { "name": "Proprietary", "url": "https://pathshalaa.in" }, "version": "2.0.0" }, "paths": { "/api/guest/guest_account_create": { "post": { "tags": [ "Guest user" ], "summary": "Generate a guest token", "description": "Creates a unique guest user and generates an authentication token for that user.", "operationId": "6074aa27acc1196f0f62f39db9f59baa", "responses": { "201": { "description": "Guest token generated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Guest token generated successfully." }, "token": { "type": "string", "example": "your_generated_token_here" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Invalid request or failure in generating token", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while generating the token." } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/user/token_verify": { "get": { "tags": [ "Authentication" ], "summary": "Check if user token is valid", "description": "This endpoint checks if the authenticated user's token is valid, whether the user's profile is active, and whether the user has the appropriate role.", "operationId": "CheckUserValidToken", "responses": { "200": { "description": "Valid user with active profile and correct role.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "User exists and is valid." }, "error": { "type": "string", "example": null } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized or inactive user.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" }, "error": { "type": "string", "example": null } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error occurred.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/send-test-email/{email}": { "get": { "tags": [ "Utility" ], "summary": "Send test email", "operationId": "8fe0cb009b4ea35605bedd34cfa2e20e", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Email sent successfully" }, "400": { "description": "Invalid email format" } } } }, "/api/teacher/test-series/auto-generate": { "post": { "tags": [ "Teacher - Auto Generate Test Series" ], "summary": "Auto-generate test series with AI questions", "operationId": "9735c3d3a00eae7954a93a8ae61201cb", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "test_series_name", "class_id", "subject_ids", "topic_ids", "question_count", "per_question_marks", "total_time" ], "properties": { "test_series_name": { "type": "string", "example": "Math Quiz 2024" }, "class_id": { "type": "integer", "example": 75 }, "subject_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 82 ] }, "topic_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 1857, 1858 ] }, "question_count": { "type": "integer", "example": 20 }, "per_question_marks": { "type": "integer", "example": 1 }, "total_time": { "type": "integer", "example": 30 }, "use_ai_generation": { "type": "boolean", "example": true }, "consent_given": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Test series created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series created successfully" }, "data": { "properties": { "test_series_id": { "type": "integer", "example": 567 }, "test_series_name": { "type": "string", "example": "Math Quiz 2024" }, "total_questions": { "type": "integer", "example": 20 }, "from_database": { "type": "integer", "example": 15 }, "from_ai": { "type": "integer", "example": 5 }, "coins_used": { "type": "integer", "example": 25 }, "remaining_balance": { "type": "integer", "example": 475 } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation or business logic error" }, "403": { "description": "Unauthorized - Only teachers allowed" }, "422": { "description": "Validation failed" }, "500": { "description": "Server error with automatic refund" } }, "security": [ { "sanctum": [] } ] } }, "/api/test-series/create": { "post": { "tags": [ "Teacher - Test Series" ], "summary": "Create a test series and assign to a batch", "description": "Create a new test series with configuration and automatically assign it to a batch/group. Students in the batch will be enrolled automatically.", "operationId": "createTestSeries", "requestBody": { "description": "Test series information", "required": true, "content": { "application/json": { "schema": { "required": [ "name", "total_time", "per_ques_mark", "max_questions", "groupId", "start_date", "end_date" ], "properties": { "name": { "description": "Test series name (required, max 255 characters)", "type": "string", "maxLength": 255, "example": "Mathematics Final Test" }, "description": { "description": "Optional description", "type": "string", "example": "Comprehensive test covering all topics" }, "instructions": { "description": "Optional instructions for students", "type": "string", "example": "Read all questions carefully" }, "total_time": { "description": "Total time in minutes (required)", "type": "integer", "example": 60 }, "per_ques_mark": { "description": "Marks per question (required)", "type": "number", "format": "float", "example": 1 }, "max_questions": { "description": "Maximum number of questions (required)", "type": "integer", "example": 50 }, "negative_marks": { "description": "Negative marks per wrong answer (optional, default 0)", "type": "number", "format": "float", "example": 0.25 }, "attempt_per_stud": { "description": "Number of attempts allowed per student (optional, default 1)", "type": "integer", "example": 3 }, "type": { "description": "Type of test series (optional, default 'testseries')", "type": "string", "example": "testseries" }, "groupId": { "description": "Group/Batch ID to assign the test series to (required)", "type": "integer", "example": 10 }, "start_date": { "description": "Start date and time for the test series", "type": "string", "format": "date-time", "example": "2026-01-20 09:00:00" }, "end_date": { "description": "End date and time for the test series", "type": "string", "format": "date-time", "example": "2026-01-25 18:00:00" }, "test_series_type": { "description": "Type of test series: objective (MCQ), subjective (written answers), or integer (numeric answers). Defaults to 'objective' if not provided.", "type": "string", "enum": [ "objective", "subjective", "integer" ], "example": "objective" } }, "type": "object" } } } }, "responses": { "200": { "description": "Test series created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "test_id": { "description": "ID of the newly created test series", "type": "integer", "example": 123 }, "name": { "description": "Name of the test series", "type": "string", "example": "Mathematics Final Test" }, "has_sections": { "description": "Whether the test has sections", "type": "boolean", "example": false }, "message": { "description": "Success message", "type": "string", "example": "Test series created successfully." } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "properties": { "name": { "type": "array", "items": { "type": "string", "example": "The name field is required." } }, "total_time": { "type": "array", "items": { "type": "string", "example": "The total time field is required." } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to create test series" }, "error": { "description": "Error details", "type": "string", "example": "Database connection error" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/section-test-series/update/{id}": { "put": { "tags": [ "Tutor - Test Series" ], "summary": "Update Test Series", "description": "Update an existing test series", "operationId": "5f5097dfe4f1d2f56e21e1391a95623e", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "total_time", "per_ques_mark", "max_questions", "groupId", "start_date", "end_date" ], "properties": { "name": { "type": "string", "example": "Physics Mid-Term Test" }, "description": { "type": "string", "example": "Test series for mid-term evaluation" }, "instructions": { "type": "string", "example": "All questions are compulsory" }, "total_time": { "type": "integer", "example": 60 }, "per_ques_mark": { "type": "number", "format": "float", "example": 2 }, "max_questions": { "type": "integer", "example": 30 }, "negative_marks": { "type": "number", "format": "float", "example": 0.5 }, "attempt_per_stud": { "type": "integer", "example": 1 }, "type": { "type": "string", "example": "testseries" }, "test_series_type": { "type": "string", "enum": [ "objective", "subjective", "integer" ], "example": "objective" }, "groupId": { "type": "integer", "example": 5 }, "start_date": { "type": "string", "format": "date", "example": "2023-10-01" }, "end_date": { "type": "string", "format": "date", "example": "2023-10-15" } }, "type": "object" } } } }, "responses": { "200": { "description": "Test series updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series updated successfully." }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series not found or unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/create-basic": { "post": { "tags": [ "Teacher - Test Series" ], "summary": "Create a basic test series", "description": "Create a new basic test series with fundamental configuration. Only teachers (role_id 3) or schools (role_id 5) can create test series.", "operationId": "createBasicTestSeries", "requestBody": { "description": "Test series basic information", "required": true, "content": { "application/json": { "schema": { "required": [ "name", "instructions", "total_time", "max_questions", "negative_marks", "attempt_per_stud" ], "properties": { "name": { "description": "Test series name (3-255 characters)", "type": "string", "maxLength": 255, "minLength": 3, "example": "Mathematics Final Test" }, "description": { "description": "Optional description (max 1000 characters)", "type": "string", "maxLength": 1000, "example": "Comprehensive test covering all topics" }, "instructions": { "description": "Instructions for students (max 2000 characters)", "type": "string", "maxLength": 2000, "example": "Read all questions carefully. No negative marking for unattempted questions." }, "total_time": { "description": "Total time in minutes (1-600 minutes, max 10 hours)", "type": "integer", "maximum": 600, "minimum": 1, "example": 60 }, "max_questions": { "description": "Maximum number of questions (1-500)", "type": "integer", "maximum": 500, "minimum": 1, "example": 50 }, "negative_marks": { "description": "Negative marks per wrong answer (0-10)", "type": "number", "format": "float", "maximum": 10, "minimum": 0, "example": 0.25 }, "attempt_per_stud": { "description": "Number of attempts allowed per student (1-10)", "type": "integer", "maximum": 10, "minimum": 1, "example": 3 }, "groupId": { "description": "Optional group/batch ID to assign the test series to", "type": "integer", "example": 5 }, "start_date": { "description": "Start date and time for the test series in this batch", "type": "string", "format": "date-time", "example": "2026-01-20 09:00:00" }, "end_date": { "description": "End date and time for the test series in this batch", "type": "string", "format": "date-time", "example": "2026-01-25 18:00:00" }, "test_series_type": { "description": "Type of test series: objective (MCQ), subjective (written answers), or integer (numeric answers). Defaults to 'objective' if not provided.", "type": "string", "enum": [ "objective", "subjective", "integer" ], "example": "objective" } }, "type": "object" } } } }, "responses": { "201": { "description": "Test series created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series created successfully" }, "data": { "properties": { "id": { "description": "ID of the newly created test series", "type": "integer", "example": 123 } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized - Only teachers can create test series", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized. Only teachers can create test series." } }, "type": "object" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "properties": { "name": { "type": "array", "items": { "type": "string", "example": "Test series name is required." } }, "total_time": { "type": "array", "items": { "type": "string", "example": "Total time must be at least 1 minute." } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to create test series" }, "error": { "description": "Only present when app.debug is enabled", "type": "string", "example": "Database connection error" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{testseries}/publish": { "post": { "tags": [ "Teacher - Test Series" ], "summary": "Publish or unpublish a test series", "description": "Update the publish status of a test series. Only the owner can update the status.", "operationId": "testSeriesPublish", "parameters": [ { "name": "testseries", "in": "path", "description": "Test series ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "description": "Publish status", "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "description": "True to publish, false to unpublish", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Publish status updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series fetched successfully" }, "data": { "properties": { "is_published": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Test series not found or you do not have permission to access it." } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to fetch test series publish status" }, "error": { "type": "string", "nullable": true } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/teacher/categories/topics": { "post": { "tags": [ "Teacher" ], "summary": "Get topics for selected subjects with question counts", "description": "Fetches all topics for the provided subject IDs, grouped by subject with question counts", "operationId": "3a520b723d1318ee36f1763e041bcfc4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "subject_ids" ], "properties": { "subject_ids": { "description": "Array of subject IDs", "type": "array", "items": { "type": "integer" }, "example": [ 82, 113 ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Successfully retrieved topics", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "subject_id": { "type": "integer", "example": 82 }, "subject_name": { "type": "string", "example": "Mathematics" }, "topic_count": { "type": "integer", "example": 5 }, "total_questions": { "type": "integer", "example": 45 }, "topics": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 201 }, "name": { "type": "string", "example": "Algebra" }, "parent_category_id": { "type": "integer", "example": 82 }, "parent_category_name": { "type": "string", "example": "Mathematics" }, "question_count": { "type": "integer", "example": 15 }, "has_sufficient_questions": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000000Z" } }, "type": "object" } } }, "type": "object" } }, "summary": { "properties": { "total_subjects": { "type": "integer", "example": 2 }, "total_topics": { "type": "integer", "example": 10 }, "total_questions": { "type": "integer", "example": 95 }, "topics_with_insufficient_questions": { "type": "integer", "example": 2 }, "minimum_questions_threshold": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Validation error" }, "details": { "type": "object" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Access denied. Only teachers can access this endpoint" } }, "type": "object" } } } }, "404": { "description": "User or subjects not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "User not found" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "An error occurred while fetching topics" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/teacher/categories/topics/{subject_id}": { "get": { "tags": [ "Teacher" ], "summary": "Get topics for a single subject (convenience endpoint)", "description": "Fetches all topics for a specific subject ID with question counts", "operationId": "a4ec7d475c8827cc2f47f6be8a88c03a", "parameters": [ { "name": "subject_id", "in": "path", "description": "ID of the subject", "required": true, "schema": { "type": "integer", "example": 82 } } ], "responses": { "200": { "description": "Successfully retrieved topics for the subject", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "subject_id": { "type": "integer", "example": 82 }, "subject_name": { "type": "string", "example": "Mathematics" }, "topic_count": { "type": "integer", "example": 5 }, "total_questions": { "type": "integer", "example": 45 }, "topics": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "summary": { "type": "object" } }, "type": "object" } } } }, "403": { "description": "Access denied" }, "404": { "description": "Subject not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/login": { "post": { "tags": [ "Tutor" ], "summary": "Login with mobile number or email and password", "operationId": "3926260a9d4a300beaa0088016076bf5", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email_or_mobile", "password", "device_token_id" ], "properties": { "email_or_mobile": { "type": "string", "example": "tutor@example.com or 1234554321" }, "password": { "type": "string", "example": "123456" }, "device_token_id": { "type": "string", "example": "your_device_token_here" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "token": { "type": "string", "example": "your_generated_token_here" }, "message": { "type": "string", "example": "Login successful" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid credentials" } }, "type": "object" } } } }, "500": { "description": "Internal server error" } } } }, "/api/tutor/login-as-school-list": { "get": { "tags": [ "Tutor" ], "summary": "Get schools associated with the tutor", "description": "Fetches the list of schools where the tutor is enrolled, marks the selected school (based on tutor_type), and includes a static Freelancer option.", "operationId": "4e35734d3229d3faa764e2729f4a780f", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "schools": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 12 }, "name": { "type": "string", "example": "ABC Public School" }, "is_true": { "type": "boolean", "example": true } }, "type": "object" } }, "count": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized Access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve school list" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/login-as-school-update": { "post": { "tags": [ "Tutor" ], "summary": "Update tutor login as selected school or freelancer", "description": "Allows a tutor to switch context to a school they are enrolled in, or to freelancer mode (login_id: '0').", "operationId": "302e93c823e2db61aa42553556cb770b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "login_id" ], "properties": { "login_id": { "description": "School ID to login as (string). Use '0' for freelancer.", "type": "string", "example": "12" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful update", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Tutor Login as ABC Public School Successfully" }, "school_name": { "type": "string", "example": "ABC Public School" }, "school_id": { "type": "string", "example": "12" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized or invalid school selection", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized school selection" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred: Something went wrong." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/register": { "post": { "tags": [ "Tutor" ], "summary": "Register a new tutor", "description": "Registers a new tutor or updates an existing unverified tutor and sends an OTP for verification.", "operationId": "registerTutor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "phone", "password" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "johndoe@example.com" }, "phone": { "type": "string", "example": "9876543210" }, "password": { "type": "string", "format": "password", "example": "secret123" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP has been sent to your registered mobile number.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "OTP has been sent to your registered mobile number." }, "phone": { "type": "string", "example": "9876543210" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The email field is required." } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Mobile number or email already exists", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Mobile number already exists" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred" }, "error": { "type": "string", "example": "SQLSTATE[23000]: Integrity constraint violation..." } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/tutor/verify-otp": { "post": { "tags": [ "Tutor" ], "summary": "Verify tutor OTP", "description": "Verifies the OTP for a tutor's phone number. If successful, marks the mobile as verified and returns an authentication token.", "operationId": "verifyTutorOtp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "phone", "otp" ], "properties": { "phone": { "type": "string", "example": "9876543210" }, "otp": { "type": "string", "example": "123456" }, "device_token_id": { "type": "string", "example": "abcd1234efgh5678", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP verified successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "OTP verified successfully." }, "token": { "type": "string", "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1..." }, "tutor_type": { "type": "string", "example": "Freelancer" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The otp field is required." } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Invalid or expired OTP", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Invalid or expired OTP." } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "User not found." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred." }, "error": { "type": "string", "example": "SQLSTATE[23000]: Integrity constraint violation..." } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/tutor/change-password": { "post": { "tags": [ "Tutor" ], "summary": "Change user password", "operationId": "498fb39fe9bdc5a8a76908d3847a1e43", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "new_password", "new_password_confirmation" ], "properties": { "new_password": { "type": "string", "example": "newpassword123" }, "new_password_confirmation": { "type": "string", "example": "newpassword123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password changed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Password changed successfully" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The new password and confirmation password must match." } }, "type": "object" } } } }, "401": { "description": "Unauthorized (if the user is not authenticated)" } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/update-profile-detail": { "post": { "tags": [ "Tutor" ], "summary": "Update Tutor Profile Details", "description": "Allows an authenticated tutor to update their profile details.", "operationId": "UpdateTutorDetails", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255, "example": "John Doe" }, "father_name": { "type": "string", "maxLength": 255, "example": "Robert Doe" }, "mother_name": { "type": "string", "maxLength": 255, "example": "Jane Doe" }, "qualification": { "type": "string", "maxLength": 255, "example": "M.Sc in Mathematics" }, "experience": { "type": "string", "maxLength": 255, "example": "5 years" }, "address": { "type": "string", "maxLength": 500, "example": "123 Street, City, Country" }, "profile_description": { "type": "string", "maxLength": 500, "example": "Experienced tutor specializing in Mathematics." } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Your Profile details updated successfully." } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The name field is required." } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "User not authenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "User not authenticated." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while updating user details." }, "error": { "type": "string", "example": "SQLSTATE[23000]: Integrity constraint violation..." } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/redeemed-request-history": { "get": { "tags": [ "Tutor" ], "summary": "Get redeemed wallet request history for tutor", "description": "Returns the list of redeemed wallet history entries and current wallet balance for the authenticated tutor.", "operationId": "getRedeemedWalletRequestHistory", "responses": { "200": { "description": "Redeemed wallet history fetched successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "wallet_balance": { "type": "number", "format": "float", "example": 1200.5 }, "wallet_history": { "properties": { "message": { "type": "string", "example": "Redeemed wallet history fetched" }, "wallet_history_list": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 5 }, "type": { "type": "string", "example": "requestearndebit" }, "amount": { "type": "number", "format": "float", "example": 500 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-08-20T10:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-08-20T10:30:00Z" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected error occurred", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Some internal error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/add-redeemed-request": { "post": { "tags": [ "Tutor" ], "summary": "Submit a wallet debit request (Redeemed Coin) for tutors", "description": "Allows authenticated tutors to submit a redeem (debit) request from their wallet balance. Minimum amount must be 500.", "operationId": "submitWalletDebitRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount" ], "properties": { "amount": { "type": "number", "format": "float", "example": 750 } }, "type": "object" } } } }, "responses": { "200": { "description": "Debit request submitted successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Debit request for Redeemed Coin submitted successfully" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation failed or amount exceeds balance", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Amount exceeds wallet balance" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Error message details" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/get-bank-detail": { "get": { "tags": [ "Tutor" ], "summary": "Get bank details of authenticated tutor", "description": "Fetches the active bank details of the logged-in tutor.", "operationId": "getTutorBankDetails", "responses": { "200": { "description": "Bank details fetched successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Bank details fetched successfully" }, "bank_details": { "type": "array", "items": { "properties": { "user_id": { "type": "integer", "example": 12 }, "name": { "type": "string", "example": "Rohit Kumar" }, "account_number": { "type": "string", "example": "1234567890" }, "bank_name": { "type": "string", "example": "State Bank of India" }, "bank_address": { "type": "string", "example": "MG Road, Delhi" }, "ifsc_code": { "type": "string", "example": "SBIN0001234" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Error message here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/add-bank-detail": { "post": { "tags": [ "Tutor" ], "summary": "Add Bank Details", "description": "This endpoint allows tutors to add their bank details.", "operationId": "addBankDetails", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "account_number", "bank_name", "bank_address", "ifsc_code", "status" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "account_number": { "type": "string", "example": "123456789012" }, "bank_name": { "type": "string", "example": "Example Bank" }, "bank_address": { "type": "string", "example": "123 Sample St, City, Country" }, "ifsc_code": { "type": "string", "example": "EXAM1234567" } }, "type": "object" } } } }, "responses": { "201": { "description": "Bank detail added successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Bank detail added successfully" }, "bank_detail": { "properties": { "user_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "account_number": { "type": "string", "example": "123456789012" }, "bank_name": { "type": "string", "example": "Example Bank" }, "bank_address": { "type": "string", "example": "123 Sample St, City, Country" }, "ifsc_code": { "type": "string", "example": "EXAM1234567" }, "created_at": { "type": "string", "format": "datetime", "example": "2025-04-05 12:00:00" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "errors": { "properties": { "name": { "type": "array", "items": { "type": "string", "example": "The name field is required." } }, "account_number": { "type": "array", "items": { "type": "string", "example": "The account number field is required." } }, "bank_name": { "type": "array", "items": { "type": "string", "example": "The bank name field is required." } }, "bank_address": { "type": "array", "items": { "type": "string", "example": "The bank address field is required." } }, "ifsc_code": { "type": "array", "items": { "type": "string", "example": "The IFSC code field is required." } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/freelancer-students-list": { "get": { "tags": [ "Tutor" ], "summary": "Get list of students for a freelancer tutor", "operationId": "ef8573b0d970d87c29b10d7299568432", "responses": { "200": { "description": "Students fetched successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Students fetched successfully" }, "student_list": { "type": "array", "items": { "properties": { "group_id": { "type": "integer", "example": 1 }, "enroll_status": { "type": "string", "example": "1" }, "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "John Doe" }, "father_name": { "type": "string", "example": "Mr. Doe" }, "email": { "type": "string", "example": "johndoe@example.com" }, "mobile_no": { "type": "string", "example": "9876543210" }, "image": { "type": "string", "example": "path/to/image.jpg" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access or not a freelancer", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Exception message here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/freelancer-student-enrol": { "post": { "tags": [ "Tutor" ], "summary": "Enroll or remove a student by mobile number", "description": "Freelancer tutors can enroll or remove a student based on mobile number and status (1 = Enroll, 0 = Remove).", "operationId": "enrollStudentToTeacher", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "mobile_no", "status" ], "properties": { "mobile_no": { "description": "10-digit mobile number of the student", "type": "string", "example": "9876543210" }, "status": { "description": "1 = Enroll, 0 = Remove", "type": "string", "enum": [ "0", "1" ], "example": "1" } }, "type": "object" } } } }, "responses": { "200": { "description": "Operation completed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Student Enrolled Successfully" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized or Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation errors", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "errors": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/dashboard": { "get": { "tags": [ "tutor" ], "summary": "Get counts and details for the dashboard", "description": "Returns counts of test series, students, instructors, and additional details for dashboard.", "operationId": "d8dfc255bc920c8b7c328222280d38a4", "responses": { "200": { "description": "Successfully retrieved dashboard details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "totalTestseries": { "type": "integer", "example": 10 }, "totalStudents": { "type": "integer", "example": 150 }, "totalInstructors": { "type": "integer", "example": 20 }, "popularInstructors": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "rating": { "type": "number", "format": "float", "example": 4.5 }, "reviews": { "type": "integer", "example": 50 }, "total_students": { "type": "integer", "example": 100 }, "total_testseries": { "type": "integer", "example": 10 }, "description": { "type": "string", "example": "Top instructor" }, "image": { "type": "string", "example": "image.jpg" } }, "type": "object" } }, "recentTestSeries": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Test Series 1" }, "testseries_image": { "type": "string", "example": "testseries_image.jpg" }, "tutor_name": { "type": "string", "example": "John Doe" }, "tutor_image": { "type": "string", "example": "tutor_image.jpg" } }, "type": "object" } }, "notifications": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "message": { "type": "string", "example": "Notification message" }, "image": { "type": "string", "example": "notification_image.jpg" }, "role_id": { "type": "integer", "example": 3 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized (if the user is not authenticated)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not authenticated" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/student_add": { "post": { "tags": [ "tutor" ], "summary": "Student Add", "description": "Allow Tutor to add new student.", "operationId": "d3c63dedea74c0e4f6cdf93a68f079bf", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "mobile_no" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "johnDoe@example1.com" }, "mobile_no": { "type": "integer", "example": "1234567890" } }, "type": "object" } } } }, "responses": { "200": { "description": "Student successfully created", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Student added successfully" }, "student": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "johnDoe@example1.com" }, "mobile_no": { "type": "integer", "example": "1234567890" }, "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" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Validation error message" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/testseries_add": { "post": { "tags": [ "tutor" ], "summary": "Add New Testseries By Tutor", "description": "Allows a tutor to add new Testseries with Details.", "operationId": "c72fdbfa43e1ca6d2056629eaf4c2664", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "category_id", "testseries_name", "instructions", "total_time", "negative_marks", "per_ques_mark", "attempt_per_stud", "price" ], "properties": { "category_id": { "type": "integer", "example": "75" }, "testseries_name": { "type": "string", "example": "Hindi Test" }, "instructions": { "type": "string", "example": "Do any 5 Questions!" }, "total_time": { "type": "integer", "example": "30" }, "negative_marks": { "type": "integer", "example": "1" }, "per_ques_mark": { "type": "integer", "example": "4" }, "attempt_per_stud": { "type": "integer", "example": "20" }, "price": { "type": "integer", "example": "50" }, "testseries_image": { "type": "string", "example": "hinditest.jpg" } }, "type": "object" } } } }, "responses": { "200": { "description": "Test Series successfully created", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "testseries_image_path": { "type": "string", "example": "/upload/testseries/" }, "message": { "type": "string", "example": "Test Series added successfully" }, "testseries": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 1 }, "category_id": { "type": "integer", "example": "75" }, "testseries_name": { "type": "string", "example": "Hindi Tets" }, "instructions": { "type": "string", "example": "Do any 5 Questions!" }, "total_time": { "type": "integer", "example": "30" }, "negative_marks": { "type": "integer", "example": 1 }, "per_ques_mark": { "type": "integer", "example": "4" }, "attempt_per_stud": { "type": "integer", "example": "20" }, "price": { "type": "integer", "example": "50" }, "tseries_verif_status": { "type": "string", "enum": [ "pending", "approved", "rejected" ], "example": "approved" }, "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" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Validation error message" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/freelancer-testseries-list": { "get": { "tags": [ "Tutor" ], "summary": "Get test series list for freelancer tutor", "description": "Returns a list of approved test series for a freelancer tutor.", "operationId": "tutorFreelancerTestSeriesList", "responses": { "200": { "description": "Test series fetched successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Test series fetched successfully" }, "test_series_image_path": { "type": "string", "example": "upload/testseries/" }, "testseries_list": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 15 }, "name": { "type": "string", "example": "Maths Series" }, "testseries_image": { "type": "string", "example": "maths_series.jpg" }, "type": { "type": "string", "example": "mock" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Exception message here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/freelancer-testseries-assign-to-students": { "post": { "tags": [ "Tutor" ], "summary": "Assign Test Series to Students (Freelancer Tutor Only)", "operationId": "dd345e1beea592b8db945ceeb000475a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "testseries_id", "student_id", "start_date_testseries", "end_date_testseries" ], "properties": { "testseries_id": { "description": "ID of the test series", "type": "integer", "example": 5 }, "student_id": { "description": "Array of student IDs to assign the test series to", "type": "array", "items": { "type": "integer" }, "example": [ 101, 102, 103 ] }, "start_date_testseries": { "description": "Start date of the test series", "type": "string", "format": "date", "example": "2025-04-07" }, "end_date_testseries": { "description": "End date of the test series (must be after start_date)", "type": "string", "format": "date", "example": "2025-04-30" } }, "type": "object" } } } }, "responses": { "200": { "description": "Assignment status", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Student enrollment process completed!" }, "assigned": { "type": "integer", "example": 2 }, "skipped": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The testseries_id field is required." } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Invalid test series", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Invalid test series." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Exception message here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/get-category-for-add-testseries": { "get": { "tags": [ "Tutor" ], "summary": "Get Category List for Tutor", "operationId": "ff75a86d47de94301f9db0278b13ed36", "responses": { "200": { "description": "List of categories based on tutor type", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Test series fetched successfully" }, "categories_image_path": { "type": "string", "example": "upload/categories/" }, "category_list": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1449 }, "category_name": { "type": "string", "example": "Science" }, "category_title": { "type": "string", "example": "General Science Test Series" }, "category_image": { "type": "string", "example": "science.png" }, "category_slug": { "type": "string", "example": "science" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Error details" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/add-new-testseries": { "post": { "tags": [ "Tutor" ], "summary": "Add new test series by tutor", "description": "This endpoint allows a tutor (role_id = 3) to add a new test series. Tutors with tutor_type other than 0 can optionally assign it to a group.", "operationId": "Tutor_AddTestseries", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "test_series_name", "catid", "total_time", "per_question_mark", "attempt_per_stud" ], "properties": { "test_series_name": { "type": "string", "example": "Physics Mock Test 01" }, "catid": { "type": "integer", "example": 2 }, "testseries_image": { "type": "string", "format": "url", "example": "https://example.com/images/test.jpg" }, "instructions": { "type": "string", "example": "Please read instructions carefully." }, "total_time": { "type": "integer", "example": 60 }, "negative_marks": { "type": "integer", "example": 1 }, "per_question_mark": { "type": "number", "format": "float", "example": 2.5 }, "attempt_per_stud": { "type": "integer", "example": 1 }, "groupid": { "type": "integer", "example": 3, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Test Series added successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Test Series added Successfully" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error or insufficient balance or group issues", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The test series name field is required." } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Exception message here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/update-tutor-testseries": { "post": { "tags": [ "Tutor" ], "summary": "Update a test series by the tutor", "operationId": "3dc4c4a2444d24ee63c3d907de41663d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "testseries_id": { "type": "integer", "example": 1 }, "test_series_name": { "type": "string", "example": "Updated Test Series Name" }, "catid": { "type": "integer", "example": 2 }, "testseries_image": { "type": "string", "example": "image.jpg" }, "instructions": { "type": "string", "example": "Follow the instructions carefully." }, "total_time": { "type": "integer", "example": 90 }, "negative_marks": { "type": "integer", "example": 1 }, "per_question_mark": { "type": "number", "format": "float", "example": 2 }, "attempt_per_stud": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "responses": { "200": { "description": "Test Series updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Test Series updated successfully" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The testseries_id field is required." } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test Series not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Test Series not found" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Error details here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/testseries-headings": { "get": { "tags": [ "Tutor" ], "summary": "Get test series heading options", "description": "Returns a list of test series headings like Assignment and MCQ Test Series. Only accessible to Freelance tutors (tutor_type = 0).", "operationId": "getTutorTestSeriesHeadings", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Test series heading retrieved successfully" }, "my_test_series_heading": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "assignment" }, "name": { "type": "string", "example": "Assignment Testseries" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid token or not logged in", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Forbidden - Only freelance tutors are allowed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Tutor as a freelancer can access this api" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Exception message here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/testseries-list-tutor": { "get": { "tags": [ "Tutor" ], "summary": "Get Test Series List for Tutor (Only Institute/School Tutors)", "description": "Retrieves a list of test series assigned to a school/institute tutor. Freelancer tutors cannot access this API.", "operationId": "81be01b574b7f1767469c7dfb5a2a2fe", "responses": { "200": { "description": "Test series retrieved successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Test series retrieved successfully." }, "test_series_image_path": { "type": "string", "example": "upload/testseries/" }, "instructor_image_path": { "type": "string", "example": "upload/instructors/" }, "my_test_series": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "group_id": { "type": "integer", "example": 5 }, "group_name": { "type": "string", "example": "Class 12 Physics" }, "test_series_id": { "type": "integer", "example": 10 }, "test_series_name": { "type": "string", "example": "NEET Physics Test Series" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-08-01T10:00:00Z" }, "tseriesid": { "type": "integer", "example": 10 }, "usid": { "type": "integer", "example": 7 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized or freelancer tutor access denied", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access or freelancer tutor cannot access this API." } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No test series found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "No enrolled test series found." }, "test_series_image_path": { "type": "string", "example": "upload/testseries/" }, "instructor_image_path": { "type": "string", "example": "upload/instructors/" }, "my_test_series": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Internal Server Error" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/list-group-school": { "get": { "tags": [ "Tutor" ], "summary": "Get list of groups for school tutor", "description": "Retrieves a paginated list of groups that the authenticated school tutor is enrolled in.", "operationId": "GetGroupSchoolTutor", "responses": { "200": { "description": "Groups retrieved successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Groups retrieved successfully." }, "my_groups": { "description": "Paginated group list", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access or freelancer not allowed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No enrolled groups found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "No enrolled groups found." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Internal Server Error: some error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/get-testseries-edit-detail/{testseries_id}": { "get": { "tags": [ "Tutor" ], "summary": "Get Test Series Edit Detail", "description": "Retrieves the full details of a test series for editing. Only accessible by freelancer tutors.", "operationId": "985a91061b7565110cd294a635335a83", "parameters": [ { "name": "testseries_id", "in": "path", "description": "ID of the test series to retrieve", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Test series retrieved successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Test series retrieved successfully." }, "test_series_image_path": { "type": "string", "example": "upload/testseries/" }, "instructor_image_path": { "type": "string", "example": "upload/instructors/" }, "my_test_series": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "NEET Practice Series" }, "testseries_image": { "type": "string", "example": "image.jpg" }, "category_id": { "type": "integer", "example": 2 }, "testseries_slug": { "type": "string", "example": "neet-practice-series" }, "instructions": { "type": "string", "example": "Read all instructions carefully." }, "short_description": { "type": "string", "example": "Quick NEET practice." }, "pahragraph": { "type": "string", "example": "Intro paragraph content." }, "description": { "type": "string", "example": "Full description here." }, "total_time": { "type": "integer", "example": 90 }, "total_questions": { "type": "integer", "example": 100 }, "negative_marks": { "type": "number", "format": "float", "example": 0.25 }, "per_ques_mark": { "type": "number", "format": "float", "example": 4 }, "max_questions": { "type": "integer", "example": 100 }, "attempt_per_stud": { "type": "integer", "example": 2 }, "tseries_verif_status": { "type": "string", "example": "approved" }, "child": { "type": "string", "example": "" }, "for_sale": { "type": "integer", "example": 1 }, "price": { "type": "number", "format": "float", "example": 499 }, "days": { "type": "integer", "example": 30 }, "type": { "type": "string", "example": "mock" }, "sch_date_time_from": { "type": "string", "format": "date-time", "example": "2025-05-01T09:00:00Z" }, "sch_date_time_to": { "type": "string", "format": "date-time", "example": "2025-05-01T11:00:00Z" }, "result_publish_date": { "type": "string", "format": "date-time", "example": "2025-05-02T12:00:00Z" }, "is_publish": { "type": "integer", "example": 1 }, "show_result": { "type": "integer", "example": 1 }, "trending": { "type": "integer", "example": 0 }, "popular": { "type": "integer", "example": 0 }, "featured": { "type": "integer", "example": 1 }, "is_top_testseries": { "type": "integer", "example": 0 }, "test_series_type": { "type": "string", "example": "subjective" }, "best_sellers": { "type": "integer", "example": 0 }, "sequence": { "type": "integer", "example": 1 }, "created_at": { "type": "string", "format": "date-time", "example": "2025-01-01T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-01-02T10:00:00Z" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation failed for testseries_id.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The testseries id field is required." } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized - Only freelancer tutors allowed.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Only freelancer tutors can edit test series." } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series not found.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Test series not found." }, "test_series_image_path": { "type": "string", "example": "upload/testseries/" }, "instructor_image_path": { "type": "string", "example": "upload/instructors/" }, "my_test_series": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Internal Server Error: Something went wrong" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/testseries-by-type": { "post": { "tags": [ "Tutor" ], "summary": "Get Test Series by Type for Tutor (Only Freelancer)", "description": "Returns a list of test series (assignment or mcqpurchased) enrolled by the freelancer tutor.", "operationId": "7f6f8b7cad7ad1b6019cd29c457910d7", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "group_id" ], "properties": { "group_id": { "description": "Type of test series: 'assignment' or 'mcqpurchased'", "type": "string", "enum": [ "assignment", "mcqpurchased" ], "example": "assignment" } }, "type": "object" } } } }, "responses": { "200": { "description": "Test series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Test series retrieved successfully." }, "test_series_image_path": { "type": "string", "example": "upload/testseries/" }, "instructor_image_path": { "type": "string", "example": "upload/instructors/" }, "my_test_series": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request due to validation or invalid group type", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The group_id field is required." } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access. Please log in." } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Only freelancer tutors can access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Only freelancer tutors can access this API." } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No enrolled test series found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "No enrolled test series found." }, "test_series_image_path": { "type": "string", "example": "upload/testseries/" }, "instructor_image_path": { "type": "string", "example": "upload/instructors/" }, "my_test_series": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Internal Server Error" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/testseries-assign-to-students": { "post": { "tags": [ "Tutor" ], "summary": "Assign a test series to students by a school tutor", "description": "Authenticated school tutors can assign a test series to multiple students. The tutor must have sufficient wallet balance.", "operationId": "TutorAssignTestSeriesGroup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "testseries_id", "student_id", "start_date_testseries", "end_date_testseries" ], "properties": { "testseries_id": { "type": "integer", "example": 12 }, "student_id": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] }, "start_date_testseries": { "type": "string", "format": "date", "example": "2025-04-10" }, "end_date_testseries": { "type": "string", "format": "date", "example": "2025-04-20" } }, "type": "object" } } } }, "responses": { "200": { "description": "Test series assigned to students successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Student enrollment process completed!" }, "assigned": { "type": "integer", "example": 3 }, "skipped": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The testseries_id field is required." } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized or invalid tutor type", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Invalid test series ID", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Invalid test series." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Exception message here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/wallet_add": { "post": { "tags": [ "Tutor" ], "summary": "Add amount to wallet", "description": "This endpoint allows authenticated users to add an amount to their wallet. It creates a Razorpay order and returns the necessary details for the transaction.", "operationId": "80f90f53b1ba8b1db1cd61caae76ead8", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount" ], "properties": { "amount": { "description": "The amount to be added to the wallet in INR. Minimum amount should be Rs. 200.", "type": "integer", "format": "int64", "example": 1000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Order Created Successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Order Created Successfully" }, "data": { "properties": { "redirect_url": { "type": "string", "example": "https://example.com/add-wallet-payment/order_DB2P2z34d" }, "order_id": { "type": "integer", "example": 1 }, "amount": { "type": "integer", "example": 100000 }, "currency": { "type": "string", "example": "INR" }, "razorpay_key": { "type": "string", "example": "rzp_test_1234567890" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Minimum Amount added should be Rs. 200", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Minimum Amount added should be Rs. 200" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred: [error message]" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/tutor/students": { "get": { "tags": [ "Tutor" ], "summary": "Get students list based on tutor role (School-wise or Freelance-wise)", "operationId": "b280e50b98ecb5382c678d22ad8c5087", "responses": { "200": { "description": "Students list retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Students retrieved successfully" }, "students": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "mobile_no": { "type": "string", "example": "9876543210" }, "image": { "type": "string", "example": "profile.jpg" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access" } }, "security": [ { "sanctum": [] } ] } }, "/api/user/master/otp/{master}/{new_otp}": { "get": { "tags": [ "Utility" ], "summary": "Handle Master OTP operations", "operationId": "59d5dde56ad2edd02f82cd73f6fb6a42", "parameters": [ { "name": "master", "in": "path", "required": false, "schema": { "type": "string" } }, { "name": "new_otp", "in": "path", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation" }, "400": { "description": "Invalid input" } } } }, "/api/user/send-otp": { "post": { "tags": [ "Authentication" ], "summary": "Send OTP to a mobile number", "operationId": "a40b0dc880c718b311d12852d2c8bf28", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "mobile_no" ], "properties": { "mobile_no": { "type": "string", "example": "1111122211" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP sent successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "OTP sent" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The mobile_no field is required." } }, "type": "object" } } } }, "500": { "description": "Internal server error" } } } }, "/api/user/verify-otp": { "post": { "tags": [ "Authentication" ], "summary": "Verify OTP for a mobile number", "description": "This endpoint verifies the OTP sent to the user's mobile number and generates an authentication token upon successful verification.", "operationId": "8045b5c604ebe62db389ef5a013bc9b0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "mobile_no", "otp", "device_token_id" ], "properties": { "mobile_no": { "description": "The mobile number of the user.", "type": "string", "example": "1111122211" }, "otp": { "description": "The 6-digit OTP sent to the mobile number.", "type": "string", "example": "123456" }, "device_token_id": { "description": "The device token for push notifications.", "type": "string", "example": "your_device_token_id" }, "referred_by": { "description": "Referral code or identifier of the person who referred the user.", "type": "string", "example": "referrer_code_123" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP verified successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "token": { "type": "string", "example": "your_generated_token" }, "message": { "type": "string", "example": "OTP verified successfully" } }, "type": "object" } } } }, "400": { "description": "Invalid or expired OTP", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid OTP" } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not found" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while verifying OTP. Please try again later." } }, "type": "object" } } } } } } }, "/api/user/login": { "post": { "tags": [ "Authentication" ], "summary": "Login with mobile number or email and password", "operationId": "4c78bb9c609e07abd2505bb7afd5a891", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email_or_mobile", "password", "device_token_id" ], "properties": { "email_or_mobile": { "type": "string", "example": "user@example.com or 1234554321" }, "password": { "type": "string", "example": "123456" }, "device_token_id": { "type": "string", "example": "your_device_token_here" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "token": { "type": "string", "example": "your_generated_token_here" }, "message": { "type": "string", "example": "Login successful" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid credentials" } }, "type": "object" } } } }, "500": { "description": "Internal server error" } } } }, "/api/user/google-login": { "post": { "tags": [ "Authentication" ], "summary": "Login using Google", "description": "Logs in a user using Google login, validates the Google ID token, and returns an API token. If the user doesn't exist, it creates a new one.", "operationId": "googleUserLogin", "requestBody": { "description": "Google login credentials and token", "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "google_id", "device_token_id" ], "properties": { "name": { "description": "User's full name", "type": "string", "example": "John Doe" }, "email": { "description": "User's email address", "type": "string", "example": "john@example.com" }, "google_id": { "description": "Google user's unique ID", "type": "string", "example": "110169484474386276334" }, "device_token_id": { "description": "The user's device token for push notifications", "type": "string", "example": "device_token_here" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful, token returned", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Google Login successful" }, "token": { "type": "string", "example": "1|klj39sdfksjf02sjdk9sdf..." } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The google_id field is required." } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Invalid Google token", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Invalid Google token." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Internal server error" }, "error": { "type": "string", "example": "Exception message here..." } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/user/forgot-password": { "post": { "tags": [ "Authentication" ], "summary": "Request password reset OTP", "operationId": "7dccbdd0c91bd7e92751e3adb8bea87a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "contact" ], "properties": { "contact": { "type": "string", "example": "user@example.com or 1234554321" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP sent successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OTP sent successfully" } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not found" } }, "type": "object" } } } }, "500": { "description": "Internal server error" } } } }, "/api/user/verify_forget_password_otp": { "post": { "tags": [ "Authentication" ], "summary": "Verify OTP and issue token", "operationId": "61064a16628c7bbbf48c24a285e30465", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "contact", "otp" ], "properties": { "contact": { "type": "string", "example": "user@example.com or 1234554321" }, "otp": { "type": "string", "example": "123456" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP verified successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OTP verified successfully" }, "token": { "type": "string", "example": "your_generated_token_here" } }, "type": "object" } } } }, "400": { "description": "Invalid OTP or expired OTP", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid OTP or OTP expired" } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not found" } }, "type": "object" } } } }, "500": { "description": "Internal server error" } } } }, "/api/user/reset-password": { "post": { "tags": [ "Authentication" ], "summary": "Reset Password using token", "operationId": "c1fa7bbf548a33a6a66b6447b1e9af96", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reset_token", "password", "password_confirmation" ], "properties": { "reset_token": { "type": "string", "example": "123|abc..." }, "password": { "type": "string", "example": "12345678" }, "password_confirmation": { "type": "string", "example": "12345678" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password reset successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Password reset successfully" } }, "type": "object" } } } }, "400": { "description": "Invalid token or validation error" } } } }, "/api/user/login-user-with-pin": { "post": { "tags": [ "Authentication" ], "summary": "Login User with PIN", "description": "Authenticate a user using their device token ID, platform type, and PIN.", "operationId": "loginUserWithPIN", "requestBody": { "description": "Pass device token ID, platform type, and PIN for authentication", "required": true, "content": { "application/json": { "schema": { "required": [ "device_token_id", "user_pin", "pf_type" ], "properties": { "device_token_id": { "description": "Unique device token ID", "type": "string", "example": "abc123deviceToken" }, "user_pin": { "description": "4-digit user PIN", "type": "string", "example": 1234 }, "pf_type": { "description": "Platform type", "type": "string", "enum": [ "web", "android", "ios" ], "example": "android" } }, "type": "object" } } } }, "responses": { "200": { "description": "PIN verified successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "PIN verified successfully" }, "token": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Incorrect PIN", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Incorrect PIN" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "User not found or not authorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "User not found or not authorized" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } } } } }, "/api/user/user-pin-set": { "post": { "tags": [ "Authentication" ], "summary": "Set User PIN, Platform Type, and Device Token", "description": "Allows an authenticated user to set or update their 4-digit PIN, specify the platform type, and provide a device token.", "operationId": "setUserPin", "requestBody": { "description": "Provide a 4-digit user PIN, platform type, and device token", "required": true, "content": { "application/json": { "schema": { "required": [ "user_pin", "pf_type", "device_token_id" ], "properties": { "user_pin": { "description": "4-digit user PIN", "type": "string", "example": 1234 }, "pf_type": { "description": "Platform type", "type": "string", "enum": [ "web", "android", "ios" ], "example": "android" }, "device_token_id": { "description": "Unique device token identifier", "type": "string", "example": "device_token_example_123" } }, "type": "object" } } } }, "responses": { "200": { "description": "User PIN, platform type, and device token updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "User PIN, platform type, and device token updated successfully" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The device_token_id field is required." } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized Access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/delete-account-request": { "post": { "tags": [ "user" ], "summary": "Request Account Deletion", "description": "Allows an authenticated user to request their account to be deleted. The account will be scheduled for deletion after 30 days.", "operationId": "requestAccountDeletion", "responses": { "200": { "description": "Account deletion scheduled successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Your account deletion request has been submitted. Your account will be permanently deleted after 30 days." } }, "type": "object" } } } }, "401": { "description": "Unauthorized Access" }, "500": { "description": "Internal Server Error" } }, "security": [ { "sanctum": [] } ] } }, "/api/user/logout": { "post": { "tags": [ "Authentication" ], "summary": "Logout the authenticated user", "operationId": "293ac12de06bad36ce356760fcbb4dc7", "responses": { "200": { "description": "Logout successful", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Logout successful" } }, "type": "object" } } } }, "401": { "description": "User not authenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not authenticated" } }, "type": "object" } } } }, "500": { "description": "Internal server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/user/change-password": { "post": { "tags": [ "user" ], "summary": "Change user password", "operationId": "86d9b8863e7776cd61b2af16cbec0f08", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "new_password", "new_password_confirmation" ], "properties": { "new_password": { "type": "string", "example": "newpassword123" }, "new_password_confirmation": { "type": "string", "example": "newpassword123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password changed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Password changed successfully" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The new password and confirmation password must match." } }, "type": "object" } } } }, "401": { "description": "Unauthorized (if the user is not authenticated)" } }, "security": [ { "sanctum": [] } ] } }, "/api/user/change-email-mobile": { "post": { "tags": [ "Authentication" ], "summary": "Change user Email/Mobile No", "operationId": "2f4a105f7e0221defca06cee45043e9e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email_or_mobile", "flag_type" ], "properties": { "email_or_mobile": { "type": "string", "example": "user@example.com or 1234554321" }, "flag_type": { "type": "string", "enum": [ "email", "mobile" ], "example": "email" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP sent successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "OTP sent successfully." } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error or user already exists", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "User Already Exists with Same Email." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing the request." }, "error": { "type": "string", "example": "Error details here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/verify-otp-change-email-mobile": { "post": { "tags": [ "Authentication" ], "summary": "Verify OTP for changing Email or Mobile No", "operationId": "fe955c1f7100ac8c7ffd3968dc52319b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email_or_mobile", "otp", "flag_type" ], "properties": { "email_or_mobile": { "type": "string", "example": "user@example.com or 1234554321" }, "otp": { "type": "string", "example": "123456" }, "flag_type": { "type": "string", "enum": [ "email", "mobile" ], "example": "email" } }, "type": "object" } } } }, "responses": { "200": { "description": "Verification successful", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Email verified successfully" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error or invalid OTP", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Invalid or expired OTP" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "User already exists with same email or mobile", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "User Already Exists with Same Email Address" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Internal server error" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/current": { "get": { "tags": [ "user" ], "summary": "Get details of the currently logged-in user", "description": "Returns the authenticated user's details if the request is authenticated.", "operationId": "25117647a115f8e9e443a106df6d1937", "responses": { "200": { "description": "Successfully retrieved user details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "user": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "mobile_no": { "type": "string", "example": "1234567890" }, "address": { "type": "string", "example": "123 Main St" }, "classname": { "type": "string", "example": "100" }, "is_pass_create": { "type": "integer", "example": "1 or 0" }, "facebook": { "type": "string", "example": "https://facebook.com/johndoe" }, "twitter": { "type": "string", "example": "https://twitter.com/johndoe" }, "instagram": { "type": "string", "example": "https://instagram.com/johndoe" }, "linkedin": { "type": "string", "example": "https://linkedin.com/in/johndoe" }, "student": { "properties": { "school": { "type": "string", "example": "ABC School" }, "state": { "type": "string", "example": "California" }, "city": { "type": "string", "example": "Los Angeles" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "User not authenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not authenticated" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/update": { "post": { "tags": [ "user" ], "summary": "Update user details", "operationId": "17f0507b360100f9361c1fb5df8fc8e9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "johndoe@example.com" }, "mobile_no": { "type": "string", "example": "1234567890" }, "father_name": { "type": "string", "example": "Robert Doe" }, "mother_name": { "type": "string", "example": "Jane Doe" }, "school": { "type": "string", "example": "ABC School" }, "state": { "type": "string", "example": "California" }, "city": { "type": "string", "example": "Los Angeles" }, "address": { "type": "string", "example": "123 Main St" }, "classname": { "type": "string", "example": "100" } }, "type": "object" } } } }, "responses": { "200": { "description": "User details updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User details updated successfully" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation error message" } }, "type": "object" } } } }, "401": { "description": "Unauthorized (if the user is not authenticated)" } }, "security": [ { "sanctum": [] } ] } }, "/api/user/profile_image_upload": { "get": { "tags": [ "user" ], "summary": "Upload User Profile Image", "description": "Uploads a profile image for the authenticated user and saves the file name in the database.", "operationId": "uploadUserProfile", "parameters": [ { "name": "image", "in": "query", "description": "The name of the image file to be uploaded", "required": true, "schema": { "type": "string", "example": "profile_picture.png" } } ], "responses": { "200": { "description": "Image uploaded successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Image uploaded successfully" }, "user_image": { "type": "string", "example": "profile_picture.png" }, "user_image_path": { "type": "string", "example": "/upload/student" }, "current_user_image": { "type": "string", "example": "profile_picture.png" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No image file provided" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred: [error_message]" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/dashboard": { "get": { "tags": [ "user" ], "summary": "Get counts and details for the dashboard", "description": "Returns counts of test series, students, instructors, and additional details for dashboard.", "operationId": "9eb4f073a3d8ff1f6e07220faee0eeff", "responses": { "200": { "description": "Successfully retrieved dashboard details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "totalTestseries": { "type": "integer", "example": 10 }, "totalStudents": { "type": "integer", "example": 150 }, "totalInstructors": { "type": "integer", "example": 20 }, "topInstructors": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "rating": { "type": "number", "format": "float", "example": 4.5 }, "reviews": { "type": "integer", "example": 50 }, "total_students": { "type": "integer", "example": 100 }, "total_testseries": { "type": "integer", "example": 10 }, "description": { "type": "string", "example": "Top instructor" }, "image": { "type": "string", "example": "image.jpg" } }, "type": "object" } }, "topTestSeries": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Test Series 1" }, "testseries_image": { "type": "string", "example": "testseries_image.jpg" }, "tutor_name": { "type": "string", "example": "John Doe" }, "tutor_image": { "type": "string", "example": "tutor_image.jpg" } }, "type": "object" } }, "notifications": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "message": { "type": "string", "example": "Notification message" }, "image": { "type": "string", "example": "notification_image.jpg" }, "role_id": { "type": "integer", "example": 2 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized (if the user is not authenticated)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not authenticated" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/featured_test_series": { "get": { "tags": [ "user" ], "summary": "Retrieve featured test series", "description": "Fetches the top 6 featured test series that are approved and for sale, including associated user and teacher details.", "operationId": "a102fd9750f74e806ebd42cb216402e3", "responses": { "200": { "description": "Successfully retrieved featured test series", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "images_path": { "type": "string", "example": "upload/testseries/" }, "total_test_series": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Test Series A" }, "price": { "type": "number", "format": "float", "example": 99.99 }, "total_time": { "type": "string", "example": "2 hours" }, "testseries_image": { "type": "string", "example": "https://example.com/images/testseries_round_image.png" } }, "type": "object" } }, "trending_test_series": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Trending Test Series" }, "price": { "type": "number", "format": "float", "example": 59.99 }, "total_time": { "type": "string", "example": "1.5 hours" }, "testseries_image": { "type": "string", "example": "https://example.com/images/trending_testseries_image.png" } }, "type": "object" } }, "popular_test_series": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Popular Test Series" }, "price": { "type": "number", "format": "float", "example": 79.99 }, "total_time": { "type": "string", "example": "2 hours" }, "testseries_image": { "type": "string", "example": "https://example.com/images/popular_testseries_image.png" } }, "type": "object" } }, "featured_test_series": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "Featured Test Series" }, "price": { "type": "number", "format": "float", "example": 69.99 }, "total_time": { "type": "string", "example": "2 hours" }, "testseries_image": { "type": "string", "example": "https://example.com/images/featured_testseries_image.png" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not authenticated" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/test_series_detail/{id}": { "get": { "tags": [ "user" ], "summary": "Get details of a specific test series", "description": "Fetches details of a specific test series by its ID, including specific columns like id, user_id, name, testseries_image, instructions, short_description, price, description, total_time, and created_at. Also includes teacher details, total number of questions, and reviews.", "operationId": "eb17d6f16a2a05681c04d8a939cbe48f", "parameters": [ { "name": "id", "in": "path", "description": "ID of the test series", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully retrieved test series details", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "teacher_image_path": { "type": "string", "example": "/upload/instructors/" }, "test_series_image_path": { "type": "string", "example": "upload/testseries/" }, "test_series_detail": { "properties": { "id": { "type": "integer", "example": 565 }, "user_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Transportation in Animal and Plants" }, "testseries_image": { "type": "string", "example": "TS-1699861917.png" }, "instructions": { "type": "string", "example": "1. You must only attempt this exam once. ..." }, "short_description": { "type": "string", "example": "Test paper designed in a way that builds confidence..." }, "price": { "type": "string", "example": "10" }, "description": { "type": "string", "example": "Full description here." }, "total_time": { "type": "string", "example": "30" }, "created_at": { "type": "string", "format": "date-time", "example": "2023-11-13T13:10:56Z" } }, "type": "object" }, "teacher_detail": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "admin" }, "image": { "type": "string", "example": "IMG_20200616_191746879.jpg" } }, "type": "object" }, "total_test_series_question": { "type": "integer", "example": 12 }, "reviews": { "properties": { "skills": { "type": "string", "example": "Expert" }, "total_testseries": { "type": "integer", "example": 5 }, "rating": { "type": "number", "format": "float", "example": 4.5 }, "reviews": { "type": "string", "example": "Great test series!" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Test series not found." } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/top_category": { "get": { "tags": [ "user" ], "summary": "Get top categories", "description": "Fetches top categories including details like category name, image, and slug.", "operationId": "60480e8bd57bf9adc9906e5bb7399442", "responses": { "200": { "description": "Successfully retrieved categories", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "top_categories_image_path": { "type": "string", "example": "upload/categories/" }, "top_categories": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "category_name": { "type": "string", "example": "Science" }, "category_slug": { "type": "string", "example": "science" }, "category_image": { "type": "string", "example": "https://example.com/images/science.png" }, "category_desc": { "type": "string", "example": "Description of Science category." }, "category_sh_descr": { "type": "string", "example": "Short description." } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/all_category": { "get": { "tags": [ "user" ], "summary": "Get all categories", "description": "Fetches all categories including details like category name, image, and slug.", "operationId": "e3b73704b4aa30f3cc4e2a81b92c8ee5", "responses": { "200": { "description": "Successfully retrieved categories", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "categories_image_path": { "type": "string", "example": "upload/categories/" }, "categories": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "category_name": { "type": "string", "example": "Science" }, "category_slug": { "type": "string", "example": "science" }, "category_image": { "type": "string", "example": "https://example.com/images/science.png" }, "category_desc": { "type": "string", "example": "Description of Science category." }, "category_sh_descr": { "type": "string", "example": "Short description." } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/child_category/{parent_id}": { "get": { "tags": [ "user" ], "summary": "Get child categories for a given parent category", "description": "Fetches child categories for a specific parent category, including details like category name, image, and slug.", "operationId": "bead8e3a960d5c9d8e1f85896ee66c06", "parameters": [ { "name": "parent_id", "in": "path", "description": "ID of the parent category", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully retrieved child categories", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "categories_image_path": { "type": "string", "example": "upload/categories/" }, "categories": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "category_name": { "type": "string", "example": "Biology" }, "category_slug": { "type": "string", "example": "biology" }, "category_image": { "type": "string", "example": "https://example.com/images/biology.png" }, "category_desc": { "type": "string", "example": "Description of Biology category." }, "category_sh_descr": { "type": "string", "example": "Short description." } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/get_test_seriesByCategory/{categoryId}": { "get": { "tags": [ "user" ], "summary": "Get test series by category", "description": "Fetches test series for a specific category and its subcategories. Results are paginated.", "operationId": "9699fb22c0118b0f78e84b0f71bf16f5", "parameters": [ { "name": "categoryId", "in": "path", "description": "ID of the category", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Successfully retrieved test series", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "test_series": { "properties": { "current_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Test Series A" }, "description": { "type": "string", "example": "Full description here." }, "price": { "type": "integer", "example": 20 }, "total_time": { "type": "string", "example": "2 hours" }, "instructor": { "type": "string", "example": "John Doe" }, "tutor_image": { "type": "string", "example": "https://example.com/images/tutor_image.png" }, "rating": { "type": "integer", "example": 4 }, "total_students": { "type": "integer", "example": 200 }, "total_testseries": { "type": "integer", "example": 5 } }, "type": "object" } }, "first_page_url": { "type": "string", "example": "http://localhost:8000/api/user/get_test_seriesByCategory/86?page=1" }, "last_page_url": { "type": "string", "example": "http://localhost:8000/api/user/get_test_seriesByCategory/86?page=5" }, "next_page_url": { "type": "string", "example": "http://localhost:8000/api/user/get_test_seriesByCategory/86?page=2" }, "prev_page_url": { "type": "string", "example": "null" }, "total": { "type": "integer", "example": 44 }, "per_page": { "type": "integer", "example": 10 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/get_all_test_series": { "get": { "tags": [ "user" ], "summary": "Retrieve a paginated list of test series", "description": "Fetches a paginated list of test series with related teacher details. Returns an empty list with a 404 status if no test series are found.", "operationId": "28bce111b1c25ef7592ca9c915ece825", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Successful response with a paginated list of test series", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "test_series": { "properties": { "current_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Sample Test Series" }, "description": { "type": "string", "example": "Description of the test series" }, "for_sale": { "type": "boolean", "example": true }, "tseries_verif_status": { "type": "string", "example": "approved" }, "days": { "type": "integer", "example": 30 }, "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" }, "teacherDetail": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Instructor Name" }, "image": { "type": "string", "example": "path/to/image.jpg" } }, "type": "object" } }, "type": "object" } }, "first_page_url": { "type": "string", "example": "/api/test-series?page=1" }, "last_page_url": { "type": "string", "example": "/api/test-series?page=10" }, "next_page_url": { "type": "string", "example": "/api/test-series?page=2" }, "prev_page_url": { "type": "string", "example": "/api/test-series?page=1" }, "total": { "type": "integer", "example": 100 }, "per_page": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No test series found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "No test series found" }, "test_series": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/get_test_series_by_instructor": { "get": { "tags": [ "user" ], "summary": "Retrieve test series by instructor", "description": "Fetches a list of test series created by a specific instructor (user). Returns an empty list with a 404 status if no test series are found for the provided instructor.", "operationId": "f49d3f20e8ed769f6aec0ad428897aea", "parameters": [ { "name": "instructor_id", "in": "query", "description": "Instructor's user ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Successful response with a list of test series", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "test_series": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Sample Test Series" }, "description": { "type": "string", "example": "Description of the test series" }, "for_sale": { "type": "boolean", "example": true }, "tseries_verif_status": { "type": "string", "example": "approved" }, "days": { "type": "integer", "example": 30 }, "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" }, "teacherDetail": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Instructor Name" }, "image": { "type": "string", "example": "path/to/image.jpg" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No test series found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "No test series found" }, "test_series": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/search_test_series": { "get": { "tags": [ "user" ], "summary": "Search for test series", "description": "Searches for test series based on the given search terms in name . Returns an empty list with a 404 status if no matches are found.", "operationId": "7b7146a557dd34ff571b3b0d87a959e3", "parameters": [ { "name": "search", "in": "query", "description": "Search term for the test series name", "required": true, "schema": { "type": "string", "example": "magnetic-field" } } ], "responses": { "200": { "description": "Successful response with the list of matching test series", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "test_series": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Sample Test Series" }, "description": { "type": "string", "example": "Description of the test series" }, "for_sale": { "type": "boolean", "example": true }, "tseries_verif_status": { "type": "string", "example": "approved" }, "days": { "type": "integer", "example": 30 }, "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" }, "teacherDetail": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Instructor Name" }, "image": { "type": "string", "example": "path/to/image.jpg" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No matching test series found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "No matching test series found" }, "test_series": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/purchase_test_series": { "post": { "tags": [ "user" ], "summary": "Purchase Test Series", "description": "Allows a user to purchase a test series either through wallet balance or Razorpay payment gateway.", "operationId": "852544fce31a26184544bbfbe21d3741", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "test_series_id", "price" ], "properties": { "test_series_id": { "description": "ID of the test series to be purchased", "type": "integer", "example": 1 }, "price": { "description": "Price of the test series", "type": "number", "format": "float", "example": 499.99 } }, "type": "object" } } } }, "responses": { "200": { "description": "Test Series Purchased Successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Test Series Purchased Successfully" }, "payment_status": { "type": "string", "example": "success" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized or Profile Deactivated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Your Profile is Deactivated." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Exception details" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/razorpay-success": { "post": { "tags": [ "user" ], "summary": "Handle Success Response from Razorpay", "description": "Processes the successful payment response from Razorpay and enrolls the user in the test series.", "operationId": "d0d5c381ba21dc7abfe73a572afa5ac5", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "payment_id", "razorpay_payment_id" ], "properties": { "payment_id": { "description": "ID of the payment record in the system", "type": "integer", "example": 1 }, "razorpay_payment_id": { "description": "Payment ID provided by Razorpay", "type": "string", "example": "rzp_test_abc123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment successful and user enrolled in test series", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Payment successful and user enrolled in test series" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Payment verification failed" }, "error": { "type": "string", "example": "Exception details" } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/user/razorpay-failed": { "post": { "tags": [ "user" ], "summary": "Handle Failed Response from Razorpay", "description": "Processes the failed payment response from Razorpay and updates the payment status in the system.", "operationId": "f3918d5c956afadf25bd30fecfae67d4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "payment_id", "razorpay_payment_id" ], "properties": { "payment_id": { "description": "ID of the payment record in the system", "type": "integer", "example": 1 }, "razorpay_payment_id": { "description": "Payment ID provided by Razorpay", "type": "string", "example": "rzp_test_abc123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment failed response handled successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Payment failed. Please try again." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Payment verification failed" }, "error": { "type": "string", "example": "Exception details" } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/user/scholarship_apply": { "post": { "tags": [ "user" ], "summary": "Apply for a scholarship", "description": "Allows a user to apply for a scholarship with their details.", "operationId": "d5c118f96209a9b765585f537c0e8781", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "applicant_name", "father_name", "mother_name", "mobile_no", "dob", "gender", "address", "adahar_no", "state", "district", "pincode", "school", "class" ], "properties": { "applicant_name": { "type": "string", "example": "John Doe" }, "father_name": { "type": "string", "example": "Richard Doe" }, "mother_name": { "type": "string", "example": "Jane Doe" }, "mobile_no": { "type": "integer", "example": "1234567890" }, "dob": { "type": "string", "format": "date", "example": "2000-01-01" }, "physically_challenged": { "type": "integer", "enum": [ 0, 1 ], "example": 0 }, "cast_category": { "type": "integer", "example": "2" }, "gender": { "type": "string", "example": "Male" }, "address": { "type": "string", "example": "123 Main Street" }, "adahar_no": { "type": "integer", "example": "123456789012" }, "state": { "type": "integer", "example": "11" }, "district": { "type": "string", "example": "Los Angeles" }, "pincode": { "type": "integer", "example": "90001" }, "school": { "type": "integer", "example": "2" }, "class": { "type": "integer", "example": "10" } }, "type": "object" } } } }, "responses": { "200": { "description": "Scholarship application successfully created", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Scholarship Application added successfully" }, "scholarship": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 1 }, "applicant_name": { "type": "string", "example": "John Doe" }, "father_name": { "type": "string", "example": "Richard Doe" }, "mother_name": { "type": "string", "example": "Jane Doe" }, "mobile_no": { "type": "integer", "example": "1234567890" }, "dob": { "type": "string", "format": "date", "example": "2000-01-01" }, "physically_challenged": { "type": "integer", "example": 0 }, "cast_category": { "type": "integer", "example": "2" }, "gender": { "type": "string", "example": "Male" }, "address": { "type": "string", "example": "123 Main Street" }, "adahar_no": { "type": "integer", "example": "123456789012" }, "state": { "type": "integer", "example": "11" }, "district": { "type": "string", "example": "Los Angeles" }, "pincode": { "type": "integer", "example": "90001" }, "school": { "type": "integer", "example": "2" }, "class": { "type": "integer", "example": "10" }, "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" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Validation error message" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/all_scholarships": { "get": { "tags": [ "user" ], "summary": "Retrieve all scholarship applications", "description": "Fetches all scholarship applications from the database.", "operationId": "d5f0cb9f14ff00b88f91b219533b14ae", "responses": { "200": { "description": "Scholarship applications retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Scholarship applications retrieved successfully" }, "scholarships": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 1 }, "applicant_name": { "type": "string", "example": "John Doe" }, "father_name": { "type": "string", "example": "Richard Doe" }, "mother_name": { "type": "string", "example": "Jane Doe" }, "mobile_no": { "type": "string", "example": "1234567890" }, "dob": { "type": "string", "format": "date", "example": "2000-01-01" }, "physically_challenged": { "type": "boolean", "example": false }, "cast_category": { "type": "string", "example": "General" }, "gender": { "type": "string", "example": "Male" }, "address": { "type": "string", "example": "123 Main Street" }, "adahar_no": { "type": "string", "example": "1234-5678-9012" }, "state": { "type": "string", "example": "California" }, "district": { "type": "string", "example": "Los Angeles" }, "pincode": { "type": "string", "example": "90001" }, "school": { "type": "string", "example": "Central High School" }, "class": { "type": "string", "example": "10th" }, "applicat_photo": { "type": "string", "example": "/storage/upload/profile/photo.jpg" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-08-22T00:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-08-22T00:00:00Z" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/single_scholarship/{id}": { "get": { "tags": [ "user" ], "summary": "Retrieve a single scholarship application for editing", "description": "Fetches a single scholarship application record by ID for the authenticated user.", "operationId": "17aad4dbbd179c959ba0f7b814fe573d", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the scholarship application to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Scholarship application retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Scholarship application retrieved successfully" }, "scholarship": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 1 }, "applicant_name": { "type": "string", "example": "John Doe" }, "father_name": { "type": "string", "example": "Richard Doe" }, "mother_name": { "type": "string", "example": "Jane Doe" }, "mobile_no": { "type": "string", "example": "1234567890" }, "dob": { "type": "string", "format": "date", "example": "2000-01-01" }, "physically_challenged": { "type": "boolean", "example": false }, "cast_category": { "type": "string", "example": "General" }, "gender": { "type": "string", "example": "Male" }, "address": { "type": "string", "example": "123 Main Street" }, "adahar_no": { "type": "string", "example": "1234-5678-9012" }, "state": { "type": "string", "example": "California" }, "district": { "type": "string", "example": "Los Angeles" }, "pincode": { "type": "string", "example": "90001" }, "school": { "type": "string", "example": "Central High School" }, "class": { "type": "string", "example": "10th" }, "applicat_photo": { "type": "string", "example": "/storage/upload/profile/photo.jpg" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-08-22T00:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-08-22T00:00:00Z" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The selected id is invalid." } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Scholarship application not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Scholarship application not found" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/available-scholarship/testseries": { "get": { "tags": [ "user" ], "summary": "Retrieve a list of test series for a user's scholarship group", "description": "Fetches a list of test series associated with the user's scholarship group. If no test series are found, returns an empty list with a 404 status.", "operationId": "d27a101e4bd2226b717ac0058b7f03f3", "responses": { "200": { "description": "Successful response with a list of test series", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Scholarship Group test series retrieved successfully" }, "teacher_image_path": { "type": "string", "example": "/upload/instructors/" }, "test_series_image_path": { "type": "string", "example": "upload/testseries/" }, "test_series": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1313 }, "user_id": { "type": "integer", "example": 555 }, "name": { "type": "string", "example": "Rational number PFT" }, "testseries_image": { "type": "string", "example": null }, "category_id": { "type": "string", "example": "1450" }, "testseries_slug": { "type": "string", "example": "rational-number-pft" }, "instructions": { "type": "string", "example": "." }, "total_time": { "type": "string", "example": "30" }, "price": { "type": "string", "example": "10" }, "is_enrolled": { "type": "boolean", "example": false }, "teacherDetail": { "properties": { "id": { "type": "integer", "example": 555 }, "name": { "type": "string", "example": "Supriya Dixit" }, "image": { "type": "string", "example": "" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No test series found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "No test series found" }, "test_series": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/update_scholarship": { "post": { "tags": [ "user" ], "summary": "Update a scholarship application", "description": "Allows a user to update their scholarship application details.", "operationId": "f91f090522abcd6c58ccebc0556d0866", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "update_id", "applicant_name", "father_name", "mother_name", "mobile_no", "dob", "gender", "address", "adahar_no", "state", "district", "pincode", "school", "class" ], "properties": { "update_id": { "description": "Scholarship ID", "type": "integer", "example": 1 }, "applicant_name": { "type": "string", "example": "John Doe" }, "father_name": { "type": "string", "example": "Richard Doe" }, "mother_name": { "type": "string", "example": "Jane Doe" }, "mobile_no": { "type": "string", "example": "1234567890" }, "dob": { "type": "string", "format": "date", "example": "2000-01-01" }, "physically_challenged": { "type": "integer", "enum": [ 0, 1 ], "example": 0 }, "cast_category": { "type": "integer", "example": 2 }, "gender": { "type": "string", "example": "Male" }, "address": { "type": "string", "example": "123 Main Street" }, "adahar_no": { "type": "string", "example": "123456789012" }, "state": { "type": "integer", "example": 11 }, "district": { "type": "string", "example": "Los Angeles" }, "pincode": { "type": "string", "example": "90001" }, "school": { "type": "integer", "example": 2 }, "class": { "type": "integer", "example": 10 } }, "type": "object" } } } }, "responses": { "200": { "description": "Scholarship application updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Scholarship Application updated successfully" }, "scholarship": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 1 }, "applicant_name": { "type": "string", "example": "John Doe" }, "father_name": { "type": "string", "example": "Richard Doe" }, "mother_name": { "type": "string", "example": "Jane Doe" }, "mobile_no": { "type": "string", "example": "1234567890" }, "dob": { "type": "string", "format": "date", "example": "2000-01-01" }, "physically_challenged": { "type": "integer", "example": 0 }, "cast_category": { "type": "integer", "example": 2 }, "gender": { "type": "string", "example": "Male" }, "address": { "type": "string", "example": "123 Main Street" }, "adahar_no": { "type": "string", "example": "123456789012" }, "state": { "type": "integer", "example": 11 }, "district": { "type": "string", "example": "Los Angeles" }, "pincode": { "type": "string", "example": "90001" }, "school": { "type": "integer", "example": 2 }, "class": { "type": "integer", "example": 10 }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Validation error message" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/schools": { "get": { "tags": [ "user" ], "summary": "Get all active schools", "description": "Fetches a list of all active schools with their IDs and names. If no logo is available, a default image is provided.", "operationId": "396fdf2d6244bb3553c3a5ba07cd9c4f", "responses": { "200": { "description": "List of active schools with ID and name", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "school_name": { "type": "string", "example": "Greenwood High" } }, "type": "object" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/schools-group": { "get": { "tags": [ "user" ], "summary": "Get all active schools with scholarship groups", "description": "Fetches a list of all active schools that provide scholarships, including groups associated with each school.", "operationId": "3c04044810da1cda59df2991c8b3458b", "responses": { "200": { "description": "List of active schools with scholarship groups", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "schools": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "school_name": { "type": "string", "example": "Greenwood High" }, "is_provide_scholarship": { "type": "boolean", "example": true }, "groups": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 101 }, "name": { "type": "string", "example": "Science Scholarship Group" }, "school_id": { "type": "integer", "example": 1 }, "status": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2023-01-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2023-01-10T12:00:00Z" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/all_states": { "get": { "tags": [ "user" ], "summary": "Get all states", "description": "Fetches a list of all states with their IDs and names.", "operationId": "44fa2e277104daeb48e013d32f6a8607", "responses": { "200": { "description": "List of states with ID and name", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "state_name": { "type": "string", "example": "California" } }, "type": "object" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/all_districts": { "get": { "tags": [ "user" ], "summary": "Get districts by state", "description": "Fetches a list of districts for a given state ID.", "operationId": "7c98c2e5096ebf90c83af9ec42931bf4", "parameters": [ { "name": "fk_state_id", "in": "query", "description": "The ID of the state to filter districts by", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of districts with ID and name for the given state ID", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "city_name": { "type": "string", "example": "Los Angeles" } }, "type": "object" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The fk_state_id field is required." } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "No districts found for the given state ID" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/wallet_history": { "get": { "tags": [ "user", "Tutor" ], "summary": "Retrieve wallet history for the authenticated user", "description": "Fetches the wallet transaction history for the currently authenticated user.", "operationId": "3664731124999666721049ce99a83a2b", "responses": { "200": { "description": "Wallet history successfully retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "wallet_history": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 1 }, "amount": { "type": "number", "format": "float", "example": 100.5 }, "transaction_type": { "type": "string", "example": "credit" }, "description": { "type": "string", "example": "Salary credited" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-08-22T00:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-08-22T00:00:00Z" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Detailed error message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/wallet_add": { "post": { "tags": [ "user" ], "summary": "Add amount to wallet", "description": "This endpoint allows authenticated users to add an amount to their wallet. It creates a Razorpay order and returns the necessary details for the transaction.", "operationId": "ba2e6b89695fda382e09bf09d1a01d64", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount" ], "properties": { "amount": { "description": "The amount to be added to the wallet in INR. Minimum amount should be Rs. 200.", "type": "integer", "format": "int64", "example": 1000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Order Created Successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Order Created Successfully" }, "data": { "properties": { "redirect_url": { "type": "string", "example": "https://example.com/add-wallet-payment/order_DB2P2z34d" }, "order_id": { "type": "integer", "example": 1 }, "amount": { "type": "integer", "example": 100000 }, "currency": { "type": "string", "example": "INR" }, "razorpay_key": { "type": "string", "example": "rzp_test_1234567890" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Minimum Amount added should be Rs. 200", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Minimum Amount added should be Rs. 200" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred: [error message]" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/wallet_verify": { "post": { "tags": [ "user", "Tutor" ], "summary": "Verify payment", "description": "This endpoint verifies the payment made via Razorpay and adds the amount to the user's wallet.", "operationId": "b1d2f64f5d556abc8dd2c0ca4e55c918", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "rzp_orderid", "rzp_paymentid" ], "properties": { "rzp_orderid": { "description": "Razorpay order ID", "type": "string", "example": "order_DB2P2z34d" }, "rzp_paymentid": { "description": "Razorpay payment ID", "type": "string", "example": "pay_Abc123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment successful, amount added to wallet", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Payment successful, amount added to wallet" }, "data": { "properties": { "wallet_balance": { "type": "integer", "example": 1500 }, "wallet_history": { "properties": { "message": { "type": "string", "example": "No wallet history found" }, "data": { "type": "array", "items": { "properties": { "date": { "type": "string", "format": "date", "example": "2024-08-23" }, "amount": { "type": "integer", "example": 500 }, "remarks": { "type": "string", "example": "Added in wallet" }, "type": { "type": "string", "example": "credit" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Invalid Order Id & RAZORPAY Order Id", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Order Id & RAZORPAY Order Id" } }, "type": "object" } } } }, "500": { "description": "Payment Failed, Please Try Again", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Payment Failed, Please Try Again" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/instructor_detail": { "get": { "tags": [ "user" ], "summary": "Retrieve instructor details", "description": "Fetches the details of a single instructor by their ID.", "operationId": "3c1511709bb33b43288920d65a9a39e7", "parameters": [ { "name": "id", "in": "query", "description": "ID of the instructor", "required": true, "schema": { "type": "string", "example": "485" } } ], "responses": { "200": { "description": "Successfully retrieved instructor details", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "instructor_image_path": { "type": "string", "example": "/upload/instructors/" }, "instructor": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "image": { "type": "string", "example": "john_doe.png" }, "experience": { "type": "string", "example": "5 years" }, "qualification": { "type": "string", "example": "M.Sc. in Physics" }, "teacher_details": { "properties": { "additional_info": { "type": "string", "example": "Expert in Quantum Physics" } }, "type": "object" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Instructor not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Instructor not found" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/all_instructors": { "get": { "tags": [ "user" ], "summary": "Retrieve all instructors", "description": "Fetches the all instructors who are active and have the role_id of 3.", "operationId": "4e73ce0d8cd7ec7156c1d1a34725cff2", "responses": { "200": { "description": "Successfully retrieved all instructors", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "allInstructors_image_path": { "type": "string", "example": "/upload/instructors/" }, "allInstructors": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "image": { "type": "string", "example": "john_doe.png" }, "experience": { "type": "string", "example": "5 years" }, "qualification": { "type": "string", "example": "M.Sc. in Physics" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/my_test_series": { "get": { "tags": [ "user" ], "summary": "Retrieve all enrollments for the authenticated user", "description": "Fetches all enrollments from the enroll_testseries table for the authenticated user.", "operationId": "a1024f06e0b2e763ca9fe687a973df8c", "responses": { "200": { "description": "Successfully retrieved all enrollments test series", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "enrollments": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 1 }, "enroll_type": { "type": "string", "example": "monthly" }, "testseries_id": { "type": "integer", "example": 2 }, "plan_id": { "type": "integer", "example": 1 }, "pay_id": { "type": "integer", "example": 3 }, "start_date": { "type": "string", "format": "date", "example": "2024-09-01" }, "end_date": { "type": "string", "format": "date", "example": "2024-09-30" }, "days": { "type": "integer", "example": 30 }, "enroll_by": { "type": "string", "example": "admin" }, "enroll_status": { "type": "string", "example": "active" }, "test_start_time": { "type": "string", "format": "date-time", "example": "2024-09-05T10:00:00" }, "test_progress_time": { "type": "string", "format": "date-time", "example": null }, "test_end_time": { "type": "string", "format": "date-time", "example": "2024-09-05T12:00:00" }, "test_submit_time": { "type": "string", "format": "date-time", "example": null }, "created_at": { "type": "string", "format": "date-time", "example": "2024-09-01T12:00:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-09-01T12:00:00" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/bundle-testseries/{enrollment_id}": { "get": { "tags": [ "user" ], "summary": "Get Bundle Test Series", "description": "Fetches the bundle test series associated with the authenticated user based on the enrollment ID.", "operationId": "4ce290071d96ac0aad4491fa24c5cc84", "parameters": [ { "name": "enrollment_id", "in": "path", "description": "Enrollment ID of the user", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully retrieved the enrolled test series", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "My enrolled Test series retrieved successfully" }, "test_series_image_path": { "type": "string", "example": "upload/testseries/" }, "instructor_image_path": { "type": "string", "example": "upload/instructors/" }, "my_test_series": { "type": "array", "items": { "properties": { "enrollment_id": { "type": "integer", "example": 1 }, "id": { "type": "integer", "example": 101 }, "name": { "type": "string", "example": "Sample Test Series" }, "image": { "type": "string", "example": "sample.jpg" }, "instructor": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Instructor Name" }, "image": { "type": "string", "example": "instructor.jpg" } }, "type": "object" }, "questions_count": { "type": "integer", "example": 50 }, "total_time": { "type": "integer", "example": 120 }, "category_id": { "type": "integer", "example": 1 }, "testseries_slug": { "type": "string", "example": "sample-test-series" }, "instructions": { "type": "string", "example": "Follow the instructions carefully" }, "short_description": { "type": "string", "example": "A sample test series" }, "negative_marks": { "type": "integer", "example": 1 }, "per_ques_mark": { "type": "integer", "example": 5 }, "max_questions": { "type": "integer", "example": 100 }, "attempt_per_stud": { "type": "integer", "example": 3 }, "tseries_verif_status": { "type": "integer", "example": 1 }, "price": { "type": "number", "format": "float", "example": 49.99 }, "days": { "type": "integer", "example": 30 }, "type": { "type": "string", "example": "Full Test Series" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-11-13T12:00:00Z" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series or enrollment not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Enrolled test series not found" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "An error occurred", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/bundle-testseries-questions/{enrollment_id}/{testseries_id}": { "get": { "tags": [ "user" ], "summary": "Get questions for a bundle test series", "description": "Retrieve questions and their details for a specific test series in a bundle.", "operationId": "getBundleTestSeriesQuestions", "parameters": [ { "name": "enrollment_id", "in": "path", "description": "The ID of the test series enrollment", "required": true, "schema": { "type": "integer" } }, { "name": "testseries_id", "in": "path", "description": "The ID of the test series", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful retrieval of test series questions", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Questions retrieved successfully" }, "total_section": { "type": "integer", "example": 1 }, "totalQuestions": { "type": "integer", "example": 40 }, "totalTime": { "type": "string", "example": "60" }, "per_question_mark": { "type": "integer", "example": 4 }, "totalMarks": { "type": "integer", "example": 160 }, "sections": { "type": "array", "items": { "properties": { "section_id": { "type": "integer", "example": 48 }, "section_title": { "type": "string", "example": "PSB Class 6 Scholarship Test" }, "enrollment_id": { "type": "integer", "example": 7 }, "bundle_id": { "type": "integer", "example": 57 }, "bundle_testseries_name": { "type": "string", "example": "BPS School Package" }, "section_total_question": { "type": "integer", "example": 40 }, "type": { "type": "string", "example": "testseries" }, "questions": { "type": "array", "items": { "properties": { "testseries_question_id": { "type": "integer", "example": 906 }, "testseries_id": { "type": "integer", "example": 48 }, "testseries_priority": { "type": "string", "example": "high" }, "question_id": { "type": "integer", "example": 42151 }, "question_text": { "type": "string", "example": "

The words Satyameva Jayate in the State Emblem of India have been adopted from which one of the following?

" }, "question_marks": { "type": "integer", "example": 1 }, "answer_type": { "type": "string", "example": "radio" }, "is_integertype": { "type": "boolean", "example": false }, "question_status": { "type": "integer", "example": 0 }, "enable_clear": { "type": "boolean", "example": false }, "start_time": { "type": "string", "example": "" }, "end_time": { "type": "string", "example": "" }, "options": { "type": "array", "items": { "properties": { "option_id": { "type": "integer", "example": 101948 }, "is_selected": { "type": "boolean", "example": false }, "option_text": { "type": "string", "example": "

Maitreyi Upanishad

" } }, "type": "object" } }, "user_answer": { "type": "string", "example": null, "nullable": true }, "question_mark": { "type": "integer", "example": 1 }, "ques_seq": { "type": "integer", "example": 0 } }, "type": "object" } } }, "type": "object" } }, "developer_information_msg": { "type": "string", "example": "Developer Information: 'radio' = Single-choice, 'checkbox' = Multiple-choice." } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series or enrollment not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Test series not found" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Exception message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/test_series_heading": { "get": { "tags": [ "user" ], "summary": "Get test series headings for the authenticated user", "description": "Returns a list of test series headings including static and user-associated groups.", "operationId": "getTestSeriesHeading", "responses": { "200": { "description": "Test series heading retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Test series heading retrieved successfully" }, "my_test_series_heading": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "0001" }, "name": { "type": "string", "example": "Bundle" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "An error occurred while processing your request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Error details here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/my_test_series_by_type/{group_id}": { "get": { "tags": [ "user" ], "summary": "Fetch My Test Series by Type", "description": "Retrieves the user's enrolled test series based on the specified type from their associated groups.", "operationId": "MyTest_Series_ByType", "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group to fetch the test series for.", "required": true, "schema": { "type": "string", "example": "0001" } } ], "responses": { "200": { "description": "Successfully retrieved test series", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "enrollment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "enroll_type": { "type": "string", "example": "testseries" }, "testseries_id": { "type": "integer" }, "plan_id": { "type": "integer", "nullable": true }, "pay_id": { "type": "integer", "nullable": true }, "start_date": { "type": "string", "format": "date-time", "example": "2024-10-17T06:27:38.000000Z" }, "end_date": { "type": "string", "format": "date-time", "example": "2024-11-16T06:27:38.000000Z" }, "enrollment_days": { "type": "integer", "example": 30 }, "enroll_by": { "type": "integer" }, "enroll_status": { "type": "string", "example": "1" }, "test_start_time": { "type": "string", "format": "date-time", "nullable": true }, "test_progress_time": { "type": "string", "format": "date-time", "nullable": true }, "test_end_time": { "type": "string", "format": "date-time", "nullable": true }, "test_submit_time": { "type": "string", "format": "date-time", "nullable": true }, "enrollment_created_at": { "type": "string", "format": "date-time", "example": "2024-10-17 06:27:38" }, "test_series": { "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "name": { "type": "string", "example": "Social Science Section (class -10) Test-3" }, "testseries_image": { "type": "string", "example": "" }, "category_id": { "type": "string", "example": "79,347" }, "testseries_slug": { "type": "string", "example": "social-science-section-(class--10)-test-3" }, "instructions": { "type": "string", "example": "na" }, "short_description": { "type": "string", "example": "na" }, "total_time": { "type": "string", "example": "10" }, "negative_marks": { "type": "string", "example": "1" }, "per_ques_mark": { "type": "integer", "example": 4 }, "max_questions": { "type": "integer", "nullable": true }, "attempt_per_stud": { "type": "string", "example": "2" }, "tseries_verif_status": { "type": "string", "example": "approved" }, "price": { "type": "string", "example": "5" }, "days": { "type": "integer", "example": 30 }, "type": { "type": "string", "example": "section" }, "created_at": { "type": "string", "format": "date-time", "example": "2023-11-11T15:36:43.000000Z" }, "instructor_detail": { "properties": { "id": { "type": "integer" }, "name": { "type": "string", "example": "admin" }, "image": { "type": "string", "example": "IMG_20200616_191746879.jpg" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access. Please log in." } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No associated groups found or invalid group ID", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "No associated groups found for this user." } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Invalid group ID provided", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Invalid group ID provided." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "An error occurred while processing the request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Error details here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/my_test_series_detail/{enrollment_id}/{testseries_id}": { "get": { "tags": [ "user" ], "summary": "Retrieve details of a single or all test series enrollment for the authenticated user", "description": "Fetches details of a specific test series enrollment or all test series if testseries_id is 0.", "operationId": "84570485922a95839989d39f63c1200a", "parameters": [ { "name": "enrollment_id", "in": "path", "description": "ID of the enrollment to retrieve", "required": true, "schema": { "type": "integer" } }, { "name": "testseries_id", "in": "path", "description": "ID of the test series to retrieve. Use 0 to retrieve all test series under this enrollment.", "required": true, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Successfully retrieved test series enrollment detail", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Enrollment or Test Series not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Enrollment or Test Series not found" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/my_test_series_questions/{enrollment_id}": { "get": { "tags": [ "user" ], "summary": "Retrieve test series questions for the authenticated user", "description": "Fetches all questions from the enrolled test series for the authenticated user along with their respective options 0 = unattempted, 1 = skip, 2 = pending, 3 = clear, 4 = save.", "operationId": "8ef91f1b2f3eedfbd12dc883f3a3d8d5", "parameters": [ { "name": "enrollment_id", "in": "path", "description": "ID of the enrollment for which to fetch questions", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Successfully retrieved the test series questions", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Questions retrieved successfully" }, "developer_information_msg": { "type": "string", "example": "Developer Information: - 'radio' represents a Single-choice question (Single Answer). - 'checkbox' represents a Multiple-choice question (Multiple Answers). - 'textarea' represents a Subjective question (Free Text Answer)." }, "total_questions": { "type": "integer", "example": 10 }, "total_time": { "type": "integer", "example": 120 }, "total_marks": { "type": "integer", "example": 100 }, "test_series_questions": { "type": "array", "items": { "properties": { "testseries_question_id": { "type": "integer", "example": 1 }, "question_id": { "type": "integer", "example": 101 }, "question_text": { "type": "string", "example": "What is the capital of France?" }, "answer_type": { "type": "string", "example": "radio" }, "is_integertype": { "type": "boolean", "example": true }, "question_status": { "type": "integer", "example": 1 }, "is_selected": { "type": "boolean", "example": true }, "options": { "type": "array", "items": { "properties": { "option_id": { "type": "integer", "example": 1 }, "option_text": { "type": "string", "example": "Paris" } }, "type": "object" } }, "question_mark": { "type": "integer", "example": 5 }, "ques_seq": { "type": "integer", "example": 1 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series enrollment not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Test series Enrollment not found" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Error details here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/my_test_series_questions/v2/{enrollment_id}": { "get": { "tags": [ "user" ], "summary": "Retrieve test series questions by enrollment ID", "description": "This endpoint retrieves the test series questions for a specific enrollment based on the user's authentication token and enrollment ID.", "operationId": "aec75840587485a447e2b9342af00368", "parameters": [ { "name": "enrollment_id", "in": "path", "description": "The ID of the test series enrollment", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Questions retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Questions retrieved successfully" }, "developer_information_msg": { "type": "string", "example": "Developer Information: 'radio' represents ..." }, "total_questions": { "type": "integer", "example": 50 }, "total_time": { "type": "string", "example": "30" }, "total_marks": { "type": "integer", "example": 50 }, "test_series_questions": { "type": "array", "items": { "type": "array", "items": { "properties": { "section_title": { "type": "string", "example": "Section 1" }, "testseries_question_id": { "type": "integer", "example": 1 }, "question_id": { "type": "integer", "example": 101 }, "question_text": { "type": "string", "example": "What is the capital of France?" }, "answer_type": { "type": "string", "example": "radio" }, "is_integertype": { "type": "boolean", "example": false }, "options": { "type": "array", "items": { "properties": { "option_id": { "type": "integer", "example": 1 }, "is_selected": { "type": "boolean", "example": false }, "option_text": { "type": "string", "example": "Paris" } }, "type": "object" } }, "question_mark": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series Enrollment not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Test series Enrollment not found" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Error message details" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/my_test_series_submit_single_question": { "post": { "tags": [ "user" ], "summary": "Submit a single question for a test series", "description": "Submit the status and answer (if applicable) for a specific question in a test series. The endpoint handles various question statuses: Skipped, Pending, Cleared, and Submitted.", "operationId": "TestSeriesSingleQuestionSubmit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "test_series_questions" ], "properties": { "test_series_questions": { "type": "array", "items": { "properties": { "testseries_id": { "description": "ID of the test series", "type": "integer", "example": 1 }, "question_id": { "description": "ID of the question", "type": "integer", "example": 1 }, "question_status": { "description": "Status of the question: 1=Skipped, 2=Pending, 3=Cleared, 4=Submitted", "type": "integer", "enum": [ 1, 2, 3, 4 ], "example": 4 }, "start_time": { "description": "Start time of answering the question", "type": "string", "format": "date-time", "example": "2023-09-27T07:40:25Z" }, "end_time": { "description": "End time of answering the question", "type": "string", "format": "date-time", "example": "2023-09-27T07:45:25Z" }, "is_integertype": { "description": "Indicates if the question requires integer only input", "type": "boolean", "example": false }, "answer_type": { "description": "Type of answer expected (e.g., multiple_choice, true_false)", "type": "string", "example": "multiple_choice" }, "options": { "type": "array", "items": { "properties": { "option_id": { "description": "ID of the option", "type": "integer", "example": 1 }, "is_selected": { "description": "Indicates if this option is selected", "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful submission of the question.", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Indicates request success", "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Question submitted successfully" }, "user_id": { "type": "integer", "example": 1 }, "testseries_id": { "type": "integer", "example": 1 }, "question_id": { "type": "integer", "example": 1 }, "answer_id": { "description": "ID of the selected answer option", "type": "integer", "example": 1 }, "total_time_spent": { "description": "Total time spent on the question", "type": "integer", "example": 30 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing the request" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/test-series/check-exam-time": { "post": { "tags": [ "Test Series" ], "summary": "Check if the user can start the exam for a specific test series", "description": "Validates enrollment, test series status, and user's attempt history.", "operationId": "checkExamTime", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "enrollment_id": { "type": "integer", "example": 1 }, "testseries_id": { "type": "integer", "example": 0 } }, "type": "object" } } } }, "responses": { "200": { "description": "User can start the exam now.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "You can start the exam now." } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "The test series is no longer available for attempts or not available within the scheduled time frame", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The test series is no longer available for attempts." } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Enrollment or test series not found or exceeded attempts", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Test series Enrollment not found" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "An error occurred while processing your request.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Exception Message here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/my_test_series_submit_single_question_v2": { "post": { "tags": [ "user" ], "summary": "Submit a single question for a test series", "description": "Submit the status and answer (if applicable) for a specific question in a test series.", "operationId": "SubmitSingleQuestionTestSeries", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "test_series_questions" ], "properties": { "test_series_questions": { "type": "array", "items": { "properties": { "testseries_id": { "description": "ID of the test series", "type": "integer", "example": 1 }, "question_id": { "description": "ID of the question", "type": "integer", "example": 1 }, "question_status": { "description": "Status of the question: 1=Skipped, 2=Pending, 3=Cleared, 4=Submitted", "type": "integer", "enum": [ 1, 2, 3, 4 ], "example": 4 }, "start_time": { "description": "Start time of answering the question", "type": "string", "format": "date-time", "example": "2023-09-27T07:40:25Z" }, "end_time": { "description": "End time of answering the question", "type": "string", "format": "date-time", "example": "2023-09-27T07:45:25Z" }, "is_integertype": { "description": "Indicates if the question requires integer only input", "type": "boolean", "example": false }, "answer_type": { "description": "Type of answer expected (e.g., multiple_choice, true_false)", "type": "string", "example": "multiple_choice" }, "options": { "type": "array", "items": { "properties": { "option_id": { "description": "ID of the option", "type": "integer", "example": 1 }, "is_selected": { "description": "Indicates if this option is selected", "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful submission of the question.", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Indicates request success", "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Question submitted successfully" }, "user_id": { "type": "integer", "example": 1 }, "testseries_id": { "type": "integer", "example": 1 }, "question_id": { "type": "integer", "example": 1 }, "answer_id": { "description": "ID of the selected answer option", "type": "integer", "example": 1 }, "total_time_spent": { "description": "Total time spent on the question", "type": "integer", "example": 30 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing the request" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/my_test_series_submit_all_question": { "post": { "tags": [ "user" ], "summary": "Submit all questions for a test series", "description": "This endpoint allows a user to submit the status and answer for specific questions in a test series. It handles various statuses: Skipped, Pending, Cleared, and Submitted.", "operationId": "TestSeriesSingleQuestionSubmitV1", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "test_series_questions" ], "properties": { "test_series_questions": { "type": "array", "items": { "properties": { "testseries_id": { "description": "ID of the test series", "type": "integer", "example": 1 }, "question_id": { "description": "ID of the question", "type": "integer", "example": 1 }, "question_status": { "description": "1=Skipped, 2=Pending, 3=Cleared, 4=Submitted", "type": "integer", "enum": [ 1, 2, 3, 4 ], "example": 4 }, "start_time": { "description": "Start time of answering the question", "type": "string", "format": "date-time", "example": "2023-09-27T07:40:25Z" }, "end_time": { "description": "End time of answering the question", "type": "string", "format": "date-time", "example": "2023-09-27T07:45:25Z" }, "options": { "type": "array", "items": { "properties": { "option_id": { "description": "ID of the option", "type": "integer", "example": 1 }, "is_selected": { "description": "Indicates if this option is selected", "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful submission of the exam.", "content": { "application/json": { "schema": { "properties": { "status": { "description": "True if submission is successful", "type": "boolean", "example": true }, "data": { "properties": { "message": { "description": "Success message", "type": "string", "example": "Exam submitted successfully." }, "responses": { "type": "array", "items": { "properties": { "question_id": { "description": "ID of the question", "type": "integer", "example": 1 }, "question_message": { "description": "Message regarding the question status", "type": "string", "example": "Question marked as submitted." }, "answer_id": { "description": "ID of the submitted answer, if applicable", "type": "integer", "example": 1 } }, "type": "object" } }, "testseries_result": { "properties": { "testseries_id": { "description": "ID of the test series", "type": "integer", "example": 1 }, "result_submited": { "description": "Indicates if the result was submitted", "type": "boolean", "example": true }, "updated_at": { "description": "Time when the result was updated", "type": "string", "format": "date-time", "example": "2023-09-27T07:50:25Z" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request, e.g., test series not found or already submitted.", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Indicates failure", "type": "boolean", "example": false }, "data": { "properties": { "message": { "description": "Error message", "type": "string", "example": "test series not found or already submitted" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "An error occurred while processing the request.", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Indicates failure", "type": "boolean", "example": false }, "data": { "properties": { "message": { "description": "Error message", "type": "string", "example": "An error occurred while processing the request" }, "error": { "type": "string", "example": "Detailed error message if available" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/my_test_series_submit_all_question_v3": { "post": { "tags": [ "user" ], "summary": "Submit all questions for a test series", "description": "This endpoint allows a user to submit the status and answer for specific questions in a test series. It handles various statuses: Skipped, Pending, Cleared, and Submitted.", "operationId": "TestSeriesAllQuestionSubmitV3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "test_series_questions" ], "properties": { "test_series_questions": { "type": "array", "items": { "properties": { "testseries_id": { "description": "ID of the test series", "type": "integer", "example": 1 }, "question_id": { "description": "ID of the question", "type": "integer", "example": 1 }, "question_status": { "description": "1=Skipped, 2=Pending, 3=Cleared, 4=Submitted", "type": "integer", "enum": [ 1, 2, 3, 4 ], "example": 4 }, "start_time": { "description": "Start time of answering the question", "type": "string", "format": "date-time", "example": "2023-09-27T07:40:25Z" }, "end_time": { "description": "End time of answering the question", "type": "string", "format": "date-time", "example": "2023-09-27T07:45:25Z" }, "options": { "type": "array", "items": { "properties": { "option_id": { "description": "ID of the option", "type": "integer", "example": 1 }, "is_selected": { "description": "Indicates if this option is selected", "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful submission of the exam.", "content": { "application/json": { "schema": { "properties": { "status": { "description": "True if submission is successful", "type": "boolean", "example": true }, "data": { "properties": { "message": { "description": "Success message", "type": "string", "example": "Exam submitted successfully." }, "responses": { "type": "array", "items": { "properties": { "question_id": { "description": "ID of the question", "type": "integer", "example": 1 }, "question_message": { "description": "Message regarding the question status", "type": "string", "example": "Question marked as submitted." }, "answer_id": { "description": "ID of the submitted answer, if applicable", "type": "integer", "example": 1 } }, "type": "object" } }, "testseries_result": { "properties": { "testseries_id": { "description": "ID of the test series", "type": "integer", "example": 1 }, "result_submited": { "description": "Indicates if the result was submitted", "type": "boolean", "example": true }, "updated_at": { "description": "Time when the result was updated", "type": "string", "format": "date-time", "example": "2023-09-27T07:50:25Z" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request, e.g., test series not found or already submitted.", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Indicates failure", "type": "boolean", "example": false }, "data": { "properties": { "message": { "description": "Error message", "type": "string", "example": "Test series not found or already submitted" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "An error occurred while processing the request.", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Indicates failure", "type": "boolean", "example": false }, "data": { "properties": { "message": { "description": "Error message", "type": "string", "example": "An error occurred while processing the request" }, "error": { "type": "string", "example": "Detailed error message if available" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/my_test_series_submit_exam": { "post": { "tags": [ "user" ], "summary": "Submit user's test series exam", "description": "This API submits the user's test series exam. The user must be authenticated via Sanctum. The request must include a valid test series ID and enrollment ID. The test result will be marked as submitted if not already submitted.", "operationId": "submitTestSeriesExam", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "testseries_id", "enrollment_id" ], "properties": { "testseries_id": { "description": "ID of the test series to be submitted", "type": "integer", "example": 1 }, "enrollment_id": { "description": "ID of the test series enrollment", "type": "integer", "example": 10 } }, "type": "object" } } } }, "responses": { "200": { "description": "Exam submitted successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Exam submitted successfully" }, "show_result": { "type": "boolean", "example": true }, "result_link": { "type": "string", "example": "/user/result" }, "testseries_result": { "properties": { "id": { "type": "integer", "example": 45 }, "obtained_marks": { "type": "number", "format": "float", "example": 75 }, "result_submited": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad Request - Validation failed or exam not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Validation failed or test series not found or already submitted" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - User not authenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not Found - Enrollment or test series not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Enrollment ID not found or test series not found" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server Error - An error occurred while submitting the exam", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while submitting the exam. Please try again later." } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/my_test_series_history/{enrollment_id}/{testseries_id}": { "get": { "tags": [ "user" ], "summary": "Get Test Series History", "description": "Fetches the test series history for a specific enrollment and test series.\n * If the test series ID is not provided, it defaults to 0, returning all test series history for the enrollment.", "operationId": "832a9ce3b9e615a87b04bba03a5f9f24", "parameters": [ { "name": "enrollment_id", "in": "path", "description": "ID of the enrollment", "required": true, "schema": { "type": "integer" } }, { "name": "testseries_id", "in": "path", "description": "ID of the test series (optional, defaults to 0 if not provided)", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Test Series History retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Test Series History retrieved successfully" }, "test_series_name": { "type": "string", "example": "Mathematics Series" }, "show_result": { "type": "boolean", "example": true }, "test_series_history": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "enrollment_id": { "type": "integer", "example": 1001 }, "testseries_id": { "type": "integer", "example": 2001 }, "user_id": { "type": "integer", "example": 10 }, "result_submited": { "type": "boolean", "example": true }, "result_link": { "type": "string", "example": "https://example.com/user/result/1" } }, "type": "object" } }, "total_attempt_per_student": { "type": "string", "example": "5" }, "total_taken_attempts": { "type": "integer", "example": 3 }, "total_remaining_attempts": { "type": "integer", "example": 2 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series not found or not enrolled", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Test series not found or not enrolled" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Exception message here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/my_test_series_history_v2/{enrollment_id}/{testseries_id}": { "get": { "tags": [ "user" ], "summary": "Fetch Test Series History", "description": "Retrieve the test series history for a specific user, including attempts, results, and remaining attempts.", "operationId": "TestSeriesHistoryV2", "parameters": [ { "name": "enrollment_id", "in": "path", "description": "The ID of the test series enrollment.", "required": true, "schema": { "type": "integer" } }, { "name": "testseries_id", "in": "path", "description": "The ID of the test series.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Test Series History retrieved successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Test Series History retrieved successfully" }, "test_series_name": { "type": "string", "example": "Math Test Series" }, "show_result": { "type": "boolean", "example": true }, "test_series_history": { "type": "array", "items": { "type": "object" } }, "total_attempt_per_student": { "type": "string", "example": "3" }, "total_taken_attempts": { "type": "integer", "example": 1 }, "total_remaining_attempts": { "type": "integer", "example": 2 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Enrollment or Test Series not found.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Test series not Enrollment" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "An error occurred while processing your request.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Exception message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/order-history": { "get": { "tags": [ "user" ], "summary": "Get user order history", "description": "Retrieve the authenticated user's order history. Only successful orders of students are returned.", "operationId": "getOrderHistory", "responses": { "200": { "description": "Order history retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Order history retrieved successfully" }, "orders": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 1 }, "order_id": { "type": "string", "example": "ORD123" }, "payment_id": { "type": "string", "example": "PAY456" }, "amount": { "type": "number", "format": "float", "example": 100.5 }, "status": { "type": "string", "example": "success" }, "testSeries": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Test Series 1" }, "testseries_image": { "type": "string", "example": "test_series_image_url" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No order history found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "No order history found" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "An error occurred while processing your request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing your request." }, "error": { "type": "string", "example": "Error details here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/contact_us/": { "post": { "tags": [ "Utility" ], "summary": "Submit contact us form", "operationId": "012d8280bda915726980585df5724a42", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "subject", "message" ], "properties": { "name": { "type": "string" }, "email_id": { "type": "string", "format": "email" }, "subject": { "type": "string" }, "message": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success message" }, "400": { "description": "Validation error" } } } }, "/api/user/get-topics": { "get": { "tags": [ "notification" ], "summary": "Get all topics with subscription status", "description": "Retrieve all topics available in the database along with their subscription status for the authenticated user.", "operationId": "getTopics", "responses": { "200": { "description": "Topics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Topics retrieved successfully." }, "topics": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "topic_name": { "type": "string", "example": "Introduction to Biology" }, "description": { "type": "string", "example": "A foundational topic covering basic biology concepts." }, "is_subscribed": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2023-01-01T12:34:56Z" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No topics found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "No topics found." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "An error occurred while fetching topics", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while fetching topics." }, "error": { "type": "string", "example": "Error details here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/home-dashboard-section-position": { "get": { "tags": [ "user" ], "summary": "Retrieve dashboard sections", "description": "Fetches a list of dashboard sections for the authenticated user, ordered by position.", "operationId": "4f9e7530ba4dee5f6e74ebf3ea80de4b", "responses": { "200": { "description": "Successfully retrieved dashboard sections", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "topics": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "section_name": { "type": "string", "example": "Featured Products" }, "position": { "type": "integer", "example": 1 }, "enable": { "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No sections found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "No Section found." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error occurred while fetching topics", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while fetching topics." }, "error": { "type": "string", "example": "Error details here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/topic-subscription": { "post": { "tags": [ "notification" ], "summary": "Manage topic subscription", "description": "Subscribe or unsubscribe a user to a specific topic. If the subscription exists, it will be updated. If not, a new subscription will be created.", "operationId": "TopicSubscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "topic_id", "subscribed" ], "properties": { "topic_id": { "type": "integer", "example": 101 }, "subscribed": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Subscription updated or removed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Topic subscription removed successfully." }, "subscription": { "properties": { "user_id": { "type": "integer", "example": 1 }, "topic_id": { "type": "integer", "example": 101 }, "subscribed": { "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "201": { "description": "Subscription created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Topic subscription created successfully." }, "subscription": { "properties": { "user_id": { "type": "integer", "example": 1 }, "topic_id": { "type": "integer", "example": 101 }, "subscribed": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Validation error." }, "errors": { "type": "object", "additionalProperties": { "type": "string", "example": "The topic_id field is required.", "property": null } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Topic not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "The specified topic does not exist." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while processing the topic subscription." }, "error": { "type": "string", "example": "Error details here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/get-notifications": { "get": { "tags": [ "notification" ], "summary": "Get user notifications", "description": "Retrieve paginated notifications for the authenticated user, filtered by receiver_id or topic subscriptions.", "operationId": "getNotifications", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 2 } } ], "responses": { "200": { "description": "Notifications retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Notifications retrieved successfully." }, "notifications": { "properties": { "current_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 4 }, "topic_id": { "type": "integer", "example": 0 }, "sender_id": { "type": "integer", "example": 1 }, "receiver_id": { "type": "integer", "example": 225 }, "message": { "type": "string", "example": "You have a new message." }, "image": { "type": "string", "example": null }, "status": { "type": "integer", "example": 1 }, "created_at": { "type": "string", "format": "date-time", "example": "2023-06-09T19:06:25.000000Z" } }, "type": "object" } }, "first_page_url": { "type": "string", "example": "http://localhost:8000/api/user/get-notifications?page=1" }, "last_page": { "type": "integer", "example": 3 }, "last_page_url": { "type": "string", "example": "http://localhost:8000/api/user/get-notifications?page=3" }, "next_page_url": { "type": "string", "example": "http://localhost:8000/api/user/get-notifications?page=2" }, "path": { "type": "string", "example": "http://localhost:8000/api/user/get-notifications" }, "per_page": { "type": "integer", "example": 5 }, "prev_page_url": { "type": "string", "example": null }, "total": { "type": "integer", "example": 11 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No notifications found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "No notifications found." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "An error occurred while fetching notifications", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while fetching notifications." }, "error": { "type": "string", "example": "Error details here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/notifications-read/{id}": { "get": { "tags": [ "notification" ], "summary": "Mark notification as read", "description": "Set the status of a notification to read (1) for the authenticated user.", "operationId": "markNotificationAsRead", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification to be marked as read", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notification marked as read successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Notification marked as read successfully." } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Notification not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Notification not found." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "An error occurred while marking notification as read", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while marking notification as read." }, "error": { "type": "string", "example": "Error details here" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/notifications/delete/{id}": { "get": { "tags": [ "Notifications" ], "summary": "Delete a user notification", "description": "Delete a specific notification by its ID if it belongs to the authenticated user.", "operationId": "deleteNotification", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notification deleted successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Notification deleted successfully." } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Notification not found.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Notification not found." } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "An error occurred while deleting the notification.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while deleting the notification." }, "error": { "type": "string", "example": "Exception message" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/all_sliders": { "get": { "tags": [ "user" ], "summary": "Get all sliders", "description": "Fetches all sliders including details like name, description, link, start date, end date, status, and timestamps.", "operationId": "e71082e18bf0bc3a1a5debf83dfe339e", "responses": { "200": { "description": "Successfully retrieved sliders", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Slider 1" }, "description": { "type": "string", "example": "This is a description of slider 1." }, "type": { "type": "string", "example": "web,testseries" }, "link": { "type": "string", "example": "https://example.com" }, "start_date": { "type": "string", "format": "date", "example": "2024-09-01" }, "end_date": { "type": "string", "format": "date", "example": "2024-09-30" }, "status": { "type": "string", "example": "active" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-08-01T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-08-15T12:00:00Z" } }, "type": "object" } } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/test-email-user/{email}": { "get": { "tags": [ "Utility" ], "summary": "Send test OTP email", "operationId": "09b3717f3dbbc07047ca9e5e56e09550", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Email sent successfully" }, "400": { "description": "Invalid email format" } } } }, "/api/v2/teacher/ai/generate-batch": { "post": { "tags": [ "AI Question Generation V2" ], "summary": "Batch generate AI questions for multiple topics (asynchronous)", "description": "Creates an asynchronous batch job to generate AI questions for large number of topics. Uses queue processing. Max 100 topics, max 10 questions per topic. Deducts coins upfront and refunds for failed generations.", "operationId": "326f8d2f0f56081ba6636c182ca8370a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "class_id", "subject_id", "topic_ids", "questions_per_topic", "question_type", "answer_type", "marks" ], "properties": { "class_id": { "description": "Class ID from lk_category", "type": "integer", "example": 1 }, "subject_id": { "description": "Subject ID from lk_category", "type": "integer", "example": 5 }, "topic_ids": { "description": "Array of topic IDs (max 100)", "type": "array", "items": { "type": "integer" }, "example": [ 10, 11, 12, 13, 14 ] }, "questions_per_topic": { "description": "Number of questions per topic (1-10)", "type": "integer", "example": 5 }, "question_type": { "description": "Question difficulty level", "type": "string", "enum": [ "Easy", "Medium", "Difficult" ], "example": "Medium" }, "answer_type": { "description": "Answer type for questions", "type": "string", "enum": [ "radio", "checkbox", "textarea" ], "example": "radio" }, "marks": { "description": "Marks per question (1-10)", "type": "integer", "example": 2 } }, "type": "object" } } } }, "responses": { "200": { "description": "Batch job created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Batch generation started successfully" }, "data": { "properties": { "job_id": { "type": "string", "example": "batch_1699012345_abc123" }, "batch_id": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "pending" }, "total_questions": { "type": "integer", "example": 50 }, "topics_count": { "type": "integer", "example": 10 }, "coins_deducted": { "type": "integer", "example": 50 }, "question_type": { "type": "string", "example": "Medium" }, "answer_type": { "type": "string", "example": "radio" }, "marks": { "type": "integer", "example": 2 }, "estimated_time": { "type": "string", "example": "5-10 minutes" }, "status_url": { "type": "string", "example": "/api/v2/teacher/ai/batch/batch_1699012345_abc123" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request - Some topics are invalid or inactive" }, "402": { "description": "Payment required - Insufficient coins" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" }, "500": { "description": "Payment processing failed" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/teacher/ai/batch-history": { "get": { "tags": [ "AI Question Generation V2" ], "summary": "Get batch generation history", "description": "Retrieve batch generation history with topic details for the authenticated user", "operationId": "07f4e7104c9d081104aca35e8c08bca3", "parameters": [ { "name": "limit", "in": "query", "description": "Number of records to retrieve", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 50, "example": 10 } } ], "responses": { "200": { "description": "Batch history retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Batch history retrieved successfully" }, "data": { "properties": { "batches": { "type": "array", "items": { "type": "object" } }, "total_count": { "type": "integer", "example": 10 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/teacher/ai/batch/{jobId}": { "get": { "tags": [ "AI Question Generation V2" ], "summary": "Get batch generation status", "description": "Check the status of a batch question generation job", "operationId": "d6e574b1861952c9a41224bb2e21f353", "parameters": [ { "name": "jobId", "in": "path", "description": "Batch job ID", "required": true, "schema": { "type": "string", "example": "batch_1699012345_abc123" } } ], "responses": { "200": { "description": "Status retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Batch status retrieved successfully" }, "data": { "properties": { "job_id": { "type": "string", "example": "batch_1699012345_abc123" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "partial" ], "example": "completed" }, "progress": { "type": "number", "format": "float", "example": 100 }, "total_requested": { "type": "integer", "example": 15 }, "generated": { "type": "integer", "example": 15 }, "failed": { "type": "integer", "example": 0 }, "coins_deducted": { "type": "integer", "example": 15 }, "coins_refunded": { "type": "integer", "example": 0 }, "generated_question_ids": { "type": "array", "items": { "type": "integer" } }, "failed_topics": { "type": "array", "items": { "type": "object" } }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "duration": { "type": "string", "example": "2 minutes" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Batch not found" }, "403": { "description": "Forbidden - Not your batch" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/teacher/ai/batches": { "get": { "tags": [ "AI Question Generation V2" ], "summary": "List all batch generation jobs", "description": "Get list of all batch generation jobs for the authenticated user", "operationId": "544b0f16437494fd7b9530fd49cc4874", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "partial" ] } }, { "name": "limit", "in": "query", "description": "Number of results per page", "required": false, "schema": { "type": "integer", "default": 20, "example": 20 } } ], "responses": { "200": { "description": "Batches retrieved successfully" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/groups": { "get": { "tags": [ "Tutor V2 - Group Management" ], "summary": "List all batches/groups with assigned teachers", "description": "Retrieves a paginated list of all batches/groups belonging to the authenticated tutor, including information about which teachers are assigned to each batch", "operationId": "v2ListGroups", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "search", "in": "query", "description": "Search groups by name", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Groups retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Groups retrieved successfully" }, "data": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Not a tutor" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/groups/{id}": { "put": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Update batch/group", "description": "Updates the details of an existing batch/group", "operationId": "v2UpdateGroup", "parameters": [ { "name": "id", "in": "path", "description": "Group ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Class 10 - Section B" }, "class_id": { "type": "integer", "example": 86 }, "subject_ids": { "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Group updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Group updated successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Group not found" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/groups/{id}/class-subjects": { "get": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Get class and subjects for a group", "description": "Returns the class name and ID along with all selected subject IDs and names for the given group", "operationId": "v2GetGroupClassSubjects", "parameters": [ { "name": "id", "in": "path", "description": "Group ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Class and subjects retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Class and subjects retrieved successfully" }, "data": { "properties": { "class": { "properties": { "id": { "type": "integer", "example": 79 }, "name": { "type": "string", "example": "Class 10" } }, "type": "object" }, "subjects": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 86 }, "name": { "type": "string", "example": "Physics" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Group not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/question-bank/hierarchy": { "get": { "tags": [ "Tutor V2" ], "summary": "Get question hierarchy with counts", "description": "Returns hierarchical structure of Classes → Subjects → Topics with question counts. Cached for 1 hour.", "operationId": "8f785c3093128f94bfbe6c1b0dd5ef93", "parameters": [ { "name": "class_id", "in": "query", "description": "Filter by specific class ID", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "subject_id", "in": "query", "description": "Filter by specific subject ID", "required": false, "schema": { "type": "integer", "example": 5 } } ], "responses": { "200": { "description": "Hierarchy retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Question hierarchy retrieved successfully" }, "data": { "properties": { "classes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Class 10" }, "subjects": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "Mathematics" }, "topics": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 23 }, "name": { "type": "string", "example": "Algebra" }, "question_count": { "type": "integer", "example": 150 } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } }, "cache_enabled": { "type": "boolean", "example": true }, "cached_until": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - User is not a teacher" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/questions/{id}": { "put": { "tags": [ "Tutor V2" ], "summary": "Update a question", "description": "Update question text, options, correct answer, and solution. Teacher can only update their own questions.", "operationId": "e4a0126bedc658c8631f7a7911df0ec9", "parameters": [ { "name": "id", "in": "path", "description": "Question ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "question": { "type": "string", "example": "

What is the capital of France?

" }, "option_a": { "type": "string", "example": "

Paris

" }, "option_b": { "type": "string", "example": "

London

" }, "option_c": { "type": "string", "example": "

Berlin

" }, "option_d": { "type": "string", "example": "

Madrid

" }, "correct_answer": { "type": "string", "enum": [ "A", "B", "C", "D" ], "example": "A" }, "solution": { "type": "string", "example": "

Paris is the capital and most populous city of France.

" }, "marks": { "type": "number", "example": 1 }, "time": { "description": "Time in seconds", "type": "integer", "example": 60 } }, "type": "object" } } } }, "responses": { "200": { "description": "Question updated successfully" }, "403": { "description": "Forbidden - User is not authorized to update this question" }, "404": { "description": "Question not found" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Question Bank V2" ], "summary": "Soft delete a question", "description": "Soft delete a question. Prevents deletion if question is used in any active test series.", "operationId": "6384e04afa2e82691484ebd9de8ce1ef", "parameters": [ { "name": "id", "in": "path", "description": "Question ID", "required": true, "schema": { "type": "integer" } }, { "name": "force", "in": "query", "description": "Force delete even if used in tests (admin only)", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Question deleted successfully" }, "403": { "description": "Forbidden - User is not authorized" }, "404": { "description": "Question not found" }, "409": { "description": "Conflict - Question is used in active tests" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/questions/{id}/restore": { "post": { "tags": [ "Question Bank V2" ], "summary": "Restore a soft-deleted question", "description": "Restore a previously soft-deleted question", "operationId": "311fc8a507a93e260914b2e12ded5d99", "parameters": [ { "name": "id", "in": "path", "description": "Question ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Question restored successfully" }, "403": { "description": "Forbidden - User is not authorized" }, "404": { "description": "Question not found in trash" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/questions/{id}/history": { "get": { "tags": [ "Question Bank V2" ], "summary": "Get question audit history", "description": "Get the last 20 changes made to a question with user details", "operationId": "cc6e0203f43e90b1b9b770842297b52c", "parameters": [ { "name": "id", "in": "path", "description": "Question ID", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Number of records to retrieve (default: 20, max: 100)", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "History retrieved successfully" }, "403": { "description": "Forbidden - User is not authorized" }, "404": { "description": "Question not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/school/login": { "post": { "tags": [ "School V2" ], "summary": "School login with email and password", "description": "Authenticate school using email and password", "operationId": "schoolLogin", "requestBody": { "description": "Login credentials", "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password", "device_token_id" ], "properties": { "email": { "description": "School email address", "type": "string", "format": "email", "example": "school@example.com" }, "password": { "description": "School password", "type": "string", "format": "password", "example": "password123" }, "device_token_id": { "description": "Device token for push notifications", "type": "string", "example": "device_token_123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Login successful" }, "data": { "properties": { "user": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "ABC School" }, "email": { "type": "string", "example": "school@example.com" }, "mobile_no": { "type": "string", "example": "9876543210" }, "role_id": { "type": "integer", "example": 5 } }, "type": "object" }, "token": { "type": "string", "example": "1|abcdef123456..." } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "School not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "School not found" }, "error_code": { "type": "string", "example": "SCHOOL_NOT_FOUND" } }, "type": "object" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid password" }, "error_code": { "type": "string", "example": "INVALID_PASSWORD" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The email field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } } } } }, "/api/v2/school/profile": { "get": { "tags": [ "School V2" ], "summary": "Get authenticated school profile", "description": "Retrieve the profile information of the authenticated school", "operationId": "getSchoolProfile", "responses": { "200": { "description": "Profile retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "ABC School" }, "email": { "type": "string", "example": "school@example.com" }, "mobile_no": { "type": "string", "example": "9876543210" }, "role_id": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/school/batches/{batch_id}/assign-teacher": { "post": { "tags": [ "School V2" ], "summary": "Assign a teacher to a batch", "description": "Assign a teacher to a specific batch. The batch must belong to the authenticated school.", "operationId": "assignTeacherToBatch", "parameters": [ { "name": "batch_id", "in": "path", "description": "The ID of the batch (group)", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "description": "Teacher assignment details", "required": true, "content": { "application/json": { "schema": { "required": [ "teacher_id" ], "properties": { "teacher_id": { "description": "The ID of the teacher/tutor to assign", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "Teacher assigned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Teacher assigned to batch successfully" }, "data": { "properties": { "batch_id": { "type": "integer", "example": 1 }, "batch_name": { "type": "string", "example": "Class 10 Mathematics" }, "teacher_id": { "type": "integer", "example": 5 }, "teacher_name": { "type": "string", "example": "John Doe" }, "assigned_at": { "type": "string", "format": "datetime", "example": "2025-01-07T10:30:00Z" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Teacher already assigned to this batch", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Teacher is already assigned to this batch" }, "error_code": { "type": "string", "example": "TEACHER_ALREADY_ASSIGNED" } }, "type": "object" } } } }, "403": { "description": "Unauthorized - Batch does not belong to school", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This batch does not belong to your school" }, "error_code": { "type": "string", "example": "UNAUTHORIZED_BATCH_ACCESS" } }, "type": "object" } } } }, "404": { "description": "Batch or teacher not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch not found" }, "error_code": { "type": "string", "example": "BATCH_NOT_FOUND" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The teacher_id field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/school/dashboard": { "get": { "tags": [ "School V2" ], "summary": "Get school dashboard statistics", "description": "Retrieve dashboard statistics including total teachers, batches, and students for the authenticated school", "operationId": "getSchoolDashboard", "responses": { "200": { "description": "Dashboard statistics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "total_teachers": { "description": "Total number of teachers assigned to school batches", "type": "integer", "example": 25 }, "total_batches": { "description": "Total number of batches in the school", "type": "integer", "example": 12 }, "total_students": { "description": "Total number of students enrolled in school batches", "type": "integer", "example": 350 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Unauthorized - User is not a school", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized access. Only schools can access dashboard." }, "error_code": { "type": "string", "example": "UNAUTHORIZED_ACCESS" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/school/teachers": { "get": { "tags": [ "School V2" ], "summary": "Get list of teachers assigned to school batches", "description": "Retrieve a paginated list of all teachers who are assigned to batches belonging to the authenticated school", "operationId": "getSchoolTeachers", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1, "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15, "example": 15 } }, { "name": "search", "in": "query", "description": "Search teachers by name or email", "required": false, "schema": { "type": "string", "example": "John" } } ], "responses": { "200": { "description": "Teachers list retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Teachers retrieved successfully" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john.doe@example.com" }, "mobile_no": { "type": "string", "example": "9876543210" }, "batches_count": { "description": "Number of batches assigned to this teacher", "type": "integer", "example": 3 }, "batches": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Class 10 Mathematics" } }, "type": "object" } } }, "type": "object" } }, "pagination": { "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 3 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 42 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" }, "error_code": { "type": "string", "example": "UNAUTHENTICATED" } }, "type": "object" } } } }, "403": { "description": "Unauthorized - User is not a school", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized access. Only schools can access teachers list." }, "error_code": { "type": "string", "example": "UNAUTHORIZED_ACCESS" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/school/teachers/search": { "post": { "tags": [ "School V2" ], "summary": "Search for teachers by name or email", "description": "Search for teachers in the system by name or email address. Returns matching teachers that can be invited to join school batches.", "operationId": "searchTeachers", "requestBody": { "description": "Search query parameters", "required": true, "content": { "application/json": { "schema": { "required": [ "search_query" ], "properties": { "search_query": { "description": "Search term to match against teacher name or email", "type": "string", "example": "John" } }, "type": "object" } } } }, "responses": { "200": { "description": "Teachers search results", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Teachers search results" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 15 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john.doe@example.com" }, "mobile_no": { "type": "string", "example": "9876543210" }, "role_id": { "type": "integer", "example": 4 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" }, "error_code": { "type": "string", "example": "UNAUTHENTICATED" } }, "type": "object" } } } }, "403": { "description": "Unauthorized - User is not a school", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized access." }, "error_code": { "type": "string", "example": "UNAUTHORIZED_ACCESS" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The search_query field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/school/student/search": { "get": { "tags": [ "School V2" ], "summary": "Search for students by mobile number or email", "description": "Search for students in the system by mobile number or email address. Returns matching students that can be enrolled to school batches.", "operationId": "searchStudents", "parameters": [ { "name": "search_query", "in": "query", "description": "Search term to match against student mobile number or email", "required": true, "schema": { "type": "string", "example": "9876543210" } } ], "responses": { "200": { "description": "Students search results", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Students search results" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 25 }, "name": { "type": "string", "example": "Jane Smith" }, "email": { "type": "string", "example": "jane.smith@example.com" }, "mobile_no": { "type": "string", "example": "9876543210" }, "role_id": { "type": "integer", "example": 1 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" }, "error_code": { "type": "string", "example": "UNAUTHENTICATED" } }, "type": "object" } } } }, "403": { "description": "Unauthorized - User is not a school", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized access." }, "error_code": { "type": "string", "example": "UNAUTHORIZED_ACCESS" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The search_query field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/school/batches/{batch_id}/unassign-teacher/{teacher_id}": { "delete": { "tags": [ "School V2" ], "summary": "Unassign a teacher from a batch", "description": "Remove a teacher's assignment from a specific batch. The batch must belong to the authenticated school.", "operationId": "unassignTeacherFromBatch", "parameters": [ { "name": "batch_id", "in": "path", "description": "The ID of the batch (group)", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "teacher_id", "in": "path", "description": "The ID of the teacher/tutor to unassign", "required": true, "schema": { "type": "integer", "example": 5 } } ], "responses": { "200": { "description": "Teacher unassigned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Teacher unassigned from batch successfully" }, "data": { "properties": { "batch_id": { "type": "integer", "example": 1 }, "batch_name": { "type": "string", "example": "Class 10 Mathematics" }, "teacher_id": { "type": "integer", "example": 5 }, "teacher_name": { "type": "string", "example": "John Doe" }, "unassigned_at": { "type": "string", "format": "datetime", "example": "2025-01-12T10:30:00Z" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized - Batch does not belong to school", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This batch does not belong to your school" }, "error_code": { "type": "string", "example": "UNAUTHORIZED_BATCH_ACCESS" } }, "type": "object" } } } }, "404": { "description": "Batch, teacher, or assignment not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Teacher assignment not found in this batch" }, "error_code": { "type": "string", "example": "ASSIGNMENT_NOT_FOUND" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" }, "error_code": { "type": "string", "example": "UNAUTHENTICATED" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/school/profile/update": { "post": { "tags": [ "School V2" ], "summary": "Update school profile", "description": "Update the profile information of the authenticated school", "operationId": "updateSchoolProfile", "requestBody": { "description": "Profile fields to update", "required": false, "content": { "multipart/form-data": { "schema": { "properties": { "name": { "description": "School name", "type": "string", "example": "ABC School" }, "email": { "description": "School email", "type": "string", "format": "email", "example": "school@example.com" }, "mobile_no": { "description": "Mobile number (10 digits)", "type": "string", "example": "9876543210" }, "address": { "description": "School address", "type": "string", "example": "123 Main Street" }, "city": { "description": "City", "type": "string", "example": "Mumbai" }, "state": { "description": "State", "type": "string", "example": "Maharashtra" }, "pincode": { "description": "Pincode", "type": "string", "example": "400001" }, "image": { "description": "School logo image", "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" }, "data": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Unauthorized - User is not a school" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/school/testseries/update/status/{status}": { "post": { "tags": [ "School - Test Series" ], "summary": "Update test series verification status", "description": "Update the verification status of a test series (approved, rejected, or pending)", "operationId": "a9970a41a8a1f9ac8b776a89182b8e50", "parameters": [ { "name": "status", "in": "path", "description": "The verification status to set", "required": true, "schema": { "type": "string", "enum": [ "approved", "rejected", "pending" ], "example": "approved" } }, { "name": "id", "in": "query", "description": "Test series ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Test series status updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series status updated to approved successfully" } }, "type": "object" } } } }, "400": { "description": "Invalid status provided", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid status. Allowed values: approved, rejected, pending" } }, "type": "object" } } } }, "404": { "description": "Test series not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/student/question/doubt": { "post": { "tags": [ "Student" ], "summary": "Submit a doubt on a question", "description": "Allows a student to submit a doubt/query on a specific question", "operationId": "submitQuestionDoubt", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ques_id", "query" ], "properties": { "ques_id": { "description": "The ID of the question", "type": "integer", "example": 123 }, "query": { "description": "The doubt/query message (max 255 characters)", "type": "string", "example": "I don't understand the explanation for option B" } }, "type": "object" } } } }, "responses": { "201": { "description": "Doubt submitted successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Doubt submitted successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "ques_id": { "type": "integer", "example": 123 }, "query": { "type": "string", "example": "I don't understand the explanation for option B" }, "status": { "type": "string", "example": "pending" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Only students can submit doubts" }, "404": { "description": "Question not found" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/api/class/{class_id}/subjects": { "get": { "tags": [ "Subject & Topics with Class" ], "summary": "Get subjects by class availability", "description": "Return all subjects (lk_category.category_level = 'subject') that have at least one active question containing the subject id AND the given class id in the same questions.category_id CSV field.", "operationId": "e00ba03f0bbbef43e8ac1119f71d70cd", "parameters": [ { "name": "class_id", "in": "path", "description": "ID of the class", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 81 }, "name": { "type": "string", "example": "Mathematics" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Invalid class_id or no subjects found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid class_id" } }, "type": "object" } } } } } } }, "/api/class/{class_id}/subject/{subject_id}/topics": { "get": { "tags": [ "Subject & Topics with Class" ], "summary": "Get topics and chapters by class and subject availability", "description": "Return all topics and chapters (lk_category.category_level IN ('chapter', 'topic')) that have at least one active question containing the category id AND the given class id AND the given subject id in the same questions.category_id CSV field.", "operationId": "af36883e17734906d2d027457c2b1589", "parameters": [ { "name": "class_id", "in": "path", "description": "ID of the class", "required": true, "schema": { "type": "integer" } }, { "name": "subject_id", "in": "path", "description": "ID of the subject", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 113 }, "name": { "type": "string", "example": "Algebraic Expressions" }, "type": { "type": "string", "example": "topic" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Invalid class_id, subject_id or no topics found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid class_id or subject_id" } }, "type": "object" } } } } } } }, "/api/v2/tutor/send-otp": { "post": { "tags": [ "Tutor V2" ], "summary": "Generate OTP for tutor login", "description": "Generate OTP for tutor authentication using email or phone number", "operationId": "generateTutorOtp", "requestBody": { "description": "Request parameters", "required": true, "content": { "application/json": { "schema": { "required": [ "identifier" ], "properties": { "identifier": { "description": "Email or 10-digit mobile number", "type": "string", "example": "user@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP generated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OTP generated successfully" }, "data": { "properties": { "identifier_type": { "type": "string", "example": "email" }, "expires_in": { "type": "string", "example": "15 minutes" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The identifier must be either a valid email or a 10-digit mobile number." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } }, "404": { "description": "Tutor not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Tutor not found with the provided email" }, "error_code": { "type": "string", "example": "TUTOR_NOT_FOUND" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An unexpected error occurred" }, "error_code": { "type": "string", "example": "INTERNAL_SERVER_ERROR" } }, "type": "object" } } } } } } }, "/api/v2/tutor/login": { "post": { "tags": [ "Tutor V2" ], "summary": "Login tutor with email/password or email/OTP or mobile/OTP", "description": "Authenticate tutor using email with password, email with OTP, or mobile with OTP : email_password,email_otp,mobile_otp", "operationId": "tutorLogin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "login_type", "device_token_id" ], "properties": { "login_type": { "description": "Type of login method", "type": "string", "enum": [ "email_password", "email_otp", "mobile_otp" ] }, "email": { "description": "Required for email_password and email_otp login types", "type": "string" }, "mobile": { "description": "Required for mobile_otp login type", "type": "string" }, "password": { "description": "Required for email_password login type", "type": "string" }, "otp": { "description": "Required for email_otp and mobile_otp login types", "type": "string" }, "device_token_id": { "description": "Device token for notifications", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Login successful" }, "data": { "properties": { "user": { "type": "object" }, "token": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "404": { "description": "Tutor not found" }, "401": { "description": "Invalid credentials" } } } }, "/api/v2/tutor/verify-otp": { "post": { "tags": [ "Tutor V2" ], "summary": "Verify OTP for tutor", "description": "Verify OTP and update email/mobile verification status", "operationId": "verifyTutorOtpAndUpdateStatus", "requestBody": { "description": "Request parameters", "required": true, "content": { "application/json": { "schema": { "required": [ "identifier", "otp" ], "properties": { "identifier": { "description": "Email or 10-digit mobile number", "type": "string", "example": "user@example.com" }, "otp": { "description": "OTP received by user", "type": "string", "example": "123456" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP verified successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OTP verified successfully" }, "data": { "properties": { "identifier_type": { "type": "string", "example": "email" }, "verification_status": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The identifier must be either a valid email or a 10-digit mobile number." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } }, "404": { "description": "Tutor not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Tutor not found" }, "error_code": { "type": "string", "example": "TUTOR_NOT_FOUND" } }, "type": "object" } } } }, "401": { "description": "Invalid or expired OTP", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid OTP" }, "error_code": { "type": "string", "example": "INVALID_OTP" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong" }, "error_code": { "type": "string", "example": "INTERNAL_SERVER_ERROR" } }, "type": "object" } } } } } } }, "/api/v2/tutor/add-student-to-batch": { "post": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Add or Create Student and Add to Batch", "description": "Add a new or existing student to a batch/group. If user exists by mobile_no or email, the system will use the existing user. If user doesn't exist, creates new user account, student record, and assigns to batch. Works for both school-wise and freelance tutors.", "operationId": "addStudentToBatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "mobile_no", "group_id" ], "properties": { "name": { "description": "Full name of the student", "type": "string", "example": "John Doe" }, "mobile_no": { "description": "Mobile number (used to check if user already exists)", "type": "string", "example": "9876543210" }, "email": { "description": "Email address (optional, also used to check existing user)", "type": "string", "format": "email", "example": "john@example.com" }, "group_id": { "description": "Batch/Group ID to add student to", "type": "integer", "example": 15 }, "qualification": { "description": "Student's educational qualification (optional)", "type": "string", "example": "Class 12 / NEET Aspirant" }, "school": { "description": "School name (optional)", "type": "string", "example": "ABC High School" }, "state": { "description": "State (optional)", "type": "string", "example": "Maharashtra" }, "city": { "description": "City (optional)", "type": "string", "example": "Mumbai" } }, "type": "object" } } } }, "responses": { "200": { "description": "Student successfully added to batch", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "New student created and added to batch successfully" }, "user_id": { "description": "User ID created or found", "type": "integer", "example": 1245 }, "student_id": { "description": "Student record ID created or found", "type": "integer", "example": 856 }, "group_user_id": { "description": "Group user relationship ID", "type": "integer", "example": 1523 }, "is_new_user": { "description": "True if new user was created, false if existing user was found", "type": "boolean", "example": true }, "batch_name": { "description": "Name of the batch student was added to", "type": "string", "example": "Physics Class 12th Batch A" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Validation error" }, "errors": { "description": "Field-specific validation errors", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Batch not found or inactive", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Batch not found or inactive" } }, "type": "object" } }, "type": "object" } } } }, "409": { "description": "Student already assigned to this batch", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "Student is already assigned to this batch" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "data": { "properties": { "message": { "type": "string", "example": "An error occurred while adding student to batch" }, "error": { "type": "string", "example": "Database connection error" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/questions/add": { "post": { "tags": [ "Tutor V2" ], "summary": "Add questions from bank or custom", "description": "Add questions to a paper/test series from question bank or as custom questions.", "operationId": "addQuestionsToPaper", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "testseries_id", "questions" ], "properties": { "testseries_id": { "type": "integer", "example": 1 }, "questions": { "type": "array", "items": { "properties": { "source": { "type": "string", "enum": [ "bank", "custom" ], "example": "bank" }, "question_id": { "type": "integer", "example": 10 }, "question": { "type": "string", "example": "What is 2+2?" }, "question_type": { "type": "string", "example": "mcq" }, "options": { "type": "array", "items": { "type": "string" } }, "answer": { "type": "string", "example": "4" }, "marks": { "type": "integer", "example": 1 } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Questions added successfully" }, "400": { "description": "Validation error" }, "500": { "description": "Server error" } } } }, "/api/v2/tutor/add-question-topic-wise": { "post": { "tags": [ "Tutor V2" ], "summary": "Add questions to specific topics", "description": "Add Question Topic Wise\nPOST /api/v2/tutor/add-question-topic-wise", "operationId": "0cfd65375c14e36bd30dc538447dc0ed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "topic_id", "questions" ], "properties": { "topic_id": { "description": "Array of topic IDs (category)", "type": "array", "items": { "type": "integer" }, "example": [ 150, 151 ] }, "questions": { "description": "Array of questions to add", "type": "array", "items": { "required": [ "question", "answer_type", "question_type", "answer", "marks" ], "properties": { "source": { "description": "Source of question", "type": "string", "enum": [ "custom", "ai_generated" ], "example": "custom" }, "question": { "description": "Question text", "type": "string", "example": "What is Laravel?" }, "answer_type": { "description": "Type of answer", "type": "string", "enum": [ "radio", "checkbox", "text", "textarea" ], "example": "radio" }, "question_type": { "description": "Difficulty level", "type": "string", "enum": [ "Easy", "Medium", "Difficult" ], "example": "Easy" }, "options": { "description": "Options for radio/checkbox types", "type": "array", "items": { "type": "string" }, "example": [ "A PHP Framework", "A JavaScript Library", "A Database" ] }, "answer": { "description": "Correct answer (string for radio, array for checkbox)", "type": "string", "example": "A PHP Framework" }, "marks": { "description": "Marks for the question", "type": "number", "example": 5 } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Questions added successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Questions added successfully to topics" }, "data": { "properties": { "questions_created": { "type": "integer", "example": 2 }, "questions": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "403": { "description": "Forbidden - Not a tutor" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v2/tutor/test-series/{id}/assign-to-groups": { "post": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Assign test series to groups", "description": "Assign a test series to one or more groups/batches. Optionally distribute test variants among students.", "operationId": "assignTestSeriesToGroups", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "group_ids", "start_date", "end_date" ], "properties": { "group_ids": { "description": "Array of Group IDs", "type": "array", "items": { "type": "integer" } }, "distribute_variants": { "description": "Whether to distribute variants among students", "type": "boolean", "example": false }, "start_date": { "description": "Start date of the assignment", "type": "string", "format": "date-time" }, "end_date": { "description": "End date of the assignment", "type": "string", "format": "date-time" } }, "type": "object" } } } }, "responses": { "200": { "description": "Test series assigned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series assigned successfully" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/groups": { "get": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Get assigned groups", "description": "Get all groups assigned to a test series with variant distribution. For school tutors, pass school_id parameter or it will auto-detect from user profile.", "operationId": "4941b194750ab7f939e4fea22a60f05c", "parameters": [ { "name": "id", "in": "path", "description": "Test series ID", "required": true, "schema": { "type": "integer" } }, { "name": "school_id", "in": "query", "description": "School ID (optional, auto-detected for school tutors)", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Groups retrieved successfully" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series": { "get": { "tags": [ "Tutor V2 - Test Series" ], "summary": "List all test series", "description": "Retrieves a paginated list of all test series created by the authenticated tutor", "operationId": "v2ListTestSeries", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "status", "in": "query", "description": "Filter by status (approved, pending, rejected)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series retrieved successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/check-available-questions": { "post": { "tags": [ "Tutor V2 - Test Series" ], "summary": "Check available questions in question bank", "description": "Check if there are enough questions available in the question bank for auto-generating a test series with specified criteria", "operationId": "checkAvailableQuestions", "requestBody": { "description": "Question availability check criteria", "required": true, "content": { "application/json": { "schema": { "required": [ "topic_ids", "questions_per_topic", "difficulty_distribution", "question_types" ], "properties": { "topic_ids": { "description": "Array of topic IDs to check", "type": "array", "items": { "type": "integer" }, "example": [ 101, 102, 103 ] }, "questions_per_topic": { "description": "Number of questions required per topic (5-25)", "type": "integer", "example": 10 }, "difficulty_distribution": { "description": "Difficulty distribution percentages (must sum to 100%)", "required": [ "easy", "medium", "hard" ], "properties": { "easy": { "description": "Percentage of easy questions (0-100)", "type": "integer", "example": 30 }, "medium": { "description": "Percentage of medium questions (0-100)", "type": "integer", "example": 50 }, "hard": { "description": "Percentage of hard questions (0-100)", "type": "integer", "example": 20 } }, "type": "object" }, "question_types": { "description": "Array of question types to include", "type": "array", "items": { "type": "string", "enum": [ "MCQ", "Subjective", "True-False" ] }, "example": [ "MCQ", "Subjective" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Availability check completed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Availability check completed" }, "data": { "properties": { "available_count": { "description": "Total questions available", "type": "integer", "example": 45 }, "required_count": { "description": "Total questions required", "type": "integer", "example": 30 }, "has_enough": { "description": "Whether there are enough questions", "type": "boolean", "example": true }, "breakdown": { "properties": { "by_topic": { "type": "array", "items": { "properties": { "topic_id": { "type": "integer", "example": 101 }, "topic_name": { "type": "string", "example": "Algebra" }, "available": { "type": "integer", "example": 15 }, "required": { "type": "integer", "example": 10 }, "shortage": { "description": "Only present if there's a shortage", "type": "integer", "example": 0 } }, "type": "object" } }, "by_difficulty": { "properties": { "easy": { "properties": { "available": { "type": "integer", "example": 12 }, "required": { "type": "integer", "example": 9 }, "shortage": { "description": "Only present if there's a shortage", "type": "integer", "example": 0 } }, "type": "object" }, "medium": { "properties": { "available": { "type": "integer", "example": 20 }, "required": { "type": "integer", "example": 15 }, "shortage": { "description": "Only present if there's a shortage", "type": "integer", "example": 0 } }, "type": "object" }, "hard": { "properties": { "available": { "type": "integer", "example": 13 }, "required": { "type": "integer", "example": 6 }, "shortage": { "description": "Only present if there's a shortage", "type": "integer", "example": 0 } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "suggestions": { "description": "Suggestions to resolve shortages (only present if has_enough is false)", "type": "array", "items": { "type": "string" }, "example": [ "Reduce questions per topic to 8", "Add more 'Hard' questions to the bank" ] } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized. Please login." } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to check available questions" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v2/tutor/test-series/{testId}/groups/{groupId}": { "delete": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Unassign batch from test series", "description": "Remove assignment of a test series from a specific batch/group", "operationId": "unassignBatchFromTestSeries", "parameters": [ { "name": "testId", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } }, { "name": "groupId", "in": "path", "description": "Group ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Batch unassigned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Batch unassigned successfully" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/wallet/balance": { "get": { "tags": [ "Tutor" ], "summary": "Get tutor wallet balance", "description": "Returns the current wallet balance for the authenticated tutor", "operationId": "getTutorWalletBalanceV2", "responses": { "200": { "description": "Wallet balance retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "wallet_balance": { "type": "number", "format": "float", "example": 1250.5 }, "currency": { "type": "string", "example": "INR" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Unauthorized - Not a tutor" }, "500": { "description": "Internal server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/schools/test-series": { "get": { "tags": [ "Tutor - Test Series" ], "summary": "Get school or tutor test series", "description": "Retrieves test series created by tutor (if school_id=0) or assigned to school (if school_id>0). Excludes sections and school-saleable items for independent tutors.", "operationId": "6e855ef1d595aa32abe13984c476d97f", "parameters": [ { "name": "per_page", "in": "query", "description": "Number of items per page (default: 15)", "required": false, "schema": { "type": "integer", "example": 15 } }, { "name": "status", "in": "query", "description": "Filter by schedule status (is_schedule_testseries)", "required": false, "schema": { "type": "string", "enum": [ "0", "1", "scheduled", "unscheduled" ], "example": "scheduled" } }, { "name": "tseries_verif_status", "in": "query", "description": "Filter by verification status", "required": false, "schema": { "type": "string", "example": "approved" } } ], "responses": { "200": { "description": "Test series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series retrieved successfully" }, "data": { "properties": { "school": { "properties": { "id": { "type": "integer", "example": 1, "nullable": true }, "name": { "type": "string", "example": "ABC School" } }, "type": "object" }, "test_series": { "properties": { "current_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "description": "Creator of the test series (tutor/school)", "type": "integer", "example": 123 }, "name": { "type": "string", "example": "Mathematics Final Test" }, "testseries_image": { "type": "string", "example": "image.jpg", "nullable": true }, "category_id": { "type": "integer", "example": 5 }, "instructions": { "type": "string", "example": "Read all questions carefully" }, "short_description": { "type": "string", "example": "Final exam for Math" }, "total_time": { "description": "Total time in minutes", "type": "integer", "example": 120 }, "negative_marks": { "type": "number", "format": "float", "example": 0.25 }, "per_ques_mark": { "type": "number", "format": "float", "example": 1 }, "max_questions": { "type": "integer", "example": 50 }, "type": { "type": "string", "example": "objective" }, "sch_date_time_from": { "type": "string", "format": "date-time", "nullable": true }, "sch_date_time_to": { "type": "string", "format": "date-time", "nullable": true }, "show_result": { "type": "string", "example": "1" }, "test_series_type": { "type": "string", "example": "practice" }, "parent_test_id": { "type": "integer", "nullable": true }, "is_section": { "type": "string", "example": "0" }, "child": { "type": "string", "example": "2,3,4", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "is_publish": { "description": "Only for independent tutors", "type": "string", "example": "1" }, "total_questions": { "description": "Total question count", "type": "integer", "example": 50 }, "category": { "type": "object", "nullable": true } }, "type": "object" } }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 100 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - User not authenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized. Please login." }, "error_code": { "type": "string", "example": "UNAUTHORIZED" } }, "type": "object" } } } }, "400": { "description": "Bad Request - School ID required but missing", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "School ID is required" }, "error_code": { "type": "string", "example": "SCHOOL_ID_REQUIRED" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve test series" }, "error": { "type": "string" }, "error_code": { "type": "string", "example": "INTERNAL_ERROR" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Tutor V2 - School Management" ], "summary": "Create test series for a school", "description": "Creates a new test series in the context of the current school", "operationId": "storeSchoolTestSeries", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "category_id" ], "properties": { "title": { "description": "Test series title", "type": "string", "example": "School Physics Test" }, "description": { "description": "Test description", "type": "string", "example": "School-wide physics test" }, "category_id": { "description": "Category/Subject ID", "type": "integer", "example": 1 }, "duration_minutes": { "description": "Test duration", "type": "integer", "example": 60 }, "total_marks": { "description": "Total marks", "type": "integer", "example": 100 } }, "type": "object" } } } }, "responses": { "201": { "description": "Test series created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series created successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 100 }, "title": { "type": "string", "example": "School Physics Test" }, "school_id": { "type": "integer", "example": 5 }, "created_at": { "type": "string", "example": "2025-01-15 10:00:00" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/schools/batches": { "get": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Get batches/groups for school", "description": "Get list of batches/groups for the authenticated tutor's school.", "operationId": "getSchoolBatches", "parameters": [ { "name": "school_id", "in": "query", "description": "School ID (optional)", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Batches retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Batches retrieved successfully" }, "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/batches/{batchId}/tests": { "get": { "tags": [ "Tutor - Test Series" ], "summary": "Get tests assigned to a batch", "description": "Retrieves all test series assigned to a specific batch/group. Returns batch details along with assigned test series information.", "operationId": "3703ae56161e8215f2e7fe9948e18bcf", "parameters": [ { "name": "batchId", "in": "path", "description": "The ID of the batch/group", "required": true, "schema": { "type": "integer", "example": 123 } } ], "responses": { "200": { "description": "Batch tests retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Batch tests retrieved successfully" }, "data": { "properties": { "batch": { "properties": { "id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "Class 10 - Section A" }, "school": { "properties": { "id": { "type": "integer", "example": 1, "nullable": true }, "name": { "type": "string", "example": "ABC School" } }, "type": "object" }, "class_id": { "type": "integer", "example": 10, "nullable": true }, "students_count": { "type": "integer", "example": 35 } }, "type": "object" }, "tests": { "type": "array", "items": { "properties": { "assignment_id": { "type": "integer", "example": 1 }, "test_series_id": { "type": "integer", "example": 456 }, "variant_assigned": { "type": "string", "example": "A", "nullable": true }, "assigned_at": { "type": "string", "format": "date-time" }, "test_series": { "properties": { "id": { "type": "integer", "example": 456 }, "name": { "type": "string", "example": "Mathematics Final Test" }, "image": { "type": "string", "example": "image.jpg", "nullable": true }, "category": { "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "Mathematics" } }, "type": "object", "nullable": true }, "total_time": { "description": "Total time in minutes", "type": "integer", "example": 120 }, "total_questions": { "type": "integer", "example": 50 }, "max_questions": { "type": "integer", "example": 50 }, "per_ques_mark": { "type": "number", "format": "float", "example": 1 }, "negative_marks": { "type": "number", "format": "float", "example": 0.25 }, "type": { "type": "string", "example": "objective" }, "schedule_from": { "type": "string", "format": "date-time", "nullable": true }, "schedule_to": { "type": "string", "format": "date-time", "nullable": true }, "show_result": { "type": "string", "example": "1" }, "test_series_type": { "type": "string", "example": "practice" }, "created_at": { "type": "string", "format": "date-time" }, "status": { "description": "Test series verification status", "type": "string", "example": "approved" } }, "type": "object" } }, "type": "object" } }, "total_count": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - User not authenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized. Please login." }, "error_code": { "type": "string", "example": "UNAUTHORIZED" } }, "type": "object" } } } }, "404": { "description": "Batch not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch not found" }, "error_code": { "type": "string", "example": "BATCH_NOT_FOUND" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve batch tests" }, "error": { "type": "string" }, "error_code": { "type": "string", "example": "INTERNAL_ERROR" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/preview-auto-generate-questions": { "post": { "tags": [ "Tutor V2 - Test Series" ], "summary": "Preview auto-generated questions", "description": "Preview questions that would be auto-generated based on the configuration before adding to test series", "operationId": "previewAutoGenerateQuestions", "requestBody": { "description": "Preview configuration", "required": true, "content": { "application/json": { "schema": { "required": [ "test_series_id", "topic_question_distribution" ], "properties": { "test_series_id": { "description": "Test series ID (required)", "type": "integer", "example": 12345 }, "topic_question_distribution": { "description": "Object mapping topic IDs to number of questions for each topic", "type": "object", "example": { "1790": 6, "1794": 14 } }, "question_types": { "description": "Difficulty distribution (must sum to 100% if provided, optional)", "properties": { "Easy": { "description": "Percentage of easy questions (0-100)", "type": "integer", "example": 0 }, "Medium": { "description": "Percentage of medium questions (0-100)", "type": "integer", "example": 100 }, "Difficult": { "description": "Percentage of difficult questions (0-100)", "type": "integer", "example": 0 } }, "type": "object", "nullable": true }, "answer_type": { "description": "Answer type filter: 'radio' for single-choice MCQ, 'checkbox' for multi-choice MCQ, 'textarea' for subjective/text answers. Returns ONLY the specified type.", "type": "string", "enum": [ "radio", "checkbox", "textarea" ], "example": "radio" }, "per_question_marks": { "description": "Marks per question (1-100)", "type": "integer", "example": 1 }, "source": { "description": "Array of question sources to filter by (optional)", "type": "array", "items": { "type": "string", "enum": [ "admin_manual", "admin_ai_generated", "tutor_manual", "tutor_ai_generated" ] }, "example": [ "admin_manual", "admin_ai_generated", "tutor_manual", "tutor_ai_generated" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Questions retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Questions retrieved successfully" }, "data": { "properties": { "questions": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1001 }, "question": { "type": "string", "example": "What is 2 + 2?" }, "question_type": { "type": "string", "example": "MCQ" }, "difficulty": { "type": "string", "example": "Medium" }, "marks": { "type": "integer", "example": 1 }, "category_id": { "type": "integer", "example": 1790 }, "category_name": { "type": "string", "example": "Algebra" }, "source": { "type": "string", "example": "admin_manual" }, "answer_type": { "type": "string", "example": "radio" }, "options": { "type": "array", "items": { "type": "string" }, "example": [ "3", "4", "5", "6" ] }, "correct_answer": { "type": "string", "example": "4" } }, "type": "object" } }, "summary": { "properties": { "total_questions": { "type": "integer", "example": 20 }, "total_marks": { "type": "integer", "example": 20 }, "by_difficulty": { "properties": { "Easy": { "type": "integer", "example": 0 }, "Medium": { "type": "integer", "example": 20 }, "Difficult": { "type": "integer", "example": 0 } }, "type": "object" }, "by_topic": { "properties": { "1790": { "type": "integer", "example": 6 }, "1794": { "type": "integer", "example": 14 } }, "type": "object" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized. Please login." } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to preview questions" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v2/tutor/batches/{batchId}/tests/{testSeriesId}": { "delete": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Remove test series from batch", "description": "Remove a test series assignment from a batch. This will unassign the test from the batch but won't delete the test itself.", "operationId": "e1f3ff1e6bd037efa352959f647b008b", "parameters": [ { "name": "batchId", "in": "path", "description": "Batch/Group ID", "required": true, "schema": { "type": "integer", "example": 20 } }, { "name": "testSeriesId", "in": "path", "description": "Test Series ID to remove", "required": true, "schema": { "type": "integer", "example": 123 } } ], "responses": { "200": { "description": "Test series removed from batch successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series removed from batch successfully" }, "data": { "properties": { "batch_id": { "type": "integer", "example": 20 }, "test_series_id": { "type": "integer", "example": 123 }, "removed_at": { "type": "string", "example": "2025-01-15 10:30:45" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - User not authenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized. Please login." }, "error_code": { "type": "string", "example": "UNAUTHORIZED" } }, "type": "object" } } } }, "404": { "description": "Not Found - Batch, test series, or assignment not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch not found" }, "error_code": { "type": "string", "example": "BATCH_NOT_FOUND" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to remove test series from batch" }, "error": { "type": "string" }, "error_code": { "type": "string", "example": "INTERNAL_ERROR" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/assign-student": { "post": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Assign/Enroll a student to tutor", "description": "Assign a student to tutor by mobile number. Deducts enrollment fee from wallet.", "operationId": "assignStudent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "std_id", "status" ], "properties": { "std_id": { "description": "Student mobile number", "type": "string", "example": "9876543210" }, "status": { "description": "1 to assign, 0 to unassign", "type": "string", "example": "1" }, "id": { "description": "Group ID (optional, for status change)", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "Student enrolled/unassigned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Student enrolled successfully" } }, "type": "object" } } } }, "400": { "description": "Insufficient balance or validation error" }, "404": { "description": "Student not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/enrollment-students": { "get": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Get all students enrolled in tutor's groups", "description": "Retrieves a list of all students who are enrolled in the groups/batches created by the authenticated tutor. This endpoint is useful for displaying students before assigning test series.", "operationId": "getEnrollmentStudents", "responses": { "200": { "description": "Students retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Students retrieved successfully" }, "data": { "type": "array", "items": { "properties": { "id": { "description": "Student user ID", "type": "integer", "example": 123 }, "name": { "description": "Student name", "type": "string", "example": "John Doe" }, "mobile_no": { "description": "Student mobile number", "type": "string", "example": "9876543210" }, "image": { "description": "Student profile image URL", "type": "string", "example": "https://example.com/image.jpg", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve students" }, "error": { "type": "string", "example": "Error message" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/student-enrollment-for-testseries": { "post": { "tags": [ "Tutor V2 - Test Series" ], "summary": "Enroll students to test series", "description": "Enroll multiple students to a test series with specified start and end dates. This endpoint deducts enrollment fee from tutor's wallet.", "operationId": "studentEnrollmentForTestSeries", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "student_id", "testseries_id", "startdateofseries", "enddateofseries" ], "properties": { "student_id": { "description": "Array of student IDs to enroll", "type": "array", "items": { "type": "integer", "example": 123 } }, "testseries_id": { "description": "Test series ID", "type": "integer", "example": 45 }, "startdateofseries": { "description": "Start date of the series", "type": "string", "format": "date", "example": "2024-01-15" }, "enddateofseries": { "description": "End date of the series (must be after start date)", "type": "string", "format": "date", "example": "2024-03-15" } }, "type": "object" } } } }, "responses": { "200": { "description": "Students enrolled successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Students enrolled to test series successfully" } }, "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" }, "500": { "description": "Internal server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/schoolstudent-enrollment-for-testseries": { "get": { "tags": [ "Tutor V2 - Test Series" ], "summary": "Enroll school students to test series", "description": "Enroll multiple school students to a test series with specified start and end dates. This endpoint is specifically for school context and does not deduct from wallet.", "operationId": "schoolStudentEnrollmentForTestSeries", "parameters": [ { "name": "student_id", "in": "query", "description": "Array of student IDs to enroll", "required": true, "schema": { "type": "array", "items": { "type": "integer", "example": 123 } } }, { "name": "testseries_id", "in": "query", "description": "Test series ID", "required": true, "schema": { "type": "integer", "example": 45 } }, { "name": "startdateofseries", "in": "query", "description": "Start date of the series", "required": true, "schema": { "type": "string", "format": "date", "example": "2024-01-15" } }, { "name": "enddateofseries", "in": "query", "description": "End date of the series (must be after start date)", "required": true, "schema": { "type": "string", "format": "date", "example": "2024-03-15" } } ], "responses": { "200": { "description": "School students enrolled successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "School students enrolled to test series successfully" } }, "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" }, "500": { "description": "Internal server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/batch-class": { "get": { "tags": [ "Tutor" ], "summary": "Get classes from tutor's assigned batches", "description": "Returns list of batches with their associated class information for the authenticated tutor", "operationId": "getClassesFromBatches", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "batch_id": { "type": "integer", "example": 1 }, "batch_name": { "type": "string", "example": "Batch A" }, "class_name": { "type": "string", "example": "Class 10" }, "class_id": { "type": "integer", "example": 5 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/testSeries/assign/for-student": { "post": { "tags": [ "Tutor" ], "summary": "Assign Test Series to Students", "description": "Allows a tutor to assign a test series to one or more students. Checks for existing enrollment and validates the test series.", "operationId": "testSeriesAssignForStudent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "testseries_id", "student_id", "start_date", "end_date" ], "properties": { "testseries_id": { "description": "ID of the test series to assign", "type": "integer", "example": 5 }, "student_id": { "description": "Array of student IDs to assign the test series to", "type": "array", "items": { "type": "integer" }, "example": [ 101, 102, 103 ] }, "start_date": { "description": "Start date of the test series enrollment", "type": "string", "format": "date", "example": "2025-04-07" }, "end_date": { "description": "End date of the test series enrollment (must be after start_date)", "type": "string", "format": "date", "example": "2025-04-30" } }, "type": "object" } } } }, "responses": { "200": { "description": "Assignment completed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "message": { "type": "string", "example": "Student enrollment process completed!" }, "assigned": { "description": "Number of students successfully assigned", "type": "integer", "example": 2 }, "skipped": { "description": "Number of students skipped (already enrolled)", "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The testseries_id field is required." } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Forbidden - User is not a tutor", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized access" } }, "type": "object" } } } }, "404": { "description": "Test series not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid test series." } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An unexpected error occurred" }, "error": { "type": "string", "example": "Exception message here" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/student-details": { "get": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Get student details with batch and test series statistics", "description": "Returns all students under the tutor with total batches, total test series, completed and pending test series counts. Optionally filter by student_id and batch_id.", "operationId": "getTutorStudentDetails", "parameters": [ { "name": "student_id", "in": "query", "description": "Filter by specific student ID", "required": false, "schema": { "type": "integer" } }, { "name": "batch_id", "in": "query", "description": "Filter by specific batch ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "total_students": { "type": "integer", "example": 25 }, "students": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 101 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "mobile": { "type": "string", "example": "9876543210" }, "total_batches": { "type": "integer", "example": 3 }, "total_test_series": { "type": "integer", "example": 10 }, "completed_test_series": { "type": "integer", "example": 6 }, "pending_test_series": { "type": "integer", "example": 4 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Not a tutor" }, "404": { "description": "Student or batch not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/school-students": { "get": { "tags": [ "Tutor V2 - Student Management" ], "summary": "Get students in tutor's batches for selected school", "description": "Retrieves all students enrolled in batches where the tutor is assigned in their selected school or freelancer context", "operationId": "getTutorStudentsBySchool", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "search", "in": "query", "description": "Search by student name, email, or mobile", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by enrollment status (active, inactive, withdrawn)", "required": false, "schema": { "type": "string" } }, { "name": "batch_id", "in": "query", "description": "Filter by specific batch ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Students retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Students retrieved successfully" }, "data": { "properties": { "total_students": { "type": "integer", "example": 45 }, "students": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "mobile_no": { "type": "string" }, "batches": { "type": "array", "items": { "properties": { "batch_id": { "type": "integer" }, "batch_name": { "type": "string" }, "class_name": { "type": "string" }, "enrollment_status": { "type": "string" } }, "type": "object" } }, "profile_image": { "type": "string" } }, "type": "object" } } }, "type": "object" }, "pagination": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Not a tutor" } }, "security": [ { "sanctum": [] } ] } }, "/api/user/publish_result": { "get": { "tags": [ "Utility" ], "summary": "Publish scheduled test results", "operationId": "89ce0b6d6904e1d85712179ab5844dd3", "responses": { "200": { "description": "Results published" } } } }, "/api/user/notifications": { "get": { "tags": [ "notifications" ], "summary": "Get notifications for the currently logged-in user", "description": "Returns a list of notifications for the authenticated user.", "operationId": "6f91130a0b8b213e0c9da8d9cb429353", "responses": { "200": { "description": "Successfully retrieved notifications", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "notifications": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "message": { "type": "string", "example": "New message received" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-08-14T07:00:00Z" }, "image": { "type": "string", "example": "http://localhost:8000/storage/tutor_profile/john_doe.png" }, "role_id": { "type": "integer", "example": 1 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized (if the user is not authenticated)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not authenticated" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/user/test-noti/": { "get": { "tags": [ "Utility" ], "summary": "Send test topic notification", "operationId": "070dd82d1cc3743d794fb096a74c1fd7", "responses": { "200": { "description": "Notification sent" } } } }, "/api/send-notification-api": { "post": { "tags": [ "Utility" ], "summary": "Send notification via API", "operationId": "31c1f17c3f927ab661a8f8598491af92", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "deviceTokens", "title", "body" ], "properties": { "deviceTokens": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" }, "body": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Notifications sent" } } } }, "/api/send-device-push-notification": { "post": { "tags": [ "Utility" ], "summary": "Web Push Notification API", "operationId": "b6790e4594a29b41dc19da3f037599ad", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "body" ], "properties": { "title": { "type": "string" }, "body": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Notification sent" } } } }, "/api/testseries/pdf/{id}": { "get": { "tags": [ "PDF" ], "summary": "Download test series PDF via BrowserShot", "operationId": "8ebac8fcf3d283ad93cdade44a58ff39", "parameters": [ { "name": "id", "in": "path", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "PDF File" } } } }, "/api/testseries/pdfold/{id}": { "get": { "tags": [ "PDF" ], "summary": "Download test series PDF via snappyTest", "operationId": "d0e16088d2a4642aa5b8c087205a371d", "parameters": [ { "name": "id", "in": "path", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "PDF File" } } } }, "/api/testseries/pdf4/{id}": { "get": { "tags": [ "PDF" ], "summary": "Download test series PDF (v1)", "operationId": "5624edd05199ea59e47d1cfd5c04aa7c", "parameters": [ { "name": "id", "in": "path", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "PDF File" } } } }, "/api/testseries/pdf5/{id}": { "get": { "tags": [ "PDF" ], "summary": "Download test series PDF (v5)", "operationId": "83bfcd5ffebe92fa563d806145544f87", "parameters": [ { "name": "id", "in": "path", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "PDF File" } } } }, "/api/testseries/pdf1/": { "get": { "tags": [ "PDF" ], "summary": "Download test series PDF (v1 - legacy)", "operationId": "d23f7044d37babf77ccfecb982888d78", "responses": { "200": { "description": "PDF File" } } } }, "/api/handle-payment": { "post": { "tags": [ "Utility" ], "summary": "Handle general payment verification", "operationId": "fb45d76937f6300d75483ef762a2facc", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "razorpay_payment_id", "order_id" ], "properties": { "razorpay_payment_id": { "type": "string" }, "order_id": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment result" } } } }, "/api/handle-test_series-payment": { "post": { "tags": [ "Utility" ], "summary": "Handle test series payment verification", "operationId": "7251d3d89ad370a1a71d3e956fc44831", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "razorpay_payment_id", "order_id", "test_series_id" ], "properties": { "razorpay_payment_id": { "type": "string" }, "order_id": { "type": "string" }, "test_series_id": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment result" } } } }, "/api/questions/generate-and-save": { "post": { "tags": [ "AI Question Generation V2" ], "summary": "Quick generate and save AI questions (synchronous)", "description": "Generate AI questions for limited topics and save directly to database. For quick generation with immediate response. Max 10 topics, max 50 questions per topic.", "operationId": "f42ccedda09c1b0978c02eb570d8d935", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "class_id", "subject_id", "topic_ids", "questions_per_topic", "question_type", "answer_type", "marks" ], "properties": { "class_id": { "description": "Class ID from lk_category", "type": "integer", "example": 1 }, "subject_id": { "description": "Subject ID from lk_category", "type": "integer", "example": 5 }, "topic_ids": { "description": "Array of topic IDs (max 10)", "type": "array", "items": { "type": "integer" }, "example": [ 10, 11, 12 ] }, "questions_per_topic": { "description": "Number of questions per topic (1-50)", "type": "integer", "example": 5 }, "question_type": { "description": "Question difficulty level", "type": "string", "enum": [ "Easy", "Medium", "Difficult" ], "example": "Medium" }, "answer_type": { "description": "Answer type for questions", "type": "string", "enum": [ "radio", "checkbox", "textarea" ], "example": "radio" }, "marks": { "description": "Marks per question (1-10)", "type": "integer", "example": 2 } }, "type": "object" } } } }, "responses": { "200": { "description": "Questions generated and saved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "15 questions generated and saved successfully" }, "data": { "properties": { "question_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 101, 102, 103 ] }, "topics_processed": { "type": "integer", "example": 3 }, "questions_per_topic": { "type": "integer", "example": 5 }, "coins_deducted": { "type": "integer", "example": 15 }, "remaining_balance": { "type": "integer", "example": 85 } }, "type": "object" } }, "type": "object" } } } }, "402": { "description": "Insufficient coins", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Insufficient coins" }, "data": { "properties": { "required": { "type": "integer", "example": 15 }, "current_balance": { "type": "integer", "example": 5 }, "shortfall": { "type": "integer", "example": 10 }, "coins_per_question": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "401": { "description": "Unauthorized" }, "500": { "description": "Generation failed" } }, "security": [ { "sanctum": [] } ] } }, "/api/questions/save-ai-questions": { "post": { "tags": [ "Tutor V2" ], "summary": "Save AI generated questions", "operationId": "saveAIQuestions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "questions" ], "properties": { "questions": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Questions saved successfully" } } } }, "/api/v2/student/enroll": { "post": { "tags": [ "Student - Enrollment" ], "summary": "Enroll in group using code", "description": "Allows students to enroll in a group/batch by providing a valid enrollment code. The enrollment code is generated by tutors and shared with students.", "operationId": "studentEnroll", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "enrollment_code" ], "properties": { "enrollment_code": { "description": "Unique enrollment code for the group/batch", "type": "string", "example": "ABC123XYZ" }, "student_name": { "description": "Student's full name (optional if already in profile)", "type": "string", "example": "John Doe" }, "student_email": { "description": "Student's email (optional)", "type": "string", "example": "john@example.com", "nullable": true }, "student_phone": { "description": "Student's phone number (optional)", "type": "string", "example": "9876543210", "nullable": true }, "device_id": { "description": "Device ID for tracking (used with deep links)", "type": "string", "example": "device_abc123", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Enrollment successful", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Successfully enrolled in the group" }, "data": { "properties": { "enrollment_id": { "type": "integer", "example": 123 }, "student_id": { "type": "integer", "example": 456 }, "group_id": { "type": "integer", "example": 10 }, "group_name": { "type": "string", "example": "Class 10 Mathematics Batch A" }, "tutor_name": { "type": "string", "example": "Prof. Sharma" }, "school_name": { "type": "string", "example": "ABC Coaching Institute", "nullable": true }, "enrollment_date": { "type": "string", "format": "date-time" }, "group_details": { "properties": { "class_id": { "type": "integer", "example": 86 }, "class_name": { "type": "string", "example": "Class 10" }, "subject_id": { "type": "integer", "example": 90, "nullable": true }, "subject_name": { "type": "string", "example": "Mathematics", "nullable": true }, "total_students": { "type": "integer", "example": 45 }, "total_tests": { "type": "integer", "example": 12 } }, "type": "object" }, "is_first_enrollment": { "description": "Whether this is the student's first enrollment", "type": "boolean", "example": true }, "welcome_message": { "type": "string", "example": "Welcome to Class 10 Mathematics! Get ready for exciting learning.", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Invalid enrollment code", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or expired enrollment code" } }, "type": "object" } } } }, "409": { "description": "Already enrolled", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are already enrolled in this group" }, "data": { "properties": { "enrollment_id": { "type": "integer", "example": 123 }, "enrollment_date": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error or enrollment limit reached", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Group enrollment limit reached" }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/pending-enrollment/store": { "post": { "tags": [ "Student - Enrollment" ], "summary": "Store pending enrollment (deep link flow)", "description": "Stores a pending enrollment request when the app is opened via a deep link but the user is not yet authenticated. The enrollment will be completed after the user signs in or signs up. This is useful for seamless onboarding via shared links.", "operationId": "storePendingEnrollment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "enrollment_code", "device_id" ], "properties": { "enrollment_code": { "description": "Enrollment code from the deep link", "type": "string", "example": "ABC123XYZ" }, "device_id": { "description": "Unique device identifier for tracking", "type": "string", "example": "device_abc123" }, "app_version": { "description": "App version for analytics", "type": "string", "example": "1.2.3", "nullable": true }, "platform": { "description": "Platform from which the deep link was opened", "type": "string", "enum": [ "android", "ios", "web" ], "example": "android", "nullable": true }, "utm_source": { "description": "UTM source for tracking marketing campaigns", "type": "string", "example": "whatsapp", "nullable": true }, "utm_medium": { "type": "string", "example": "share_link", "nullable": true }, "utm_campaign": { "type": "string", "example": "batch_enrollment_q1", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Pending enrollment stored successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Pending enrollment stored successfully" }, "data": { "properties": { "pending_enrollment_id": { "type": "integer", "example": 789 }, "enrollment_code": { "type": "string", "example": "ABC123XYZ" }, "device_id": { "type": "string", "example": "device_abc123" }, "group_preview": { "properties": { "group_name": { "type": "string", "example": "Class 10 Mathematics Batch A" }, "tutor_name": { "type": "string", "example": "Prof. Sharma" }, "school_name": { "type": "string", "example": "ABC Coaching Institute", "nullable": true }, "class_name": { "type": "string", "example": "Class 10" }, "subject_name": { "type": "string", "example": "Mathematics", "nullable": true } }, "type": "object" }, "expires_at": { "description": "Pending enrollment expiration time (typically 7 days)", "type": "string", "format": "date-time" }, "next_step": { "type": "string", "example": "Please sign in or create an account to complete enrollment" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Invalid enrollment code", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or expired enrollment code" } }, "type": "object" } } } }, "422": { "description": "Validation error or pending enrollment already exists", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Pending enrollment already exists for this device" }, "data": { "properties": { "existing_pending_enrollment_id": { "type": "integer", "example": 788 } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/v2/student/batches/join": { "post": { "tags": [ "Student - Enrollment" ], "summary": "Join a batch using enrollment code", "description": "Allows students to join a batch/group by providing a valid enrollment code. This endpoint returns a simplified response format with batch details.", "operationId": "joinBatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "enrollment_code" ], "properties": { "enrollment_code": { "description": "Unique enrollment code for the batch", "type": "string", "example": "ABC123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successfully joined the batch", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Successfully joined the batch" }, "data": { "properties": { "batch": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Mathematics Excellence" }, "class_name": { "type": "string", "example": "Class 10" }, "teacher_name": { "type": "string", "example": "Mr. Sharma" }, "subjects": { "type": "array", "items": { "type": "string", "example": "Mathematics" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Already enrolled or code expired", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are already enrolled in this batch" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden - Only students can join batches", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Forbidden: Only students can join batches" } }, "type": "object" } } } }, "404": { "description": "Invalid enrollment code", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid enrollment code" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to join batch" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/student/batches-list": { "get": { "tags": [ "Student - Enrollment" ], "summary": "Get list of enrolled batches", "description": "Retrieves a list of all batches (groups) that the authenticated student is enrolled in. Returns detailed information about each batch including class, school, subjects, and enrollment details.", "operationId": "studentBatchesList", "responses": { "200": { "description": "Batches list retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Batches list retrieved successfully" }, "data": { "properties": { "batches": { "type": "array", "items": { "properties": { "enrollment_id": { "type": "integer", "example": 123 }, "group_id": { "type": "integer", "example": 10 }, "group_name": { "type": "string", "example": "Class 10 Mathematics Batch A" }, "class": { "properties": { "id": { "type": "integer", "example": 86 }, "name": { "type": "string", "example": "Class 10" } }, "type": "object" }, "school": { "properties": { "id": { "type": "integer", "example": 5, "nullable": true }, "name": { "type": "string", "example": "ABC Coaching Institute", "nullable": true } }, "type": "object" }, "subjects": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 90 }, "name": { "type": "string", "example": "Mathematics" } }, "type": "object" } }, "enrollment_code": { "type": "string", "example": "ABC123XYZ" }, "code_expires_at": { "type": "string", "format": "date-time", "example": "2024-12-31 23:59:59", "nullable": true }, "is_code_expired": { "type": "boolean", "example": false }, "enrolled_at": { "type": "string", "format": "date-time", "example": "2024-01-15 10:30:00", "nullable": true }, "enrolled_at_human": { "type": "string", "example": "2 months ago", "nullable": true } }, "type": "object" } }, "total_count": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" }, "error_code": { "type": "string", "example": "UNAUTHENTICATED" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/pending-enrollment/{device_id}": { "get": { "tags": [ "Student - Enrollment" ], "summary": "Get pending enrollment by device", "description": "Retrieves any pending enrollment associated with the specified device ID. This is called after user authentication to check if there's a pending enrollment to complete. If found, the app should automatically process the enrollment.", "operationId": "getPendingEnrollmentByDevice", "parameters": [ { "name": "device_id", "in": "path", "description": "Device ID", "required": true, "schema": { "type": "string", "example": "device_abc123" } } ], "responses": { "200": { "description": "Pending enrollment retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Pending enrollment found" }, "data": { "properties": { "pending_enrollment_id": { "type": "integer", "example": 789 }, "enrollment_code": { "type": "string", "example": "ABC123XYZ" }, "device_id": { "type": "string", "example": "device_abc123" }, "group_details": { "properties": { "group_id": { "type": "integer", "example": 10 }, "group_name": { "type": "string", "example": "Class 10 Mathematics Batch A" }, "tutor_name": { "type": "string", "example": "Prof. Sharma" }, "school_name": { "type": "string", "example": "ABC Coaching Institute", "nullable": true }, "class_name": { "type": "string", "example": "Class 10" }, "subject_name": { "type": "string", "example": "Mathematics", "nullable": true }, "total_students": { "type": "integer", "example": 45 }, "total_tests": { "type": "integer", "example": 12 } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "is_expired": { "type": "boolean", "example": false }, "days_until_expiry": { "type": "integer", "example": 6 }, "utm_tracking": { "properties": { "utm_source": { "type": "string", "example": "whatsapp" }, "utm_medium": { "type": "string", "example": "share_link" }, "utm_campaign": { "type": "string", "example": "batch_enrollment_q1" } }, "type": "object", "nullable": true }, "action_required": { "type": "string", "example": "Complete enrollment by calling POST /api/v2/student/enroll with this enrollment_code" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "No pending enrollment found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No pending enrollment found for this device" } }, "type": "object" } } } }, "410": { "description": "Pending enrollment expired", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Pending enrollment has expired. Please request a new enrollment link." }, "data": { "properties": { "expired_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/v2/student/batches/{batch_id}": { "get": { "tags": [ "Student - Enrollment" ], "summary": "Get batch details", "description": "Retrieves detailed information about a specific batch that the student is enrolled in. Returns information about the batch, teacher, subjects, and test statistics.", "operationId": "getBatchDetails", "parameters": [ { "name": "batch_id", "in": "path", "description": "Batch/Group ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Batch details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "batch": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Mathematics Excellence" }, "class_name": { "type": "string", "example": "Class 10" }, "teacher_id": { "type": "integer", "example": 101, "nullable": true }, "teacher_name": { "type": "string", "example": "Mr. Sharma", "nullable": true }, "teacher_image": { "type": "string", "example": "https://example.com/images/teacher.jpg", "nullable": true }, "subjects": { "type": "array", "items": { "type": "string" }, "example": [ "Mathematics", "Algebra", "Geometry" ] }, "description": { "type": "string", "example": "Comprehensive mathematics course for Class 10", "nullable": true }, "pending_tests_count": { "type": "integer", "example": 5 }, "total_tests_count": { "type": "integer", "example": 12 }, "total_students": { "type": "integer", "example": 45 }, "joined_at": { "type": "string", "format": "date-time", "example": "2025-12-25T10:30:00Z" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Not enrolled in this batch", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not enrolled in this batch" } }, "type": "object" } } } }, "404": { "description": "Batch not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch not found" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve batch details" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/student/batches/{batch_id}/tests": { "get": { "tags": [ "Student - Enrollment" ], "summary": "Get enrolled test series for a batch", "description": "Retrieves test series that the student is enrolled in for a specific batch. Shows only tests with enrollment records in enroll_testseries table. Status is calculated based on enrollment dates (start_date, end_date) rather than test series scheduled dates. Supports filtering by status and pagination.", "operationId": "getBatchTests", "parameters": [ { "name": "batch_id", "in": "path", "description": "Batch/Group ID", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "status", "in": "query", "description": "Filter tests by status (based on enrollment dates)", "required": false, "schema": { "type": "string", "enum": [ "active", "expired", "completed" ], "example": "active" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1, "example": 1 } }, { "name": "limit", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1, "example": 20 } } ], "responses": { "200": { "description": "Tests retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "batch_enrollment_id": { "description": "Student's enrollment ID in the batch (from group_users table)", "type": "integer", "example": 123 }, "tests": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Weekly Math Quiz" }, "test_type": { "type": "string", "example": "Quiz" }, "total_questions": { "type": "integer", "example": 20 }, "total_marks": { "type": "integer", "example": 40 }, "duration_minutes": { "type": "integer", "example": 30 }, "start_date": { "description": "Enrollment start date from enroll_testseries table", "type": "string", "format": "date-time", "example": "2026-02-01T00:00:00+05:30", "nullable": true }, "end_date": { "description": "Enrollment end date from enroll_testseries table", "type": "string", "format": "date-time", "example": "2026-02-28T23:59:59+05:30", "nullable": true }, "test_enrollment_id": { "description": "Enrollment ID from enroll_testseries table", "type": "integer", "example": 456 }, "batch_enrollment_id": { "description": "Student's enrollment ID in the batch", "type": "integer", "example": 123 }, "status": { "description": "active: within enrollment period; expired: past end_date; completed: test submitted", "type": "string", "enum": [ "active", "expired", "completed" ], "example": "active" }, "score": { "type": "number", "example": null, "nullable": true }, "percentage": { "type": "number", "example": null, "nullable": true }, "attempted_at": { "type": "string", "format": "date-time", "example": null, "nullable": true }, "can_attempt": { "type": "boolean", "example": true } }, "type": "object" } }, "total_count": { "description": "Total number of enrolled tests (filtered if status param is provided)", "type": "integer", "example": 12 }, "active_count": { "description": "Number of tests within enrollment period and not completed", "type": "integer", "example": 5 }, "completed_count": { "description": "Number of tests submitted by student", "type": "integer", "example": 6 }, "expired_count": { "description": "Number of tests past enrollment end_date", "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Not enrolled in this batch", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not enrolled in this batch" } }, "type": "object" } } } }, "404": { "description": "Batch not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch not found" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/student/batches/{batch_id}/activity": { "get": { "tags": [ "Student - Enrollment" ], "summary": "Get batch activity feed", "description": "Retrieves the activity timeline for a specific batch, including test assignments, test completions, student enrollments, and teacher assignments. Activities are sorted by timestamp in descending order (newest first).", "operationId": "getBatchActivity", "parameters": [ { "name": "batch_id", "in": "path", "description": "Batch/Group ID", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1, "example": 1 } }, { "name": "limit", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1, "example": 20 } } ], "responses": { "200": { "description": "Activity feed retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "activities": { "type": "array", "items": { "properties": { "id": { "description": "Unique identifier for the activity", "type": "string", "example": "test_assigned_123" }, "action": { "type": "string", "enum": [ "test_assigned", "test_completed", "student_joined", "teacher_assigned" ], "example": "test_assigned" }, "title": { "type": "string", "example": "Weekly Math Quiz" }, "description": { "type": "string", "example": "New test assigned by Mr. Sharma" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-01-01T10:00:00Z" }, "related_id": { "description": "ID of the related resource (test, student, teacher)", "type": "integer", "example": 101, "nullable": true }, "related_type": { "type": "string", "enum": [ "test", "test_result", "student", "teacher" ], "example": "test", "nullable": true } }, "type": "object" } }, "total_count": { "type": "integer", "example": 15 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Not enrolled in this batch", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not enrolled in this batch" } }, "type": "object" } } } }, "404": { "description": "Batch not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch not found" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve batch activity" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/student/batches/{batch_id}/my-activity": { "get": { "tags": [ "Student - Enrollment" ], "summary": "Get student's own activity in a batch", "description": "Retrieves the authenticated student's personal activity timeline within a specific batch. Shows when the student joined the batch, tests they completed with scores, and tests they started. This is different from the batch activity feed which shows all activities in the batch.", "operationId": "getStudentActivityInBatch", "parameters": [ { "name": "batch_id", "in": "path", "description": "Batch/Group ID", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1, "example": 1 } }, { "name": "limit", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1, "example": 20 } } ], "responses": { "200": { "description": "Student activity retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "summary": { "properties": { "total_activities": { "description": "Total number of activities for this student", "type": "integer", "example": 5 }, "tests_completed": { "description": "Number of tests completed", "type": "integer", "example": 3 }, "tests_in_progress": { "description": "Number of tests started but not completed", "type": "integer", "example": 1 }, "joined_at": { "description": "When the student joined this batch", "type": "string", "format": "date-time", "example": "2025-12-01T10:00:00Z" } }, "type": "object" }, "activities": { "type": "array", "items": { "properties": { "id": { "description": "Unique identifier for the activity", "type": "string", "example": "test_completed_123" }, "action": { "type": "string", "enum": [ "joined_batch", "test_completed", "test_started" ], "example": "test_completed" }, "title": { "type": "string", "example": "Weekly Math Quiz" }, "description": { "type": "string", "example": "You scored 38/40 (95%)" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-01-05T14:30:00Z" }, "related_id": { "description": "ID of the related resource (batch, test)", "type": "integer", "example": 101 }, "related_type": { "type": "string", "enum": [ "batch", "test" ], "example": "test" }, "score": { "description": "Score obtained (only for test_completed)", "type": "number", "example": 38, "nullable": true }, "total_marks": { "description": "Total marks (only for test_completed)", "type": "number", "example": 40, "nullable": true }, "percentage": { "description": "Percentage score (only for test_completed)", "type": "number", "example": 95, "nullable": true } }, "type": "object" } }, "total_count": { "type": "integer", "example": 5 }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Not enrolled in this batch", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not enrolled in this batch" } }, "type": "object" } } } }, "404": { "description": "Batch not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch not found" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve student activity" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/student/batches/{batch_id}/leave": { "delete": { "tags": [ "Student - Enrollment" ], "summary": "Leave a batch (un-enroll)", "description": "Allows a student to un-enroll from a batch they are currently enrolled in. This permanently removes the student from the batch.", "operationId": "leaveBatch", "parameters": [ { "name": "batch_id", "in": "path", "description": "Batch/Group ID to leave", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Successfully left the batch", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Successfully left the batch" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Not enrolled in this batch", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not enrolled in this batch" } }, "type": "object" } } } }, "404": { "description": "Batch not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch not found" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to leave batch" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/student/batches/{batch_id}/syllabus": { "get": { "tags": [ "Student - Enrollment" ], "summary": "Get batch syllabus", "description": "Retrieves the syllabus assigned to a specific batch that the student is enrolled in. Returns syllabus details including title, dates, completion progress, and current week information.", "operationId": "getBatchSyllabus", "parameters": [ { "name": "batch_id", "in": "path", "description": "Batch/Group ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Syllabus retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "syllabus": { "properties": { "id": { "description": "Syllabus ID", "type": "integer", "example": 1 }, "batch_id": { "description": "Batch ID", "type": "integer", "example": 1 }, "batch_name": { "description": "Batch name", "type": "string", "example": "Mathematics Excellence" }, "title": { "description": "Syllabus title", "type": "string", "example": "Class 10 Mathematics - Complete Syllabus" }, "start_date": { "description": "Syllabus start date", "type": "string", "format": "date", "example": "2025-12-01" }, "end_date": { "description": "Syllabus end date", "type": "string", "format": "date", "example": "2026-02-28" }, "total_weeks": { "description": "Total number of weeks in the syllabus", "type": "integer", "example": 10 }, "completion_percentage": { "description": "Overall completion percentage", "type": "number", "format": "float", "example": 35 }, "total_topics": { "description": "Total number of topics in syllabus", "type": "integer", "example": 20 }, "completed_topics": { "description": "Number of topics completed", "type": "integer", "example": 7 }, "current_week": { "description": "Current week number (null if not started)", "type": "integer", "example": 4, "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Not enrolled in this batch", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not enrolled in this batch" } }, "type": "object" } } } }, "404": { "description": "Batch not found or No syllabus found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No syllabus found for this batch" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve batch syllabus" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/student/syllabus/{syllabus_id}": { "get": { "tags": [ "Student - Enrollment" ], "summary": "Get detailed syllabus with all topics", "description": "Retrieves detailed information about a specific syllabus including all topics organized by week, their completion status, and associated tests. This endpoint provides the full syllabus breakdown for students to view all topics and their scheduled dates.", "operationId": "getSyllabusDetails", "parameters": [ { "name": "syllabus_id", "in": "path", "description": "Syllabus ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Syllabus details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "syllabus": { "properties": { "id": { "description": "Syllabus ID", "type": "integer", "example": 1 }, "batch_id": { "description": "Batch ID", "type": "integer", "example": 1 }, "title": { "description": "Syllabus title", "type": "string", "example": "Class 10 Mathematics - Complete Syllabus" }, "start_date": { "description": "Syllabus start date", "type": "string", "format": "date", "example": "2025-12-01" }, "end_date": { "description": "Syllabus end date", "type": "string", "format": "date", "example": "2026-02-28" }, "total_weeks": { "description": "Total number of weeks in the syllabus", "type": "integer", "example": 10 }, "completion_percentage": { "description": "Overall completion percentage", "type": "number", "format": "float", "example": 35 }, "total_topics": { "description": "Total number of topics in syllabus", "type": "integer", "example": 20 }, "completed_topics": { "description": "Number of topics completed", "type": "integer", "example": 7 }, "current_week": { "description": "Current week number (null if not started)", "type": "integer", "example": 4, "nullable": true }, "topics": { "type": "array", "items": { "properties": { "topic_id": { "description": "Topic ID", "type": "integer", "example": 101 }, "title": { "description": "Topic title/name", "type": "string", "example": "Quadratic Equations" }, "description": { "description": "Topic description", "type": "string", "example": null, "nullable": true }, "week_number": { "description": "Week number for this topic", "type": "integer", "example": 1 }, "scheduled_date": { "description": "Scheduled date for this topic", "type": "string", "format": "date", "example": "2025-12-01" }, "is_completed": { "description": "Whether the topic is marked as completed", "type": "boolean", "example": false }, "test_generated": { "description": "Whether a test has been generated for this topic", "type": "boolean", "example": true }, "test_id": { "description": "ID of the associated test (if any)", "type": "integer", "example": 201, "nullable": true }, "test_name": { "description": "Name of the associated test (if any)", "type": "string", "example": "Week 1 Test", "nullable": true } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Not enrolled in the batch associated with this syllabus", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not enrolled in this batch" } }, "type": "object" } } } }, "404": { "description": "Syllabus or batch not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Syllabus not found" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve syllabus details" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/student/syllabus/{syllabus_id}/progress": { "get": { "tags": [ "Student - Enrollment" ], "summary": "Get syllabus progress", "description": "Retrieves the student's progress on a specific syllabus, including completion percentage, topic counts, and progress tracking metrics. This endpoint helps students understand if they are on track with the syllabus.", "operationId": "getSyllabusProgress", "parameters": [ { "name": "syllabus_id", "in": "path", "description": "Syllabus ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Syllabus progress retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "progress": { "properties": { "syllabus_id": { "description": "Syllabus ID", "type": "integer", "example": 1 }, "completion_percentage": { "description": "Overall completion percentage", "type": "number", "format": "float", "example": 35 }, "total_topics": { "description": "Total number of topics in syllabus", "type": "integer", "example": 20 }, "completed_topics": { "description": "Number of topics completed", "type": "integer", "example": 7 }, "overdue_topics": { "description": "Number of topics that are overdue (past scheduled date but not completed)", "type": "integer", "example": 1 }, "upcoming_topics": { "description": "Number of upcoming topics (scheduled in next 7 days)", "type": "integer", "example": 12 }, "weeks_completed": { "description": "Number of weeks fully completed (all topics in week completed)", "type": "integer", "example": 3 }, "current_week": { "description": "Current week number (null if not started)", "type": "integer", "example": 4, "nullable": true }, "total_weeks": { "description": "Total number of weeks in the syllabus", "type": "integer", "example": 10 }, "on_track": { "description": "Whether the student is on track with expected progress", "type": "boolean", "example": false }, "message": { "description": "Human-readable progress message", "type": "string", "example": "You are 1 topic behind schedule" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Not enrolled in the batch associated with this syllabus", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not enrolled in this batch" } }, "type": "object" } } } }, "404": { "description": "Syllabus or batch not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Syllabus not found" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve syllabus progress" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/subscriptions/verify": { "post": { "tags": [ "Tutor V2" ], "summary": "Verify subscription payment", "description": "Verifies the payment for a subscription purchase.", "operationId": "verifySubscriptionPayment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "payment_id", "order_id", "signature" ], "properties": { "payment_id": { "type": "string", "example": "pay_293839" }, "order_id": { "type": "string", "example": "order_DBJOWzyhf0fzUK" }, "signature": { "type": "string", "example": "signature_string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment verified and subscription activated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Subscription activated successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "400": { "description": "Verification failed" } }, "security": [ { "sanctum": [] } ] } }, "/api/teacher/questions/debug-database": { "get": { "tags": [ "Tutor V2" ], "summary": "Debug question database", "operationId": "teacherDebugQuestionDatabase", "responses": { "200": { "description": "Debug info retrieved successfully" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/dashboard": { "get": { "tags": [ "Tutor V2" ], "summary": "Get tutor dashboard with statistics", "description": "Retrieves comprehensive dashboard data including student count, test series count, wallet balance, upcoming tests, and recent activities.", "operationId": "getTutorDashboard", "parameters": [ { "name": "days", "in": "query", "description": "Number of days for recent activities (1-30)", "required": false, "schema": { "type": "integer", "default": 7, "maximum": 30, "minimum": 1 } } ], "responses": { "200": { "description": "Dashboard data retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Dashboard data fetched successfully" }, "data": { "properties": { "total_students": { "description": "Total number of students", "type": "integer", "example": 150 }, "classes_count": { "description": "Number of distinct classes taught", "type": "integer", "example": 5 }, "test_series_count": { "description": "Total test series created", "type": "integer", "example": 25 }, "wallet_balance": { "description": "Current wallet balance", "type": "number", "format": "float", "example": 5000.5 }, "upcoming_test_series": { "description": "List of upcoming tests", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Mathematics Final Test" }, "from": { "type": "string", "format": "date-time", "example": "2025-12-20 10:00:00" }, "to": { "type": "string", "format": "date-time", "example": "2025-12-20 12:00:00" }, "duration": { "description": "Duration in minutes", "type": "integer", "example": 120 } }, "type": "object" } }, "recent_submissions": { "description": "Recent test submissions by students", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 50 }, "user_name": { "type": "string", "example": "Student Name" }, "testseries_id": { "type": "integer", "example": 10 }, "testseries_name": { "type": "string", "example": "Math Test" }, "submitted_at": { "type": "string", "format": "date-time" }, "type": { "type": "string", "example": "submission" } }, "type": "object" } }, "recent_enrollments": { "description": "Recent student enrollments", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "student_id": { "type": "integer", "example": 50 }, "student_name": { "type": "string", "example": "Student Name" }, "enrolled_at": { "type": "string", "format": "date-time" }, "type": { "type": "string", "example": "enrollment" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Not a tutor" }, "422": { "description": "Validation error" }, "500": { "description": "Internal server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/categories/topics": { "get": { "tags": [ "Tutor V2" ], "summary": "List all topics", "description": "Retrieves a list of all topics/chapters with optional subject filtering.", "operationId": "listTopics", "parameters": [ { "name": "subject_id", "in": "query", "description": "Filter topics by subject ID", "required": false, "schema": { "type": "integer" } }, { "name": "class_id", "in": "query", "description": "Filter topics by class ID", "required": false, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Search topics by name", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Topics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Topics fetched successfully" }, "data": { "properties": { "topics": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 150 }, "name": { "type": "string", "example": "Algebra" }, "description": { "type": "string", "nullable": true }, "subject_id": { "type": "integer", "example": 90 }, "subject_name": { "type": "string", "example": "Mathematics" }, "class_id": { "type": "integer", "example": 86 }, "class_name": { "type": "string", "example": "Class 10" }, "question_count": { "description": "Number of questions in this topic", "type": "integer", "example": 50 }, "order": { "type": "integer", "example": 1 } }, "type": "object" } }, "pagination": { "properties": { "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 5 }, "total": { "type": "integer", "example": 125 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/export-docx": { "post": { "tags": [ "Tutor V2 - Export & Assignment" ], "summary": "Export test series to DOCX format", "description": "Exports the test series questions and answers to a DOCX document for offline distribution", "operationId": "tutorV2ExportTestSeriesToDocx", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "include_answer_key": { "description": "Include answer key in the document", "type": "boolean", "example": false }, "format": { "description": "Format type: question_paper or full_test", "type": "string", "example": "question_paper" } }, "type": "object" } } } }, "responses": { "200": { "description": "DOCX file exported successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series exported successfully" }, "data": { "properties": { "download_url": { "type": "string", "example": "https://example.com/exports/test-series-123.docx" }, "file_name": { "type": "string", "example": "test-series-123.docx" }, "file_size": { "type": "string", "example": "2.5 MB" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/export-answer-key": { "post": { "tags": [ "Tutor V2 - Export & Assignment" ], "summary": "Export standalone answer key", "description": "Exports only the answer key for a test series as a separate PDF or DOCX document", "operationId": "tutorV2ExportAnswerKey", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "format": { "description": "Export format: pdf or docx", "type": "string", "example": "pdf" }, "include_solutions": { "description": "Include detailed solutions", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Answer key exported successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Answer key exported successfully" }, "data": { "properties": { "download_url": { "type": "string", "example": "https://example.com/exports/answer-key-123.pdf" }, "file_name": { "type": "string", "example": "answer-key-123.pdf" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/copy-assignments-to-variants": { "post": { "tags": [ "Tutor V2 - Export & Assignment" ], "summary": "Copy group assignments to test variants", "description": "Copies the group assignments from the parent test series to all its variants", "operationId": "tutorV2CopyAssignmentsToVariants", "parameters": [ { "name": "id", "in": "path", "description": "Parent Test Series ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "variant_ids": { "description": "Specific variant IDs (optional, copies to all if not provided)", "type": "array", "items": { "type": "integer" }, "example": [ 2, 3, 4 ] }, "override_existing": { "description": "Override existing assignments", "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "200": { "description": "Assignments copied successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Assignments copied to 3 variants successfully" }, "data": { "properties": { "variants_updated": { "type": "integer", "example": 3 }, "groups_copied": { "type": "integer", "example": 5 }, "variants": { "type": "array", "items": { "properties": { "variant_id": { "type": "integer", "example": 2 }, "variant_name": { "type": "string", "example": "Variant B" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series not found" }, "422": { "description": "No variants found" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/create-paper": { "post": { "tags": [ "Tutor V2" ], "summary": "Create a paper/test", "description": "Creates a paper/test with questions from the question bank or custom questions.", "operationId": "createPaper", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "class_id", "subject_id" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "Mathematics Mid-Term Exam" }, "description": { "type": "string", "example": "Mid-term examination covering chapters 1-5", "nullable": true }, "class_id": { "type": "integer", "example": 86 }, "subject_id": { "type": "integer", "example": 90 }, "duration_minutes": { "type": "integer", "example": 120 }, "total_marks": { "type": "number", "format": "float", "example": 100 }, "question_selection": { "description": "Question selection criteria", "properties": { "method": { "type": "string", "enum": [ "manual", "auto", "topic_wise" ], "example": "topic_wise" }, "topic_distribution": { "type": "array", "items": { "properties": { "topic_id": { "type": "integer", "example": 150 }, "question_count": { "type": "integer", "example": 5 }, "difficulty_mix": { "properties": { "easy": { "type": "integer", "example": 2 }, "medium": { "type": "integer", "example": 2 }, "hard": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } }, "question_ids": { "description": "Manual question selection", "type": "array", "items": { "type": "integer" } } }, "type": "object" }, "negative_marking": { "type": "boolean", "example": true }, "negative_marking_value": { "type": "number", "format": "float", "example": 0.25 }, "shuffle_questions": { "type": "boolean", "example": false }, "shuffle_options": { "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "201": { "description": "Paper created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Paper created successfully" }, "data": { "properties": { "paper_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Mathematics Mid-Term Exam" }, "total_questions": { "type": "integer", "example": 25 }, "total_marks": { "type": "number", "example": 100 }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/question-bank": { "get": { "tags": [ "Tutor V2 - Question Bank" ], "summary": "Get question bank with filters", "description": "Retrieves questions from the question bank with optional filtering by category, difficulty, and type", "operationId": "getQuestionBank", "parameters": [ { "name": "category_id", "in": "query", "description": "Filter by category/subject/topic ID", "required": false, "schema": { "type": "integer", "example": 89 } }, { "name": "difficulty_level", "in": "query", "description": "Filter by difficulty: easy, medium, hard", "required": false, "schema": { "type": "string", "example": "medium" } }, { "name": "question_type", "in": "query", "description": "Filter by type: mcq, true_false, subjective", "required": false, "schema": { "type": "string", "example": "mcq" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Question bank retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Questions retrieved successfully" }, "data": { "properties": { "total": { "type": "integer", "example": 150 }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "questions": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "question_text": { "type": "string", "example": "What is Newton's first law?" }, "option_a": { "type": "string", "example": "Law of inertia" }, "option_b": { "type": "string", "example": "Law of acceleration" }, "option_c": { "type": "string", "example": "Law of action-reaction" }, "option_d": { "type": "string", "example": "Law of gravitation" }, "correct_answer": { "type": "string", "example": "a" }, "difficulty_level": { "type": "string", "example": "medium" }, "marks": { "type": "integer", "example": 2 }, "category_id": { "type": "integer", "example": 89 }, "category_name": { "type": "string", "example": "Physics - Mechanics" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/auto-generate-paper-from-chapter": { "post": { "tags": [ "Tutor V2 - Paper Creation" ], "summary": "Auto-generate paper from chapter", "description": "Automatically generates a test paper by selecting questions from specified chapters/topics", "operationId": "autoGeneratePaperFromChapter", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "chapter_ids", "total_questions" ], "properties": { "chapter_ids": { "description": "Array of chapter/topic IDs", "type": "array", "items": { "type": "integer" }, "example": [ 10, 11, 12 ] }, "total_questions": { "description": "Total number of questions to generate", "type": "integer", "example": 30 }, "difficulty_distribution": { "properties": { "easy": { "description": "Number of easy questions", "type": "integer", "example": 10 }, "medium": { "description": "Number of medium questions", "type": "integer", "example": 15 }, "hard": { "description": "Number of hard questions", "type": "integer", "example": 5 } }, "type": "object" }, "title": { "description": "Paper title", "type": "string", "example": "Auto-generated Physics Test" }, "duration_minutes": { "description": "Test duration", "type": "integer", "example": 60 }, "marks_per_question": { "description": "Marks for each question", "type": "integer", "example": 2 } }, "type": "object" } } } }, "responses": { "201": { "description": "Paper auto-generated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Paper auto-generated successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 101 }, "title": { "type": "string", "example": "Auto-generated Physics Test" }, "total_questions": { "type": "integer", "example": 30 }, "total_marks": { "type": "integer", "example": 60 }, "difficulty_breakdown": { "properties": { "easy": { "type": "integer", "example": 10 }, "medium": { "type": "integer", "example": 15 }, "hard": { "type": "integer", "example": 5 } }, "type": "object" }, "chapters_covered": { "type": "array", "items": { "type": "string" }, "example": [ "Mechanics", "Thermodynamics", "Optics" ] } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error or insufficient questions" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/get-chapters-for-paper-generation": { "post": { "tags": [ "Tutor V2 - Paper Creation" ], "summary": "Get chapters available for paper generation", "description": "Retrieves list of chapters/topics with question counts for a given subject or class", "operationId": "getChaptersForPaperGeneration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "subject_id": { "description": "Subject/Category ID", "type": "integer", "example": 1 }, "class_id": { "description": "Class/Grade ID (optional)", "type": "integer", "example": 10 } }, "type": "object" } } } }, "responses": { "200": { "description": "Chapters retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Chapters retrieved successfully" }, "data": { "properties": { "subject_id": { "type": "integer", "example": 1 }, "subject_name": { "type": "string", "example": "Physics" }, "total_chapters": { "type": "integer", "example": 15 }, "chapters": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Mechanics" }, "question_count": { "type": "integer", "example": 50 }, "difficulty_breakdown": { "properties": { "easy": { "type": "integer", "example": 15 }, "medium": { "type": "integer", "example": 25 }, "hard": { "type": "integer", "example": 10 } }, "type": "object" }, "is_sufficient": { "description": "Has enough questions for auto-generation", "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/class-details": { "get": { "tags": [ "Tutor V2 - Class Management" ], "summary": "View class/batch details", "description": "Retrieves detailed information about a specific class or batch", "operationId": "viewClassDetails", "parameters": [ { "name": "class_id", "in": "query", "description": "Class/Batch ID", "required": true, "schema": { "type": "integer", "example": 89 } } ], "responses": { "200": { "description": "Class details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Class details retrieved successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 89 }, "name": { "type": "string", "example": "Physics Batch A" }, "description": { "type": "string", "example": "Advanced physics batch" }, "student_count": { "type": "integer", "example": 30 }, "test_series_count": { "type": "integer", "example": 5 }, "created_at": { "type": "string", "example": "2025-01-01 10:00:00" }, "students": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Class not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/profile": { "get": { "tags": [ "Tutor V2" ], "summary": "Get tutor profile", "operationId": "getTutorProfileV2", "responses": { "200": { "description": "Profile retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Tutor V2" ], "summary": "Update tutor profile", "operationId": "updateTutorProfileV2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated successfully" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/questions": { "get": { "tags": [ "Tutor V2" ], "summary": "List all questions", "description": "Retrieves a paginated list of questions with filtering options. For topic-wise filtering from the category CSV, pass category_id, class_id, and subject_id together.", "operationId": "tutorListQuestions", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100 } }, { "name": "keyword", "in": "query", "description": "Search keyword (min 2 characters) - searches in question text, translations, options, and solution", "required": false, "schema": { "type": "string", "minLength": 2 } }, { "name": "category_id", "in": "query", "description": "Filter by category/topic ID (supports multiple comma-separated IDs). Use with class_id and subject_id for contextual filtering.", "required": false, "schema": { "type": "string", "example": "1790,1791" } }, { "name": "class_id", "in": "query", "description": "Filter by class ID (must be used with category_id and subject_id for contextual filtering)", "required": false, "schema": { "type": "integer" } }, { "name": "subject_id", "in": "query", "description": "Filter by subject ID (must be used with category_id and class_id for contextual filtering)", "required": false, "schema": { "type": "integer" } }, { "name": "question_type", "in": "query", "description": "Filter by question type", "required": false, "schema": { "type": "string", "enum": [ "mcq", "numerical", "true_false", "fill_blank", "subjective" ] } }, { "name": "answer_type", "in": "query", "description": "Filter by answer type (supports multiple comma-separated values)", "required": false, "schema": { "type": "string", "example": "single,multiple" } }, { "name": "from_date", "in": "query", "description": "Filter questions created on or after this date", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "to_date", "in": "query", "description": "Filter questions created on or before this date", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-12-31" } }, { "name": "min_marks", "in": "query", "description": "Minimum marks filter", "required": false, "schema": { "type": "number", "minimum": 0 } }, { "name": "max_marks", "in": "query", "description": "Maximum marks filter", "required": false, "schema": { "type": "number", "minimum": 0 } }, { "name": "added_by_type", "in": "query", "description": "Filter by source type (ai/self/admin)", "required": false, "schema": { "type": "string", "enum": [ "tutor_manual", "tutor_ai_generated", "admin_manual", "admin_ai_generated" ] } } ], "responses": { "200": { "description": "Questions retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Questions retrieved successfully" }, "data": { "properties": { "current_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "question": { "type": "string" }, "question_type": { "type": "string", "example": "mcq" }, "answer_type": { "type": "string", "example": "single" }, "marks": { "type": "number", "example": 4 }, "difficulty": { "type": "string", "example": "medium" }, "time": { "type": "integer", "example": 60 }, "category_id": { "type": "string", "example": "1790" }, "status": { "type": "integer", "example": 1 }, "added_by": { "type": "integer", "example": 1 }, "added_by_type": { "type": "string", "example": "self" }, "translation": { "properties": { "question_text": { "type": "string" }, "option_a": { "type": "string" }, "option_b": { "type": "string" }, "option_c": { "type": "string" }, "option_d": { "type": "string" }, "solution": { "type": "string" } }, "type": "object", "nullable": true }, "available_languages": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "per_page": { "type": "integer", "example": 10 }, "total": { "type": "integer", "example": 300 }, "last_page": { "type": "integer", "example": 30 } }, "type": "object" }, "filters_applied": { "properties": { "keyword": { "type": "string", "nullable": true }, "category_id": { "type": "string", "nullable": true }, "class_id": { "type": "integer", "nullable": true }, "subject_id": { "type": "integer", "nullable": true }, "question_type": { "type": "string", "nullable": true }, "answer_type": { "type": "string", "nullable": true }, "from_date": { "type": "string", "nullable": true }, "to_date": { "type": "string", "nullable": true }, "min_marks": { "type": "number", "nullable": true }, "max_marks": { "type": "number", "nullable": true }, "added_by_type": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/results/test/{testId}": { "get": { "tags": [ "Tutor V2" ], "summary": "Get test results", "description": "Retrieves comprehensive results for a specific test including all student submissions and scores.", "operationId": "getTestResults", "parameters": [ { "name": "testId", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } }, { "name": "batch_id", "in": "query", "description": "Filter by batch ID", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Test results retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test results fetched successfully" }, "data": { "properties": { "test_id": { "type": "integer", "example": 1 }, "test_name": { "type": "string", "example": "Mathematics Chapter 1 Test" }, "total_students": { "type": "integer", "example": 30 }, "attempted_count": { "type": "integer", "example": 25 }, "pending_count": { "type": "integer", "example": 5 }, "average_score": { "type": "number", "format": "float", "example": 72.5 }, "highest_score": { "type": "number", "format": "float", "example": 98 }, "lowest_score": { "type": "number", "format": "float", "example": 45 }, "results": { "type": "array", "items": { "properties": { "student_id": { "type": "integer", "example": 50 }, "student_name": { "type": "string", "example": "John Doe" }, "score": { "type": "number", "format": "float", "example": 85 }, "percentage": { "type": "number", "format": "float", "example": 85 }, "rank": { "type": "integer", "example": 3 }, "time_taken": { "description": "Time taken in minutes", "type": "integer", "example": 55 }, "correct_answers": { "type": "integer", "example": 20 }, "incorrect_answers": { "type": "integer", "example": 5 }, "unattempted": { "type": "integer", "example": 0 }, "submitted_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Test not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/analytics/batch/{batchId}/test/{testId}": { "get": { "tags": [ "Tutor V2" ], "summary": "Get batch analytics for test", "description": "\n# API Purpose\nThis API provides comprehensive analytics for a specific test within a batch, designed for tutors to track student performance and identify learning trends.\n\n# Business Logic Flow\n1. **Authentication & Authorization**: Verifies the tutor is logged in via Sanctum and owns the batch\n2. **Data Retrieval**: Fetches all student enrollments and test results for the specified batch/test combination\n3. **Analytics Calculation**: Computes four main categories:\n - Overall Statistics (averages, pass/fail rates)\n - Score Distribution (grouped into 4 ranges)\n - Topic-wise Performance (accuracy by question category)\n - Time Analysis (fastest/slowest/average completion times)\n4. **Caching**: Results are cached for 1 hour to improve performance\n5. **Response**: Returns structured JSON with chart-ready data\n\n# Database Tables & Columns Used\n\n## Primary Tables:\n1. **create_groups** (Batch Information)\n - Columns: id, user_id, name\n - Purpose: Validates batch ownership and retrieves batch name\n - Query: WHERE id = {batchId} AND user_id = {authenticated_user_id}\n\n2. **testseries** (Test Series Information)\n - Columns: id, name\n - Purpose: Validates test exists and retrieves test name\n - Query: WHERE id = {testId}\n\n3. **school_enrollments** (Student Enrollments)\n - Columns: id, user_id, group_id\n - Purpose: Gets all students enrolled in the batch\n - Query: WHERE group_id = {batchId}\n - Returns: Array of user_ids\n\n4. **testresult** (Test Results)\n - Columns: id, user_id, testseries_id, total_marks, obtained_marks, created_at, result_submited\n - Purpose: Gets all test results for students in this batch\n - Query: WHERE testseries_id = {testId} AND user_id IN (student_ids_from_enrollments)\n - Used for: Overall statistics, score distribution\n\n5. **stu_testseries_analysis** (Question-level Analysis)\n - Columns: testresult_id, testseries_id, question_id, question_status, total_time\n - Purpose: Detailed question-by-question performance tracking\n - Query: WHERE testresult_id IN (test_result_ids) AND testseries_id = {testId}\n - Used for: Topic-wise performance, time analysis\n\n6. **questions** (Question Details)\n - Columns: id, category_id\n - Purpose: Links questions to their topics/categories\n - Query: WHERE id IN (question_ids_from_analysis)\n - Relationship: Eager loads category relationship\n\n7. **categories** (Topic/Category Information)\n - Columns: id, category_name\n - Purpose: Provides topic names for topic-wise performance\n - Query: Loaded via questions->category relationship\n\n## Data Relationships:\n```\ncreate_groups (batch)\n └─> school_enrollments (students in batch)\n └─> testresult (student test submissions)\n └─> stu_testseries_analysis (question-level data)\n └─> questions (question metadata)\n └─> categories (topic names)\n```\n\n# Validation Rules\n- **batchId** (path param): Required, integer, must exist in create_groups table\n- **testId** (path param): Required, integer, must exist in testseries table\n- **Authorization**: Authenticated tutor must be the owner of the batch (create_groups.user_id = auth.user.id)\n\n# Calculation Logic\n\n## Overall Statistics:\n- **total_participants**: COUNT of testresult records\n- **average_score**: AVG((obtained_marks / total_marks) * 100)\n- **highest_score**: MAX((obtained_marks / total_marks) * 100)\n- **lowest_score**: MIN((obtained_marks / total_marks) * 100)\n- **pass_percentage**: (COUNT where percentage >= 40) / total_participants * 100\n- **completion_rate**: (COUNT where result_submited = 1) / total_participants * 100\n- **passed_students**: COUNT where percentage >= 40\n- **failed_students**: COUNT where percentage < 40\n\n## Score Distribution:\nGroups students into 4 fixed ranges based on percentage:\n- 0-25%: percentage >= 0 AND percentage <= 25\n- 26-50%: percentage > 25 AND percentage <= 50\n- 51-75%: percentage > 50 AND percentage <= 75\n- 76-100%: percentage > 75\n\n## Topic-wise Performance:\n1. Aggregates stu_testseries_analysis by question_id\n2. Maps questions to categories via questions.category_id\n3. For each category:\n - total_attempts: COUNT of all question attempts in that category\n - correct_answers: COUNT where question_status = 1\n - accuracy: (correct_answers / total_attempts) * 100\n4. weak_topics: Filters topics where accuracy < 50%\n5. Sorted by accuracy (ascending) - weakest topics first\n\n## Time Analysis:\n- Aggregates stu_testseries_analysis.total_time grouped by testresult_id\n- **average_time_seconds**: AVG(SUM(total_time) per student)\n- **fastest_time_seconds**: MIN(SUM(total_time) per student)\n- **slowest_time_seconds**: MAX(SUM(total_time) per student)\n- All formatted to HH:MM:SS format\n\n# Caching Strategy\n- Cache Key: analytics_batch_{batchId}_test_{testId}\n- Duration: 3600 seconds (1 hour)\n- Can be cleared via AnalyticsService->clearCache(batchId, testId)\n\n# Empty Data Handling\nReturns empty analytics structure with zero values if:\n- No students enrolled in batch\n- No test results available\n- No question analysis data\n\n# Notes\n- question_status values: 1 = correct, 0 = incorrect, 2 = skipped\n- Time is stored in seconds in database\n- Pass threshold is hardcoded at 40%\n- All percentages rounded to 2 decimal places\n", "operationId": "getBatchAnalytics", "parameters": [ { "name": "batchId", "in": "path", "description": "Batch ID", "required": true, "schema": { "type": "integer", "example": 3 } }, { "name": "testId", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer", "example": 56 } } ], "responses": { "200": { "description": "Analytics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Analytics retrieved successfully" }, "data": { "properties": { "batch_id": { "description": "ID of the batch", "type": "integer", "example": 3 }, "test_id": { "description": "ID of the test series", "type": "integer", "example": 56 }, "test_series_name": { "description": "Name of the test series", "type": "string", "example": "Mathematics Final Test" }, "batch_name": { "description": "Name of the batch", "type": "string", "example": "NEET 2025 Batch A" }, "generated_at": { "description": "Timestamp when analytics were generated", "type": "string", "format": "date-time", "example": "2025-12-27 10:30:45" }, "overall_statistics": { "description": "Overall performance statistics", "properties": { "total_participants": { "description": "Total number of students who attempted the test", "type": "integer", "example": 3 }, "average_score": { "description": "Average percentage score", "type": "number", "format": "float", "example": 79.11 }, "highest_score": { "description": "Highest percentage score", "type": "number", "format": "float", "example": 88.61 }, "lowest_score": { "description": "Lowest percentage score", "type": "number", "format": "float", "example": 69.62 }, "pass_percentage": { "description": "Percentage of students who passed (>=40%)", "type": "number", "format": "float", "example": 100 }, "completion_rate": { "description": "Percentage of students who completed the test", "type": "number", "format": "float", "example": 0 }, "passed_students": { "description": "Number of students who passed", "type": "integer", "example": 3 }, "failed_students": { "description": "Number of students who failed", "type": "integer", "example": 0 } }, "type": "object" }, "score_distribution": { "description": "Score distribution data", "properties": { "ranges": { "description": "Detailed breakdown by score ranges with 4 predefined ranges", "type": "array", "items": { "properties": { "range": { "type": "string", "example": "51-75%" }, "count": { "description": "Number of students in this range", "type": "integer", "example": 1 }, "percentage": { "description": "Percentage of total students", "type": "number", "format": "float", "example": 33.33 } }, "type": "object" } }, "chart_labels": { "description": "Fixed array of 4 labels for charting: [0-25%, 26-50%, 51-75%, 76-100%]", "type": "array", "items": { "type": "string" }, "example": [ "0-25%", "26-50%", "51-75%", "76-100%" ] }, "chart_data": { "description": "Count of students in each range for charting. Array of 4 integers matching chart_labels.", "type": "array", "items": { "type": "integer" }, "example": [ 0, 0, 1, 2 ] } }, "type": "object" }, "topic_wise_performance": { "description": "Performance analysis by topic/category. Arrays may be empty if no topic data is available.", "properties": { "topics": { "description": "All topics sorted by accuracy (weakest first). Empty array if no topic data available.", "type": "array", "items": { "properties": { "topic_name": { "type": "string", "example": "Algebra" }, "accuracy": { "description": "Accuracy percentage for this topic", "type": "number", "format": "float", "example": 65.5 }, "total_questions": { "description": "Total questions attempted across all students", "type": "integer", "example": 120 }, "correct_answers": { "description": "Total correct answers across all students", "type": "integer", "example": 78 } }, "type": "object" } }, "weak_topics": { "description": "Topics with accuracy below 50%. Empty array if no weak topics or no topic data.", "type": "array", "items": { "properties": { "topic_name": { "type": "string", "example": "Geometry" }, "accuracy": { "type": "number", "format": "float", "example": 42.5 }, "total_questions": { "type": "integer", "example": 80 }, "correct_answers": { "type": "integer", "example": 34 } }, "type": "object" } }, "chart_labels": { "description": "Topic names for charting. Empty array if no topic data.", "type": "array", "items": { "type": "string", "example": "Algebra" } }, "chart_data": { "description": "Accuracy percentages for charting. Empty array if no topic data.", "type": "array", "items": { "type": "number", "example": 65.5 } } }, "type": "object" }, "time_analysis": { "description": "Time analysis across all students", "properties": { "average_time_seconds": { "description": "Average time taken in seconds", "type": "integer", "example": 1800 }, "average_time_formatted": { "description": "Average time in HH:MM:SS format", "type": "string", "example": "00:30:00" }, "fastest_time_seconds": { "description": "Fastest completion time in seconds", "type": "integer", "example": 1500 }, "fastest_time_formatted": { "description": "Fastest time in HH:MM:SS format", "type": "string", "example": "00:25:00" }, "slowest_time_seconds": { "description": "Slowest completion time in seconds", "type": "integer", "example": 2100 }, "slowest_time_formatted": { "description": "Slowest time in HH:MM:SS format", "type": "string", "example": "00:35:00" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Forbidden - Batch does not belong to tutor", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch not found or you do not have permission to access it" } }, "type": "object" } } } }, "404": { "description": "Test not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Test not found" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve analytics" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/leaderboard/test/{testId}": { "get": { "tags": [ "Tutor V2" ], "summary": "Get global leaderboard", "description": "\n# API Purpose\nThis API retrieves a global ranked leaderboard for a specific test across ALL batches and students, sorted by score (highest first) with time-based tie-breaking. Unlike the batch leaderboard, this shows competitive ranking across the entire platform for the test. Designed to help tutors see how their students compare globally and identify top performers across all batches.\n\n# Business Logic Flow\n1. **Authentication**: Verifies user is logged in via Sanctum (any authenticated user can access)\n2. **Validation**: Validates limit parameter (must be 10, 20, 50, or 100; defaults to 50)\n3. **Test Verification**: Confirms test exists in database\n4. **Data Collection**: Fetches ALL submitted test results for this test (no batch filtering)\n5. **Time Aggregation**: Calculates total time spent per student from question-level analysis\n6. **User Data Enrichment**: Retrieves student names and details in bulk\n7. **Ranking Algorithm**:\n - Primary sort: Score (percentage) in descending order (highest score = rank 1)\n - Tie-breaker: Time taken in ascending order (faster completion wins)\n8. **Rank Assignment**: Assigns sequential global ranks (1, 2, 3, ...) to sorted entries\n9. **Current User Rank**: Calculates logged-in user's rank if they took the test\n10. **Caching**: Results cached for 30 minutes to optimize performance\n11. **Limit Application**: Returns only top N students based on limit parameter\n\n# Key Difference from Batch Leaderboard\n- **Global Scope**: Shows ALL students who took the test (no batch filtering)\n- **No Authorization Check**: Doesn't verify batch ownership (public across all batches)\n- **Cross-Batch Competition**: Students from different batches compete in same ranking\n- **Use Case**: Platform-wide competition, identifying absolute top performers\n\n# Database Tables & Columns Used\n\n## Primary Tables:\n1. **testseries** (Test Series Information)\n - Columns: id, name\n - Purpose: Validates test exists and retrieves test name\n - Query: WHERE id = {testId}\n\n2. **testresult** (Test Submission Records - Global)\n - Columns: id, user_id, testseries_id, total_marks, obtained_marks, result_submited, created_at\n - Purpose: Gets ALL submitted test results across all batches\n - Query: WHERE testseries_id = {testId} AND result_submited = 1\n - Key Difference: NO batch filtering (no JOIN with school_enrollments)\n - Used for: Score calculation, attempted_at timestamp\n - Scope: Platform-wide\n\n3. **stu_testseries_analysis** (Question-level Time Tracking)\n - Columns: testresult_id, total_time\n - Purpose: Calculates total time spent by each student\n - Query: WHERE testresult_id IN (test_result_ids) GROUP BY testresult_id\n - Aggregation: SUM(total_time) per testresult_id\n - Used for: Tie-breaking in ranking algorithm\n\n4. **users** (Student Information)\n - Columns: id, name, email\n - Purpose: Retrieves student names for leaderboard display\n - Query: WHERE id IN (unique_user_ids_from_results)\n - Returns: Student names and emails for display\n\n## Data Relationships:\n```\ntestseries (test)\n └─> testresult (ALL test submissions globally - ONLY where result_submited = 1)\n ├─> stu_testseries_analysis (time data: SUM(total_time) per student)\n └─> users (student details)\n\nNOTE: No school_enrollments or create_groups tables involved (global scope)\n```\n\n# Validation Rules\n- **testId** (path param): Required, integer, must exist in testseries table\n- **limit** (query param): Optional, integer, must be one of [10, 20, 50, 100], default = 50\n - Invalid values automatically reset to 50\n- **Authentication**: User must be logged in (no specific ownership requirements)\n\n# Ranking Algorithm\n\n## Score Calculation:\nFor each student:\n```\npercentage = (obtained_marks / total_marks) * 100\n```\n\n## Sorting Logic (Two-Phase):\n1. **Primary Sort**: By score (percentage) descending\n - Higher score = better rank\n - Student with 95% ranks higher than student with 85%\n - Applies globally across ALL batches\n\n2. **Tie-Breaker** (when scores are equal): By time_taken_seconds ascending\n - Lower time = better rank\n - If two students both score 85%, the one who completed faster gets better rank\n - Example: Student A (85%, 1800s) ranks higher than Student B (85%, 2100s)\n\n## Rank Assignment:\n- Sequential global ranking: 1, 2, 3, 4, ...\n- Applied after sorting all students globally\n- Limited to top N entries based on limit parameter\n- No rank gaps (no shared ranks, each student gets unique rank based on order)\n- Rank 1 = highest scorer across entire platform\n\n# Response Data Structure\n\n## Leaderboard Entries:\nEach entry contains:\n- **rank**: Sequential global position (1-based)\n- **student_id**: User ID from users table\n- **student_name**: User name from users table (or 'Unknown' if not found)\n- **score**: Percentage score rounded to 2 decimals\n- **obtained_marks**: Raw marks obtained from testresult table\n- **total_marks**: Total possible marks from testresult table\n- **time_taken_seconds**: Total time in seconds (SUM from stu_testseries_analysis)\n- **time_taken**: Formatted time as HH:MM:SS\n- **attempted_at**: Timestamp when test was created (formatted as Y-m-d H:i:s)\n\n## Additional Response Fields:\n- **my_rank**: Current user's global rank in the leaderboard (null if user hasn't taken test)\n- **total_participants**: COUNT of ALL submitted results for this test globally\n- **test_series_name**: Name from testseries table\n\n## Notable Absence:\n- **NO batch_name**: Global leaderboard doesn't include batch information\n- **NO batch filtering**: All students compete in same ranking pool\n\n# Caching Strategy\n- **Cache Key Format**: leaderboard_global_test_{testId}_limit_{limit}\n- **Duration**: 1800 seconds (30 minutes)\n- **Cache per Limit**: Each limit value (10, 20, 50, 100) has separate cache\n- **Clear Method**: LeaderboardService->clearCache(testId, null)\n- **Clear All Limits**: Clears all 4 common limit caches (10, 20, 50, 100)\n\n# Performance Optimizations\n1. **Eager Loading**: User data loaded in bulk (not N+1 queries)\n2. **Indexed Lookups**: Results keyed by user_id and testresult_id for O(1) access\n3. **Efficient Aggregation**: Single GROUP BY query for time data\n4. **Limited Results**: Only fetches submitted results (result_submited = 1)\n5. **Array Slicing**: Applies limit after sorting for minimal memory usage\n6. **No JOIN Overhead**: Simpler query without school_enrollments JOIN\n\n# Empty Data Handling\nReturns empty leaderboard array [] if:\n- No submitted test results globally (result_submited = 1)\n- Test not found\n\n# Business Rules\n- **Global Scope**: NO batch filtering or restrictions\n- **Public Access**: Any authenticated user can view global leaderboard\n- **Submission Filter**: Only includes students who submitted their test (result_submited = 1)\n- **Time Tie-Breaker**: Encourages both accuracy AND speed\n- **Cross-Batch Competition**: Students from different batches compete together\n- **Valid Limits Only**: Invalid limit values automatically corrected to 50\n- **Zero Time Handling**: Students with no time data get 0 seconds (appears as 00:00:00)\n\n# Use Cases\n1. **Platform-wide Competition**: See top performers across all batches\n2. **Tutor Comparison**: Compare your batch's students against global rankings\n3. **Motivation**: Show students their global standing\n4. **Marketing**: Showcase top performers from the platform\n5. **Performance Benchmarking**: Identify if a batch is performing above/below global average\n\n# Comparison: Global vs Batch Leaderboard\n\n| Feature | Global Leaderboard | Batch Leaderboard |\n|---------|-------------------|-------------------|\n| Scope | All students platform-wide | Students in specific batch only |\n| Authorization | Any authenticated user | Must own the batch |\n| Tables Used | testresult only | testresult + school_enrollments |\n| Query Filter | testseries_id only | testseries_id + batch students |\n| Batch Name | Not included | Included |\n| Use Case | Platform competition | Batch-specific tracking |\n| Cache Key | leaderboard_global_test_X | leaderboard_batch_X_test_Y |\n\n# Notes\n- result_submited values: 1 = submitted, 0 = not submitted (only 1 included)\n- Time stored in seconds in database, formatted to HH:MM:SS for display\n- Percentage rounded to 2 decimal places\n- Ranks are sequential with no gaps (1, 2, 3, ... no 1, 1, 3)\n- Students who haven't submitted (result_submited = 0) are excluded from leaderboard\n- NO batch ownership validation required\n- Potentially larger dataset than batch leaderboard (more students)\n", "operationId": "getGlobalLeaderboard", "parameters": [ { "name": "testId", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Number of top students to retrieve globally. Must be one of: 10, 20, 50, 100. Invalid values default to 50. Determines how many top-ranked students appear in the response from across ALL batches.", "required": false, "schema": { "type": "integer", "default": 50, "enum": [ 10, 20, 50, 100 ], "example": 50 } } ], "responses": { "200": { "description": "Global leaderboard retrieved successfully with platform-wide ranked student list", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Indicates API call success", "type": "boolean", "example": true }, "message": { "description": "Success message", "type": "string", "example": "Leaderboard retrieved successfully" }, "data": { "description": "Global leaderboard data object", "properties": { "test_series_name": { "description": "Name from testseries.name", "type": "string", "example": "JEE Main Mock Test 2025" }, "total_participants": { "description": "COUNT of ALL students who submitted test (result_submited=1) across entire platform", "type": "integer", "example": 547 }, "my_rank": { "description": "Current authenticated user's global rank in leaderboard. Null if user hasn't taken the test.", "type": "integer", "example": 42, "nullable": true }, "leaderboard": { "description": "Ranked list of top students globally (limited by limit parameter). Sorted by score DESC, then time ASC. No batch filtering applied.", "type": "array", "items": { "properties": { "rank": { "description": "Sequential global rank position (1-based). Rank 1 = highest scorer across entire platform. No gaps or ties.", "type": "integer", "example": 1 }, "student_id": { "description": "User ID from users.id", "type": "integer", "example": 127 }, "student_name": { "description": "Name from users.name (or 'Unknown' if user not found)", "type": "string", "example": "Priya Sharma" }, "score": { "description": "Percentage score: (obtained_marks / total_marks) * 100, rounded to 2 decimals", "type": "number", "format": "float", "example": 99.5 }, "obtained_marks": { "description": "Raw marks obtained from testresult.obtained_marks", "type": "number", "format": "float", "example": 199 }, "total_marks": { "description": "Total possible marks from testresult.total_marks", "type": "number", "format": "float", "example": 200 }, "time_taken_seconds": { "description": "Total time in seconds: SUM(stu_testseries_analysis.total_time) for this student. Used for tie-breaking.", "type": "integer", "example": 3245 }, "time_taken": { "description": "Formatted time as HH:MM:SS", "type": "string", "example": "00:54:05" }, "attempted_at": { "description": "When test was created (testresult.created_at)", "type": "string", "format": "date-time", "example": "2025-12-27 09:15:00" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated - User not logged in", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "404": { "description": "Test not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Test not found" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve leaderboard" }, "error": { "type": "string", "example": "Database connection error" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/leaderboard/batch/{batchId}/test/{testId}": { "get": { "tags": [ "Tutor V2" ], "summary": "Get batch leaderboard", "description": "\n# API Purpose\nThis API retrieves a ranked leaderboard of students within a specific batch for a given test, sorted by score (highest first) with time-based tie-breaking. Designed to help tutors identify top performers and track competitive performance within their batches.\n\n# Business Logic Flow\n1. **Authentication & Authorization**: Verifies tutor is logged in via Sanctum and owns the batch\n2. **Validation**: Validates limit parameter (must be 10, 20, 50, or 100; defaults to 50)\n3. **Data Collection**: Fetches all submitted test results for students in the batch\n4. **Time Aggregation**: Calculates total time spent per student from question-level analysis\n5. **User Data Enrichment**: Retrieves student names and details\n6. **Ranking Algorithm**:\n - Primary sort: Score (percentage) in descending order (highest score = rank 1)\n - Tie-breaker: Time taken in ascending order (faster completion wins)\n7. **Rank Assignment**: Assigns sequential ranks (1, 2, 3, ...) to sorted entries\n8. **Current User Rank**: Optionally calculates logged-in tutor's rank if they took the test\n9. **Caching**: Results cached for 30 minutes to optimize performance\n10. **Limit Application**: Returns only top N students based on limit parameter\n\n# Database Tables & Columns Used\n\n## Primary Tables:\n1. **create_groups** (Batch/Group Information)\n - Columns: id, user_id, name\n - Purpose: Validates batch ownership and retrieves batch name\n - Query: WHERE id = {batchId} AND user_id = {authenticated_user_id}\n - Authorization: Ensures tutor owns the batch\n\n2. **testseries** (Test Series Information)\n - Columns: id, name\n - Purpose: Validates test exists and retrieves test name\n - Query: WHERE id = {testId}\n\n3. **school_enrollments** (Student-Batch Enrollment)\n - Columns: id, user_id, group_id, payment_status\n - Purpose: Gets list of students enrolled in the specific batch\n - Query: WHERE group_id = {batchId}\n - Returns: Array of user_ids who belong to this batch\n - Note: payment_status filter is commented out in current implementation\n\n4. **testresult** (Test Submission Records)\n - Columns: id, user_id, testseries_id, total_marks, obtained_marks, result_submited, created_at\n - Purpose: Gets all submitted test results for students in the batch\n - Query: WHERE testseries_id = {testId} AND user_id IN (student_ids_from_enrollments) AND result_submited = 1\n - Key Filter: Only includes submitted results (result_submited = 1)\n - Used for: Score calculation, attempted_at timestamp\n\n5. **stu_testseries_analysis** (Question-level Time Tracking)\n - Columns: testresult_id, total_time\n - Purpose: Calculates total time spent by each student\n - Query: WHERE testresult_id IN (test_result_ids) GROUP BY testresult_id\n - Aggregation: SUM(total_time) per testresult_id\n - Used for: Tie-breaking in ranking algorithm\n\n6. **users** (Student Information)\n - Columns: id, name, email\n - Purpose: Retrieves student names for leaderboard display\n - Query: WHERE id IN (unique_user_ids_from_results)\n - Returns: Student names and emails for display\n\n## Data Relationships:\n```\ncreate_groups (batch)\n └─> school_enrollments (students in batch)\n └─> testresult (test submissions - ONLY where result_submited = 1)\n ├─> stu_testseries_analysis (time data: SUM(total_time) per student)\n └─> users (student details)\n```\n\n# Validation Rules\n- **batchId** (path param): Required, integer, must exist in create_groups table\n- **testId** (path param): Required, integer, must exist in testseries table\n- **limit** (query param): Optional, integer, must be one of [10, 20, 50, 100], default = 50\n - Invalid values automatically reset to 50\n- **Authorization**: Authenticated tutor must own the batch (create_groups.user_id = auth.user.id)\n\n# Ranking Algorithm\n\n## Score Calculation:\nFor each student:\n```\npercentage = (obtained_marks / total_marks) * 100\n```\n\n## Sorting Logic (Two-Phase):\n1. **Primary Sort**: By score (percentage) descending\n - Higher score = better rank\n - Student with 95% ranks higher than student with 85%\n\n2. **Tie-Breaker** (when scores are equal): By time_taken_seconds ascending\n - Lower time = better rank\n - If two students both score 85%, the one who completed faster gets better rank\n - Example: Student A (85%, 1800s) ranks higher than Student B (85%, 2100s)\n\n## Rank Assignment:\n- Sequential ranking: 1, 2, 3, 4, ...\n- Applied after sorting\n- Limited to top N entries based on limit parameter\n- No rank gaps (no shared ranks, each student gets unique rank based on order)\n\n# Response Data Structure\n\n## Leaderboard Entries:\nEach entry contains:\n- **rank**: Sequential position (1-based)\n- **student_id**: User ID from users table\n- **student_name**: User name from users table (or 'Unknown' if not found)\n- **score**: Percentage score rounded to 2 decimals\n- **obtained_marks**: Raw marks obtained from testresult table\n- **total_marks**: Total possible marks from testresult table\n- **time_taken_seconds**: Total time in seconds (SUM from stu_testseries_analysis)\n- **time_taken**: Formatted time as HH:MM:SS\n- **attempted_at**: Timestamp when test was created (formatted as Y-m-d H:i:s)\n\n## Additional Response Fields:\n- **my_rank**: Current user's rank in the leaderboard (null if user hasn't taken test)\n- **total_participants**: COUNT of all submitted results for this test in this batch\n- **batch_name**: Name from create_groups table\n- **test_series_name**: Name from testseries table\n\n# Caching Strategy\n- **Cache Key Format**: leaderboard_batch_{batchId}_test_{testId}_limit_{limit}\n- **Duration**: 1800 seconds (30 minutes)\n- **Cache per Limit**: Each limit value (10, 20, 50, 100) has separate cache\n- **Clear Method**: LeaderboardService->clearCache(testId, batchId)\n- **Clear All Limits**: Clears all 4 common limit caches (10, 20, 50, 100)\n\n# Performance Optimizations\n1. **Eager Loading**: User data loaded in bulk (not N+1 queries)\n2. **Indexed Lookups**: Results keyed by user_id and testresult_id for O(1) access\n3. **Efficient Aggregation**: Single GROUP BY query for time data\n4. **Limited Results**: Only fetches submitted results (result_submited = 1)\n5. **Array Slicing**: Applies limit after sorting for minimal memory usage\n\n# Empty Data Handling\nReturns empty leaderboard array [] if:\n- No students enrolled in batch\n- No submitted test results (result_submited = 1)\n- Batch or test not found\n\n# Business Rules\n- **Submission Filter**: Only includes students who submitted their test (result_submited = 1)\n- **Time Tie-Breaker**: Encourages both accuracy AND speed\n- **Batch Isolation**: Leaderboard scoped to specific batch (no cross-batch ranking)\n- **Valid Limits Only**: Invalid limit values automatically corrected to 50\n- **Zero Time Handling**: Students with no time data get 0 seconds (appears as 00:00:00)\n\n# Notes\n- result_submited values: 1 = submitted, 0 = not submitted (only 1 included)\n- Time stored in seconds in database, formatted to HH:MM:SS for display\n- Percentage rounded to 2 decimal places\n- Ranks are sequential with no gaps (1, 2, 3, ... no 1, 1, 3)\n- Students who haven't submitted (result_submited = 0) are excluded from leaderboard\n- payment_status filter on school_enrollments is currently commented out\n", "operationId": "getBatchLeaderboard", "parameters": [ { "name": "batchId", "in": "path", "description": "Batch ID", "required": true, "schema": { "type": "integer" } }, { "name": "testId", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Number of top students to retrieve. Must be one of: 10, 20, 50, 100. Invalid values default to 50. Determines how many top-ranked students appear in the response.", "required": false, "schema": { "type": "integer", "default": 50, "enum": [ 10, 20, 50, 100 ], "example": 50 } } ], "responses": { "200": { "description": "Batch leaderboard retrieved successfully with ranked student list", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Indicates API call success", "type": "boolean", "example": true }, "message": { "description": "Success message", "type": "string", "example": "Leaderboard retrieved successfully" }, "data": { "description": "Leaderboard data object", "properties": { "batch_name": { "description": "Name from create_groups.name", "type": "string", "example": "NEET 2025 Batch A" }, "test_series_name": { "description": "Name from testseries.name", "type": "string", "example": "Mathematics Final Test" }, "total_participants": { "description": "COUNT of all students who submitted test (result_submited=1) in this batch", "type": "integer", "example": 28 }, "my_rank": { "description": "Current authenticated user's rank in leaderboard. Null if user hasn't taken the test.", "type": "integer", "example": 5, "nullable": true }, "leaderboard": { "description": "Ranked list of top students (limited by limit parameter). Sorted by score DESC, then time ASC.", "type": "array", "items": { "properties": { "rank": { "description": "Sequential rank position (1-based). No gaps or ties.", "type": "integer", "example": 1 }, "student_id": { "description": "User ID from users.id", "type": "integer", "example": 50 }, "student_name": { "description": "Name from users.name (or 'Unknown' if user not found)", "type": "string", "example": "John Doe" }, "score": { "description": "Percentage score: (obtained_marks / total_marks) * 100, rounded to 2 decimals", "type": "number", "format": "float", "example": 98.5 }, "obtained_marks": { "description": "Raw marks obtained from testresult.obtained_marks", "type": "number", "format": "float", "example": 197 }, "total_marks": { "description": "Total possible marks from testresult.total_marks", "type": "number", "format": "float", "example": 200 }, "time_taken_seconds": { "description": "Total time in seconds: SUM(stu_testseries_analysis.total_time) for this student. Used for tie-breaking.", "type": "integer", "example": 1845 }, "time_taken": { "description": "Formatted time as HH:MM:SS", "type": "string", "example": "00:30:45" }, "attempted_at": { "description": "When test was created (testresult.created_at)", "type": "string", "format": "date-time", "example": "2025-12-27 14:30:00" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated - User not logged in", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "404": { "description": "Batch not found or tutor does not have permission / Test not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch not found or you do not have permission to access it" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve leaderboard" }, "error": { "type": "string", "example": "Database connection error" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/results/export-excel": { "post": { "tags": [ "Tutor V2" ], "summary": "Export results to Excel", "description": "Exports test results for a batch to an Excel file with detailed analytics.", "operationId": "exportBatchResultsToExcel", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "test_id", "batch_id" ], "properties": { "test_id": { "type": "integer", "example": 1 }, "batch_id": { "type": "integer", "example": 5 }, "include_analytics": { "description": "Include analytics sheet", "type": "boolean", "example": true }, "include_question_wise": { "description": "Include question-wise analysis", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Excel export initiated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Excel export initiated successfully" }, "data": { "properties": { "download_url": { "type": "string", "example": "https://pathshalaa.com/downloads/results_batch5_test1.xlsx" }, "expires_at": { "description": "URL expiration time", "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Test or batch not found" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/trends/student/{studentId}": { "get": { "tags": [ "Tutor V2" ], "summary": "Get student performance trends", "description": "Retrieves performance trends and analytics for a student over time with graphical data.", "operationId": "getStudentTrends", "parameters": [ { "name": "studentId", "in": "path", "description": "Student ID", "required": true, "schema": { "type": "integer" } }, { "name": "period", "in": "query", "description": "Time period for trends", "required": false, "schema": { "type": "string", "default": "3months", "enum": [ "1month", "3months", "6months", "1year" ] } }, { "name": "batch_id", "in": "query", "description": "Filter by batch", "required": false, "schema": { "type": "integer" } }, { "name": "subject_id", "in": "query", "description": "Filter by subject", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Student trends retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Student trends fetched successfully" }, "data": { "properties": { "student_id": { "type": "integer", "example": 50 }, "student_name": { "type": "string", "example": "John Doe" }, "period": { "type": "string", "example": "3months" }, "total_tests": { "type": "integer", "example": 12 }, "average_score": { "type": "number", "format": "float", "example": 78.5 }, "improvement_rate": { "description": "Percentage improvement", "type": "number", "format": "float", "example": 5.2 }, "consistency_score": { "description": "Performance consistency (0-100)", "type": "number", "format": "float", "example": 85 }, "performance_trend": { "description": "Score progression over time", "type": "array", "items": { "properties": { "test_date": { "type": "string", "format": "date" }, "test_name": { "type": "string" }, "score": { "type": "number" }, "rank": { "type": "integer" } }, "type": "object" } }, "subject_wise_performance": { "type": "array", "items": { "properties": { "subject_name": { "type": "string", "example": "Mathematics" }, "average_score": { "type": "number", "example": 82 }, "tests_count": { "type": "integer", "example": 5 } }, "type": "object" } }, "strengths": { "description": "Topics where student performs well", "type": "array", "items": { "type": "string", "example": "Algebra" } }, "weaknesses": { "description": "Topics needing improvement", "type": "array", "items": { "type": "string", "example": "Geometry" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Student not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/school-assign": { "post": { "tags": [ "Tutor V2 - School Management" ], "summary": "Assign tutor to a school context", "description": "Assigns the authenticated tutor to a specific school context, enabling school-specific operations.", "operationId": "schoolAssign", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "school_id" ], "properties": { "school_id": { "description": "ID of the school to assign", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "School assigned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "School assigned successfully" }, "data": { "properties": { "school_id": { "type": "integer", "example": 5 }, "school_name": { "type": "string", "example": "ABC School" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Not a tutor" }, "404": { "description": "School not found" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/add-student": { "post": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Add a student to the system", "description": "Creates a new student record in the system by associating an existing user with student details (qualification, school, state, city). Only tutors can add students.", "operationId": "addStudent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id", "qualification", "school", "state", "city" ], "properties": { "user_id": { "description": "ID of the existing user to be added as a student", "type": "integer", "example": 123 }, "qualification": { "description": "Student's qualification or current class", "type": "string", "example": "Class 10" }, "school": { "description": "Name of the school", "type": "string", "example": "ABC High School" }, "state": { "description": "State where student resides", "type": "string", "example": "Maharashtra" }, "city": { "description": "City where student resides", "type": "string", "example": "Mumbai" }, "show_on_home_page": { "description": "Whether to show student on home page (0 or 1)", "type": "integer", "example": 0 } }, "type": "object" } } } }, "responses": { "201": { "description": "Student added successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Student added successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 50 }, "user_id": { "type": "integer", "example": 123 }, "qualification": { "type": "string", "example": "Class 10" }, "school": { "type": "string", "example": "ABC High School" }, "state": { "type": "string", "example": "Maharashtra" }, "city": { "type": "string", "example": "Mumbai" }, "show_on_home_page": { "type": "integer", "example": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthenticated" }, "error_code": { "type": "string", "example": "UNAUTHENTICATED" } }, "type": "object" } } } }, "403": { "description": "Forbidden - Only tutors can add students", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Forbidden: only tutors can add students" }, "error_code": { "type": "string", "example": "FORBIDDEN" } }, "type": "object" } } } }, "409": { "description": "Student already exists", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Student already exists" }, "error_code": { "type": "string", "example": "ALREADY_EXISTS" }, "data": { "description": "Existing student data", "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The user id field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to add student" }, "error_code": { "type": "string", "example": "INTERNAL_SERVER_ERROR" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/remove-student/{id}": { "delete": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Remove a student from tutor's class", "description": "Removes or unenrolls a student from the tutor's class or batch", "operationId": "removeStudent", "parameters": [ { "name": "id", "in": "path", "description": "Student ID or Enrollment ID", "required": true, "schema": { "type": "integer", "example": 500 } }, { "name": "group_id", "in": "query", "description": "Group/Batch ID (optional, if removing from specific group)", "required": false, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Student removed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Student removed successfully" }, "data": { "properties": { "student_id": { "type": "integer", "example": 500 }, "student_name": { "type": "string", "example": "John Doe" }, "removed_from_group": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Student not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/import-students": { "post": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Bulk import students", "description": "Import multiple students at once using CSV or Excel file", "operationId": "importStudents", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "description": "CSV or Excel file with student data", "type": "string", "format": "binary" }, "group_id": { "description": "Group/Batch ID to enroll all students", "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Students imported successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Students imported successfully" }, "data": { "properties": { "total_rows": { "type": "integer", "example": 50 }, "successful_imports": { "type": "integer", "example": 48 }, "failed_imports": { "type": "integer", "example": 2 }, "errors": { "type": "array", "items": { "properties": { "row": { "type": "integer", "example": 5 }, "error": { "type": "string", "example": "Invalid email format" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error or invalid file format" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/track-student": { "post": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Track student progress and participation", "description": "Records and tracks a student's progress, attendance, or participation metrics", "operationId": "trackStudent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "student_id" ], "properties": { "student_id": { "description": "Student ID", "type": "integer", "example": 500 }, "test_id": { "description": "Test ID (if tracking test performance)", "type": "integer", "example": 10 }, "attendance": { "description": "Mark attendance", "type": "boolean", "example": true }, "notes": { "description": "Tutor notes", "type": "string", "example": "Good performance in recent tests" } }, "type": "object" } } } }, "responses": { "200": { "description": "Student tracking recorded successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Student tracking recorded successfully" }, "data": { "properties": { "student_id": { "type": "integer", "example": 500 }, "tracked_at": { "type": "string", "example": "2025-01-15 10:00:00" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "404": { "description": "Student not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/share-enrollment": { "post": { "tags": [ "Tutor V2 - Group Management" ], "summary": "Share enrollment link or QR code", "description": "Generates and shares enrollment link or QR code for students to join a group/batch", "operationId": "shareEnrollment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "group_id" ], "properties": { "group_id": { "description": "Group/Batch ID", "type": "integer", "example": 1 }, "share_method": { "description": "Share method: link, qr_code, or both", "type": "string", "example": "qr_code" }, "expiry_days": { "description": "Link expiry in days (optional)", "type": "integer", "example": 30 } }, "type": "object" } } } }, "responses": { "200": { "description": "Enrollment details generated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Enrollment link generated successfully" }, "data": { "properties": { "group_id": { "type": "integer", "example": 1 }, "group_name": { "type": "string", "example": "Physics Batch A" }, "enrollment_code": { "type": "string", "example": "ABC123XYZ" }, "enrollment_link": { "type": "string", "example": "https://app.pathshalaa.in/enroll/ABC123XYZ" }, "qr_code_url": { "type": "string", "example": "https://api.pathshalaa.in/qr/ABC123XYZ.png" }, "expires_at": { "type": "string", "example": "2025-02-15 10:00:00" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Group not found" }, "422": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/groups/{id}/regenerate-code": { "post": { "tags": [ "Tutor V2" ], "summary": "Regenerate enrollment code", "operationId": "regenerateGroupCode", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Code regenerated successfully" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/syllabus": { "get": { "tags": [ "Tutor V2" ], "summary": "List all syllabi", "description": "Retrieves a paginated list of all syllabus plans created by the tutor. Teachers can only see their own syllabi, admins can see all syllabi.", "operationId": "indexSyllabus", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (default: 15)", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "batch_id", "in": "query", "description": "Filter by batch/group ID", "required": false, "schema": { "type": "integer" } }, { "name": "sort_by", "in": "query", "description": "Field to sort by (default: created_at)", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "sort_order", "in": "query", "description": "Sort order (asc/desc, default: desc)", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Syllabi retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Syllabi retrieved successfully" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "batch_id": { "type": "integer", "example": 5 }, "batch_name": { "type": "string", "example": "Class 10 - Section A" }, "title": { "type": "string", "example": "Mathematics Syllabus Q1 2025" }, "start_date": { "type": "string", "format": "date", "example": "2025-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2025-03-31" }, "total_weeks": { "type": "integer", "example": 12 }, "completion_percentage": { "type": "number", "format": "float", "example": 41.67 }, "total_topics": { "type": "integer", "example": 48 }, "completed_topics": { "type": "integer", "example": 20 }, "is_active": { "type": "boolean", "example": true }, "has_started": { "type": "boolean", "example": true }, "has_ended": { "type": "boolean", "example": false }, "current_week": { "type": "integer", "example": 5, "nullable": true }, "created_by": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "John Doe" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2025-01-01 10:30:00" } }, "type": "object" } }, "pagination": { "properties": { "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 45 }, "last_page": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "500": { "description": "Server error" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Tutor V2" ], "summary": "Create a new syllabus plan", "description": "Creates a new syllabus plan with topics automatically distributed across weeks based on the date range. Topics are evenly distributed unless custom dates are provided.", "operationId": "storeSyllabus", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "batch_id", "title", "start_date", "end_date", "topic_ids" ], "properties": { "batch_id": { "description": "Batch/Group ID (must be active)", "type": "integer", "example": 5 }, "title": { "type": "string", "maxLength": 255, "minLength": 3, "example": "Mathematics Syllabus Q1 2025" }, "start_date": { "description": "Start date (must be today or future date)", "type": "string", "format": "date", "example": "2025-01-01" }, "end_date": { "description": "End date (must be after start_date, duration 1 week to 2 years)", "type": "string", "format": "date", "example": "2025-03-31" }, "topic_ids": { "description": "Array of topic IDs (must be active)", "type": "array", "items": { "type": "integer", "example": 150 }, "maxItems": 100, "minItems": 1 }, "custom_topic_dates": { "description": "Optional custom scheduled dates for specific topics", "type": "array", "items": { "properties": { "topic_id": { "description": "Must exist in topic_ids array", "type": "integer", "example": 150 }, "scheduled_date": { "description": "Must be between start_date and end_date", "type": "string", "format": "date", "example": "2025-01-15" } }, "type": "object" }, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Syllabus created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Syllabus created successfully" }, "data": { "properties": { "syllabus": { "properties": { "id": { "type": "integer", "example": 1 }, "batch_id": { "type": "integer", "example": 5 }, "title": { "type": "string", "example": "Mathematics Syllabus Q1 2025" }, "start_date": { "type": "string", "format": "date", "example": "2025-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2025-03-31" }, "total_weeks": { "type": "integer", "example": 12 } }, "type": "object" }, "distribution": { "description": "Topics distributed by week", "type": "array", "items": { "properties": { "week_number": { "type": "integer", "example": 1 }, "topics": { "type": "array", "items": { "properties": { "topic_id": { "type": "integer", "example": 150 }, "topic_name": { "type": "string", "example": "Algebra" }, "scheduled_date": { "type": "string", "format": "date", "example": "2025-01-05" } }, "type": "object" } } }, "type": "object" } }, "summary": { "properties": { "total_topics": { "type": "integer", "example": 48 }, "total_weeks": { "type": "integer", "example": 12 }, "avg_topics_per_week": { "type": "number", "format": "float", "example": 4 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Unauthorized - Only teachers and admins can create syllabi" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/syllabus/{id}": { "get": { "tags": [ "Tutor V2" ], "summary": "Get syllabus details", "description": "Retrieves detailed information about a specific syllabus including all topics with their completion status, scheduled dates, and metadata.", "operationId": "showSyllabus", "parameters": [ { "name": "id", "in": "path", "description": "Syllabus ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Syllabus retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Syllabus retrieved successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "batch_id": { "type": "integer", "example": 5 }, "batch_name": { "type": "string", "example": "Class 10 - Section A" }, "title": { "type": "string", "example": "Mathematics Syllabus Q1 2025" }, "start_date": { "type": "string", "format": "date", "example": "2025-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2025-03-31" }, "total_weeks": { "type": "integer", "example": 12 }, "completion_percentage": { "type": "number", "format": "float", "example": 41.67 }, "total_topics": { "type": "integer", "example": 48 }, "completed_topics": { "type": "integer", "example": 20 }, "pending_topics": { "type": "integer", "example": 28 }, "is_active": { "description": "Whether syllabus is currently active", "type": "boolean", "example": true }, "has_started": { "description": "Whether syllabus has started", "type": "boolean", "example": true }, "has_ended": { "description": "Whether syllabus has ended", "type": "boolean", "example": false }, "current_week": { "description": "Current week number (null if not started)", "type": "integer", "example": 5, "nullable": true }, "created_by": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "John Doe" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2025-01-01 10:30:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-01-05 14:20:00" }, "topics": { "description": "All topics in this syllabus", "type": "array", "items": { "properties": { "syllabus_topic_id": { "description": "Syllabus topic junction table ID", "type": "integer", "example": 1 }, "topic_id": { "type": "integer", "example": 150 }, "topic_name": { "type": "string", "example": "Algebra" }, "topic_title": { "type": "string", "example": "Introduction to Algebra" }, "week_number": { "type": "integer", "example": 1 }, "scheduled_date": { "type": "string", "format": "date", "example": "2025-01-05" }, "is_completed": { "type": "boolean", "example": false }, "completed_at": { "type": "string", "format": "date-time", "example": "2025-01-05 15:30:00", "nullable": true }, "test_generated": { "description": "Whether test has been generated for this topic", "type": "boolean", "example": false }, "is_overdue": { "description": "Whether topic is past scheduled date but not completed", "type": "boolean", "example": false }, "is_today": { "description": "Whether topic is scheduled for today", "type": "boolean", "example": false }, "is_upcoming": { "description": "Whether topic is scheduled in future", "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Unauthorized - Teachers can only view their own syllabi" }, "404": { "description": "Syllabus not found" }, "500": { "description": "Server error" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Tutor V2" ], "summary": "Update syllabus", "description": "Updates syllabus details. Changing dates or topics will trigger automatic redistribution of topics across weeks. All fields are optional.", "operationId": "updateSyllabus", "parameters": [ { "name": "id", "in": "path", "description": "Syllabus ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "batch_id": { "description": "Batch/Group ID (must be active)", "type": "integer", "example": 5 }, "title": { "type": "string", "maxLength": 255, "minLength": 3, "example": "Updated Mathematics Syllabus" }, "start_date": { "description": "Start date (triggers redistribution)", "type": "string", "format": "date", "example": "2025-01-01" }, "end_date": { "description": "End date (must be after start_date, triggers redistribution)", "type": "string", "format": "date", "example": "2025-03-31" }, "topic_ids": { "description": "Updated array of topic IDs (triggers redistribution)", "type": "array", "items": { "type": "integer", "example": 150 }, "maxItems": 100, "minItems": 1 }, "custom_topic_dates": { "description": "Optional custom scheduled dates for specific topics", "type": "array", "items": { "properties": { "topic_id": { "description": "Must exist in topic_ids array if provided", "type": "integer", "example": 150 }, "scheduled_date": { "type": "string", "format": "date", "example": "2025-01-15" } }, "type": "object" }, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Syllabus updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Syllabus updated successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "batch_id": { "type": "integer", "example": 5 }, "title": { "type": "string", "example": "Updated Mathematics Syllabus" }, "start_date": { "type": "string", "format": "date", "example": "2025-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2025-03-31" }, "total_weeks": { "type": "integer", "example": 12 }, "total_topics": { "type": "integer", "example": 48 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Unauthorized - Teachers can only update their own syllabi" }, "404": { "description": "Syllabus not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Tutor V2" ], "summary": "Delete syllabus", "description": "Soft deletes a syllabus plan. Associated topics and completion records are also deleted.", "operationId": "destroySyllabus", "parameters": [ { "name": "id", "in": "path", "description": "Syllabus ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Syllabus deleted successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Syllabus deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Unauthorized - Teachers can only delete their own syllabi" }, "404": { "description": "Syllabus not found" }, "500": { "description": "Server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/syllabus/{id}/weekly": { "get": { "tags": [ "Tutor V2" ], "summary": "Get weekly view", "description": "Retrieves topics planned for a specific week with completion status.", "operationId": "syllabusWeeklyView", "parameters": [ { "name": "id", "in": "path", "description": "Syllabus ID", "required": true, "schema": { "type": "integer" } }, { "name": "week", "in": "query", "description": "Week number", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Weekly view retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Weekly view fetched successfully" }, "data": { "properties": { "syllabus_id": { "type": "integer", "example": 1 }, "week_number": { "type": "integer", "example": 1 }, "week_start_date": { "type": "string", "format": "date", "example": "2025-01-01" }, "week_end_date": { "type": "string", "format": "date", "example": "2025-01-07" }, "topics": { "type": "array", "items": { "properties": { "topic_id": { "type": "integer", "example": 150 }, "topic_name": { "type": "string", "example": "Algebra" }, "is_completed": { "type": "boolean", "example": false }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "estimated_hours": { "type": "number", "format": "float", "example": 3.5 }, "order": { "type": "integer", "example": 1 } }, "type": "object" } }, "completion_percentage": { "type": "number", "format": "float", "example": 50 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Syllabus not found" }, "422": { "description": "Invalid week number" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/syllabus/{id}/weeks-overview": { "get": { "tags": [ "Tutor V2" ], "summary": "Get weeks overview", "description": "Retrieves an overview of all weeks with completion statistics.", "operationId": "syllabusWeeksOverview", "parameters": [ { "name": "id", "in": "path", "description": "Syllabus ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Weeks overview retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Weeks overview fetched successfully" }, "data": { "type": "array", "items": { "properties": { "week_number": { "type": "integer", "example": 1 }, "week_start_date": { "type": "string", "format": "date" }, "week_end_date": { "type": "string", "format": "date" }, "total_topics": { "type": "integer", "example": 4 }, "completed_topics": { "type": "integer", "example": 2 }, "completion_percentage": { "type": "number", "format": "float", "example": 50 }, "is_current_week": { "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Syllabus not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/syllabus/{id}/progress": { "get": { "tags": [ "Tutor V2" ], "summary": "Get overall progress", "description": "Retrieves overall progress statistics for the syllabus including completion trends.", "operationId": "syllabusProgress", "parameters": [ { "name": "id", "in": "path", "description": "Syllabus ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Progress retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Progress fetched successfully" }, "data": { "properties": { "syllabus_id": { "type": "integer", "example": 1 }, "total_topics": { "type": "integer", "example": 48 }, "completed_topics": { "type": "integer", "example": 20 }, "pending_topics": { "type": "integer", "example": 28 }, "completion_percentage": { "type": "number", "format": "float", "example": 41.67 }, "on_track": { "description": "Whether syllabus is on schedule", "type": "boolean", "example": true }, "current_week": { "type": "integer", "example": 5 }, "total_weeks": { "type": "integer", "example": 12 }, "expected_completion_percentage": { "type": "number", "format": "float", "example": 41.67 }, "weekly_completion_trend": { "description": "Completion trend over weeks", "type": "array", "items": { "properties": { "week": { "type": "integer" }, "topics_completed": { "type": "integer" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Syllabus not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/syllabus/{id}/generate-weekly-test": { "post": { "tags": [ "Tutor V2" ], "summary": "Generate weekly test from completed topics", "description": "Auto-generates a test series from topics completed in a specific week. Supports configuring negative marks, per-question marks, answer type filtering, question type filtering, and more. All new fields are optional with backward-compatible defaults.", "operationId": "generateWeeklyTest", "parameters": [ { "name": "id", "in": "path", "description": "Syllabus ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "week_number", "questions_per_topic", "duration_minutes", "total_marks", "start_date", "end_date" ], "properties": { "week_number": { "description": "Week number (must be within syllabus range)", "type": "integer", "minimum": 1, "example": 1 }, "questions_per_topic": { "description": "Number of questions per topic", "type": "integer", "maximum": 50, "minimum": 1, "example": 5 }, "duration_minutes": { "description": "Test duration in minutes", "type": "integer", "maximum": 300, "minimum": 5, "example": 60 }, "total_marks": { "description": "Total marks for the test", "type": "integer", "maximum": 1000, "minimum": 1, "example": 100 }, "start_date": { "description": "Start date and time for the test", "type": "string", "format": "date-time", "example": "2026-03-05 09:00:00" }, "end_date": { "description": "End date and time for the test (must be >= start_date)", "type": "string", "format": "date-time", "example": "2026-03-05 18:00:00" }, "negative_marks": { "description": "Negative marks per wrong answer (optional, default: 0)", "type": "number", "format": "float", "example": 0, "nullable": true }, "per_ques_mark": { "description": "Marks per question. If not provided, auto-calculated as total_marks / total_questions", "type": "number", "format": "float", "example": 2, "nullable": true }, "max_questions": { "description": "Maximum number of questions cap. If not provided, uses questions_per_topic × number_of_topics", "type": "integer", "example": 20, "nullable": true }, "attempt_per_stud": { "description": "Number of attempts allowed per student (optional, default: 1)", "type": "integer", "example": 1, "nullable": true }, "answer_type": { "description": "Filter questions by answer type: 'radio' (single-choice MCQ), 'checkbox' (multi-choice MCQ), 'textarea' (subjective/text), 'integer' (integer type answer). If not provided, all types are included.", "type": "string", "enum": [ "radio", "textarea", "checkbox", "text", "integer" ], "example": "radio", "nullable": true }, "question_type": { "description": "Filter questions by question type/difficulty: 'Easy', 'Medium', 'Difficult'. If not provided, all types are included.", "type": "string", "enum": [ "Easy", "Medium", "Difficult" ], "example": "Easy", "nullable": true }, "test_series_type": { "description": "Type of test series (optional, default: 'syllabus_weekly')", "type": "string", "enum": [ "objective", "subjective", "integer", "syllabus_weekly" ], "example": "syllabus_weekly", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Weekly test generated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Weekly test generated successfully" }, "data": { "properties": { "test_series_id": { "type": "integer", "example": 10 }, "test_name": { "type": "string", "example": "Mathematics - Week 1 Test" }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "start_date": { "type": "string", "format": "date-time", "example": "2026-03-05 09:00:00" }, "end_date": { "type": "string", "format": "date-time", "example": "2026-03-05 18:00:00" }, "duration_minutes": { "type": "integer", "example": 60 }, "total_questions": { "type": "integer", "example": 20 }, "total_marks": { "type": "integer", "example": 100 }, "enrolled_students_count": { "type": "integer", "example": 5 }, "topics_covered": { "type": "array", "items": { "properties": { "topic_id": { "type": "integer", "example": 150 }, "topic_name": { "type": "string", "example": "Algebra" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Unauthorized - Teachers can only generate tests for their own syllabi" }, "404": { "description": "Syllabus not found" }, "422": { "description": "Validation or business logic error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No completed topics found for week 1" }, "error_code": { "type": "string", "example": "NO_COMPLETED_TOPICS" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/syllabus/{id}/dashboard": { "get": { "tags": [ "Tutor V2" ], "summary": "Get syllabus dashboard", "description": "Retrieves comprehensive dashboard data including syllabus info, progress statistics, week-wise breakdown, upcoming topics, and performance insights.", "operationId": "syllabusDashboard", "parameters": [ { "name": "id", "in": "path", "description": "Syllabus ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Dashboard data retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Dashboard data retrieved successfully" }, "data": { "properties": { "syllabus_info": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Mathematics Syllabus Q1 2025" }, "batch_name": { "type": "string", "example": "Class 10 - Section A" }, "batch_id": { "type": "integer", "example": 5 }, "created_by": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "John Doe" } }, "type": "object" } }, "type": "object" }, "progress": { "properties": { "total_topics": { "type": "integer", "example": 48 }, "completed_topics": { "type": "integer", "example": 20 }, "pending_topics": { "type": "integer", "example": 28 }, "completion_percentage": { "type": "number", "format": "float", "example": 41.67 } }, "type": "object" }, "weeks": { "type": "array", "items": { "properties": { "week_number": { "type": "integer", "example": 1 }, "week_start_date": { "type": "string", "format": "date", "example": "2025-01-01" }, "week_end_date": { "type": "string", "format": "date", "example": "2025-01-07" }, "total_topics": { "type": "integer", "example": 4 }, "completed_topics": { "type": "integer", "example": 2 }, "is_current_week": { "type": "boolean", "example": false } }, "type": "object" } }, "upcoming_topics": { "description": "Next upcoming topics", "type": "array", "items": { "properties": { "topic_id": { "type": "integer", "example": 150 }, "topic_name": { "type": "string", "example": "Algebra" }, "scheduled_date": { "type": "string", "format": "date", "example": "2025-01-15" }, "week_number": { "type": "integer", "example": 2 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Unauthorized - Teachers can only view dashboard for their own syllabi" }, "404": { "description": "Syllabus not found" }, "500": { "description": "Server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/syllabus-topics/{id}/complete": { "post": { "tags": [ "Tutor V2" ], "summary": "Mark topic as complete", "description": "Marks a topic in the syllabus as completed.", "operationId": "markTopicComplete", "parameters": [ { "name": "id", "in": "path", "description": "Syllabus Topic ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Topic marked as complete", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Topic marked as complete" }, "data": { "properties": { "topic_id": { "type": "integer", "example": 150 }, "completed_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Topic not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/syllabus-topics/{id}/incomplete": { "post": { "tags": [ "Tutor V2" ], "summary": "Mark topic as incomplete", "description": "Marks a previously completed topic as incomplete.", "operationId": "markTopicIncomplete", "parameters": [ { "name": "id", "in": "path", "description": "Syllabus Topic ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Topic marked as incomplete", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Topic marked as incomplete" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Topic not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/syllabus-topics/bulk-complete": { "post": { "tags": [ "Tutor V2" ], "summary": "Bulk mark topics as complete", "description": "Marks multiple topics as completed at once.", "operationId": "bulkCompleteTopics", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "topic_ids" ], "properties": { "topic_ids": { "description": "Array of syllabus topic IDs", "type": "array", "items": { "type": "integer", "example": 1 } } }, "type": "object" } } } }, "responses": { "200": { "description": "Topics marked as complete", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Topics marked as complete" }, "data": { "properties": { "completed_count": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/syllabus/{id}/remove-topics": { "delete": { "tags": [ "Tutor V2" ], "summary": "Remove topics from syllabus", "description": "Removes one or more topics from a syllabus. Only pending (not completed) topics can be removed. Completion percentage is automatically recalculated after removal.", "operationId": "removeTopicsFromSyllabus", "parameters": [ { "name": "id", "in": "path", "description": "Syllabus ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "topic_ids" ], "properties": { "topic_ids": { "description": "Array of topic IDs to remove (1-50 topics, must be distinct)", "type": "array", "items": { "type": "integer", "example": 150 }, "maxItems": 50, "minItems": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Topics removed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "3 topic(s) removed successfully from syllabus" }, "data": { "properties": { "syllabus_id": { "type": "integer", "example": 1 }, "removed_count": { "type": "integer", "example": 3 }, "removed_topics": { "description": "Names of removed topics", "type": "array", "items": { "type": "string", "example": "Algebra" } }, "remaining_topics_count": { "type": "integer", "example": 45 }, "completion_percentage": { "type": "number", "format": "float", "example": 42.22 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Unauthorized - Teachers can only remove topics from their own syllabi", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized. Only teachers and admins can remove topics from syllabus." } }, "type": "object" } } } }, "404": { "description": "Syllabus not found or no matching topics found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No matching topics found in this syllabus" } }, "type": "object" } } } }, "422": { "description": "Validation error or completed topics cannot be removed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Cannot remove completed topics. Please mark them as incomplete first." }, "completed_topics": { "type": "string", "example": "Algebra, Geometry" }, "errors": { "description": "Validation errors if applicable", "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/create": { "post": { "tags": [ "Tutor V2 - Test Series Basic" ], "summary": "Create a new test series", "description": "Creates a new test series with basic information and optionally assigns it to a group", "operationId": "createTestSeriesV2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "total_time", "per_ques_mark", "max_questions" ], "properties": { "name": { "description": "Test series name", "type": "string", "example": "Physics Mock Test 2025" }, "description": { "description": "Test description (optional)", "type": "string", "example": "Comprehensive physics test covering mechanics and thermodynamics" }, "instructions": { "description": "Test instructions for students (optional)", "type": "string", "example": "Read all questions carefully. No negative marking for unattempted questions." }, "total_time": { "description": "Total test duration in minutes", "type": "integer", "example": 90 }, "per_ques_mark": { "description": "Marks per question", "type": "number", "format": "float", "example": 4 }, "max_questions": { "description": "Maximum number of questions in the test", "type": "integer", "example": 25 }, "negative_marks": { "description": "Negative marks per wrong answer (optional, default: 0)", "type": "number", "format": "float", "example": 1 }, "attempt_per_stud": { "description": "Number of attempts allowed per student (optional, default: 1)", "type": "integer", "example": 2 }, "category_id": { "description": "Category/subject ID (optional)", "type": "integer", "example": 5 }, "type": { "description": "Test type (optional, default: 'testseries')", "type": "string", "example": "testseries" }, "groupId": { "description": "Group ID to assign the test series to (optional)", "type": "integer", "example": 10 }, "has_sections": { "description": "Whether the test has sections (optional)", "type": "boolean", "example": false }, "test_series_type": { "description": "Type of test series: objective (MCQ), subjective (written answers), or integer (numeric answers)", "type": "string", "enum": [ "objective", "subjective", "integer" ], "example": "objective" } }, "type": "object" } } } }, "responses": { "200": { "description": "Test series created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "test_id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "Physics Mock Test 2025" }, "has_sections": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Test series created successfully." } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ] } } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to create test series" }, "error": { "type": "string", "example": "Error details" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/category": { "put": { "tags": [ "Tutor V2 - Test Series Basic" ], "summary": "Update test series category", "description": "Updates the category/subject assignment for a test series", "operationId": "updateTestSeriesCategory", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "category_id" ], "properties": { "category_id": { "description": "New category/subject ID", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "Category updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series category updated successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "category_id": { "type": "integer", "example": 5 }, "category_name": { "type": "string", "example": "Chemistry" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series not found" }, "422": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/subject-list": { "get": { "tags": [ "Tutor V2 - Test Series Basic" ], "summary": "Get subjects for a test series", "description": "Retrieves the list of subjects/topics included in a test series", "operationId": "getTestSeriesSubjectList", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Subject list retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Subject list retrieved successfully" }, "data": { "properties": { "test_series_id": { "type": "integer", "example": 1 }, "subjects": { "type": "array", "items": { "properties": { "subject_id": { "type": "integer", "example": 1 }, "subject_name": { "type": "string", "example": "Physics" }, "question_count": { "type": "integer", "example": 25 }, "marks": { "type": "integer", "example": 50 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{testseries}/{subject}/topic": { "get": { "tags": [ "Tutor V2 - Test Series Basic" ], "summary": "Get topics for a subject in test series", "description": "Retrieves the list of topics for a specific subject within a test series", "operationId": "getTestSeriesTopicList", "parameters": [ { "name": "testseries", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "subject", "in": "path", "description": "Subject ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Topic list retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Topic list retrieved successfully" }, "data": { "properties": { "test_series_id": { "type": "integer", "example": 1 }, "subject_id": { "type": "integer", "example": 1 }, "subject_name": { "type": "string", "example": "Physics" }, "topics": { "type": "array", "items": { "properties": { "topic_id": { "type": "integer", "example": 10 }, "topic_name": { "type": "string", "example": "Mechanics" }, "question_count": { "type": "integer", "example": 10 }, "marks": { "type": "integer", "example": 20 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series or subject not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/update-basic/{id}": { "put": { "tags": [ "Tutor V2 - Test Series Basic" ], "summary": "Update basic test series information", "description": "Updates basic information of a test series (title, description, duration, etc.)", "operationId": "updateBasicTestSeries", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "title": { "description": "Test series title", "type": "string", "example": "Updated Physics Mock Test" }, "description": { "description": "Test description", "type": "string", "example": "Updated description" }, "duration_minutes": { "description": "Test duration in minutes", "type": "integer", "example": 90 }, "total_marks": { "description": "Total marks", "type": "integer", "example": 120 } }, "type": "object" } } } }, "responses": { "200": { "description": "Test series updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series updated successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Updated Physics Mock Test" }, "duration_minutes": { "type": "integer", "example": 90 }, "updated_at": { "type": "string", "example": "2025-01-15 10:00:00" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Test series not found" }, "422": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/questions-for-testseries/{testseries_id}/{topic_id}": { "get": { "tags": [ "Tutor V2 - Test Series Basic" ], "summary": "Get questions for test series by topic", "description": "Retrieves available questions for a specific topic that can be added to the test series", "operationId": "getQuestionsForTestSeries", "parameters": [ { "name": "testseries_id", "in": "path", "description": "Test Series ID (optional)", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "topic_id", "in": "path", "description": "Topic ID (optional)", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Questions retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Questions retrieved successfully" }, "data": { "properties": { "total_questions": { "type": "integer", "example": 50 }, "questions": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 100 }, "question_text": { "type": "string", "example": "What is Newton's first law?" }, "difficulty_level": { "type": "string", "example": "medium" }, "marks": { "type": "integer", "example": 2 }, "is_selected": { "type": "boolean", "example": false } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/scheduled": { "get": { "tags": [ "Tutor V2" ], "summary": "Get all scheduled tests", "description": "Retrieves all test series that are currently scheduled with start and end dates.", "operationId": "scheduledTestSeries", "parameters": [ { "name": "from_date", "in": "query", "description": "Filter from date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "Filter to date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Scheduled tests retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Scheduled tests fetched successfully" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Mathematics Chapter 1 Test" }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "duration_minutes": { "type": "integer", "example": 60 }, "assigned_batches": { "type": "array", "items": { "properties": { "batch_id": { "type": "integer", "example": 5 }, "batch_name": { "type": "string", "example": "Class 10 - Section A" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}": { "get": { "tags": [ "Tutor V2" ], "summary": "Get test series details", "description": "Retrieves detailed information about a specific test series including configuration and statistics.", "operationId": "showTestSeries", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Test series details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series details fetched successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Mathematics Chapter 1 Test" }, "description": { "type": "string" }, "duration_minutes": { "type": "integer", "example": 60 }, "total_marks": { "type": "number", "example": 100 }, "passing_marks": { "type": "number", "example": 40 }, "negative_marking": { "type": "boolean", "example": true }, "negative_marking_value": { "type": "number", "example": 0.25 }, "question_count": { "type": "integer", "example": 25 }, "status": { "type": "string", "example": "scheduled" }, "start_date": { "type": "string", "format": "date-time", "nullable": true }, "end_date": { "type": "string", "format": "date-time", "nullable": true }, "class_id": { "type": "integer", "example": 86 }, "subject_id": { "type": "integer", "example": 90 }, "is_free": { "type": "boolean", "example": true }, "show_answers_after_submit": { "type": "boolean", "example": true }, "shuffle_questions": { "type": "boolean", "example": false }, "shuffle_options": { "type": "boolean", "example": false }, "allow_review": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Not your test series" }, "404": { "description": "Test series not found" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Tutor V2" ], "summary": "Update test series", "description": "Updates the details of an existing test series. Cannot update if test is ongoing or completed.", "operationId": "updateTestSeries", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "duration_minutes": { "type": "integer" }, "total_marks": { "type": "number", "format": "float" }, "passing_marks": { "type": "number", "format": "float", "nullable": true }, "negative_marking": { "type": "boolean" }, "negative_marking_value": { "type": "number", "format": "float", "nullable": true }, "is_free": { "type": "boolean" }, "show_answers_after_submit": { "type": "boolean" }, "shuffle_questions": { "type": "boolean" }, "shuffle_options": { "type": "boolean" }, "allow_review": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Test series updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series updated successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Cannot update ongoing/completed test" }, "404": { "description": "Test series not found" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Tutor V2" ], "summary": "Delete test series", "description": "Soft deletes a test series. Cannot delete if test has started or has student submissions.", "operationId": "destroyTestSeries", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Test series deleted successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Cannot delete test with submissions" }, "404": { "description": "Test series not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/preview": { "get": { "tags": [ "Tutor V2" ], "summary": "Preview test questions", "description": "Retrieves all questions in the test series for preview before publishing or scheduling.", "operationId": "previewTest", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Test preview retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test preview fetched successfully" }, "data": { "properties": { "test_id": { "type": "integer", "example": 1 }, "test_name": { "type": "string", "example": "Mathematics Chapter 1 Test" }, "questions": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 10 }, "question_text": { "type": "string" }, "question_type": { "type": "string", "example": "multiple_choice" }, "marks": { "type": "number", "example": 4 }, "difficulty": { "type": "string", "example": "medium" }, "options": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "is_correct": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Test series not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/questions": { "get": { "tags": [ "Tutor V2" ], "summary": "Get test questions", "description": "Retrieves all questions in the test series with basic information.", "operationId": "getTestSeriesQuestions", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Questions retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Questions fetched successfully" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 10 }, "question_text": { "type": "string" }, "marks": { "type": "number", "example": 4 }, "question_type": { "type": "string", "example": "multiple_choice" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Test series not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/questions/{questionId}": { "delete": { "tags": [ "Tutor V2" ], "summary": "Remove question from test series", "description": "Removes a specific question from the test series. The tutor must own the test series.", "operationId": "removeQuestionFromTestSeries", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } }, { "name": "questionId", "in": "path", "description": "Question ID to remove", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Question removed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Question removed from test series successfully" }, "data": { "properties": { "test_series_id": { "type": "integer", "example": 1 }, "removed_question_id": { "type": "integer", "example": 45 }, "remaining_questions": { "type": "integer", "example": 24 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Only tutors and schools can perform this action" }, "404": { "description": "Test series not found or question not found in test series" }, "500": { "description": "Internal server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/schedule": { "put": { "tags": [ "Tutor V2" ], "summary": "Update test schedule", "description": "Updates the start and end dates of a scheduled test. Cannot update if test has already started.", "operationId": "updateTestSchedule", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "start_date": { "type": "string", "format": "date-time", "example": "2025-12-21 10:00:00" }, "end_date": { "type": "string", "format": "date-time", "example": "2025-12-21 12:00:00" }, "notify_students": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Test schedule updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test schedule updated successfully" }, "data": { "properties": { "test_id": { "type": "integer", "example": 1 }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Cannot update started test" }, "404": { "description": "Test series not found" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Tutor V2" ], "summary": "Schedule a test", "description": "Schedules a test series with start and end dates.", "operationId": "scheduleTest", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "start_date", "end_date" ], "properties": { "start_date": { "type": "string", "format": "date-time", "example": "2025-12-20 10:00:00" }, "end_date": { "type": "string", "format": "date-time", "example": "2025-12-20 12:00:00" }, "notify_students": { "description": "Send notification to enrolled students", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Test scheduled successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test scheduled successfully" }, "data": { "properties": { "test_id": { "type": "integer", "example": 1 }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "status": { "type": "string", "example": "scheduled" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Test series not found" }, "422": { "description": "Validation error - Invalid dates" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/cancel": { "post": { "tags": [ "Tutor V2" ], "summary": "Cancel a scheduled test", "description": "Cancels a scheduled test. Students will be notified about the cancellation.", "operationId": "cancelTest", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "reason": { "type": "string", "example": "Technical issues", "nullable": true }, "notify_students": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Test cancelled successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test cancelled successfully" }, "data": { "properties": { "test_id": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "cancelled" }, "cancelled_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Cannot cancel completed test" }, "404": { "description": "Test series not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/search": { "get": { "tags": [ "Tutor V2" ], "summary": "Search test series", "description": "Searches test series by name, description, or tags with advanced filtering.", "operationId": "searchTestSeries", "parameters": [ { "name": "q", "in": "query", "description": "Search query", "required": true, "schema": { "type": "string" } }, { "name": "class_id", "in": "query", "description": "Filter by class", "required": false, "schema": { "type": "integer" } }, { "name": "subject_id", "in": "query", "description": "Filter by subject", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Search results retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Search completed successfully" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "total_marks": { "type": "number" }, "duration_minutes": { "type": "integer" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/assign": { "post": { "tags": [ "Tutor V2" ], "summary": "Quick assign test to a group", "description": "Quickly assigns a test series to a single batch/group. Use assign-to-groups for multiple groups.", "operationId": "assignTest", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "group_id" ], "properties": { "group_id": { "description": "Batch/Group ID to assign the test to", "type": "integer", "example": 5 }, "start_date": { "type": "string", "format": "date-time", "example": "2025-12-20 10:00:00", "nullable": true }, "end_date": { "type": "string", "format": "date-time", "example": "2025-12-20 12:00:00", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Test assigned successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test assigned to group successfully" }, "data": { "properties": { "test_id": { "type": "integer", "example": 1 }, "group_id": { "type": "integer", "example": 5 }, "group_name": { "type": "string", "example": "Class 10 - Section A" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Test series or group not found" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/duplicate": { "post": { "tags": [ "Tutor V2" ], "summary": "Duplicate a test series", "description": "Creates a complete copy of an existing test series including all questions and settings. The duplicate will be created as a draft with a new unique name and slug.", "operationId": "duplicateTestSeries", "parameters": [ { "name": "id", "in": "path", "description": "Test Series ID to duplicate", "required": true, "schema": { "type": "integer", "example": 2424 } } ], "requestBody": { "description": "Optional customization for the duplicated test series", "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "description": "Custom name for the duplicated test (defaults to 'Copy of [original name]')", "type": "string", "maxLength": 255, "example": "Mathematics Chapter 1 Test - Version 2", "nullable": true }, "include_questions": { "description": "Whether to copy all questions from the original test (default: true)", "type": "boolean", "example": true, "nullable": true }, "include_schedule": { "description": "Whether to copy schedule dates (default: false - dates will be cleared)", "type": "boolean", "example": false, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Test series duplicated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Test series duplicated successfully" }, "data": { "properties": { "id": { "description": "ID of the newly created duplicate test", "type": "integer", "example": 2425 }, "name": { "description": "Name of the duplicated test", "type": "string", "example": "Copy of Mathematics Chapter 1 Test" }, "original_id": { "description": "ID of the original test that was duplicated", "type": "integer", "example": 2424 }, "total_questions": { "description": "Number of questions copied", "type": "integer", "example": 50 }, "slug": { "description": "Unique slug for the duplicate", "type": "string", "example": "copy-of-mathematics-chapter-1-test-1735907234" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "404": { "description": "Test series not found or access denied", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Test series not found or you do not have permission to access it" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "properties": { "name": { "type": "array", "items": { "type": "string", "example": "The name must not exceed 255 characters." } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error during duplication", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to duplicate test series" }, "error": { "type": "string", "example": "Database transaction failed" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{id}/getSections": { "get": { "tags": [ "Tutor V2 - Test Series Sections" ], "summary": "Get test series with all sections", "description": "Retrieves a test series along with all its sections and section details including questions count.", "operationId": "getTestSeriesWithSections", "parameters": [ { "name": "id", "in": "path", "description": "Parent Test Series ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Test series with sections retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "test_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "JEE Main Mock Test 2025" }, "type": { "type": "string", "example": "testseries" }, "category_id": { "type": "integer", "example": 5 }, "total_time": { "type": "integer", "example": 180 }, "has_sections": { "type": "boolean", "example": true }, "sections_count": { "type": "integer", "example": 3 }, "sections": { "type": "array", "items": { "properties": { "section_id": { "type": "integer", "example": 10 }, "section_name": { "type": "string", "example": "Physics" }, "section_title": { "type": "string", "example": "JEE Main Mock Test 2025 - Physics" }, "sequence": { "type": "integer", "example": 1 }, "total_questions": { "type": "integer", "example": 25 }, "questions_added": { "type": "integer", "example": 20 }, "per_ques_mark": { "type": "number", "example": 4 }, "negative_marks": { "type": "number", "example": 1 }, "total_time": { "type": "integer", "example": 60 }, "total_marks": { "type": "number", "example": 80 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Test series not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{parent_id}/addSection": { "post": { "tags": [ "Tutor V2 - Test Series Sections" ], "summary": "Add sections to test series", "description": "Adds one or more sections to an existing test series with questions and configuration.", "operationId": "addSections", "parameters": [ { "name": "parent_id", "in": "path", "description": "Parent Test Series ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "sections" ], "properties": { "sections": { "type": "array", "items": { "required": [ "section_name", "total_questions", "per_ques_mark" ], "properties": { "section_name": { "type": "string", "maxLength": 100, "example": "Physics Section" }, "sequence": { "description": "Display order of section", "type": "integer", "example": 1, "nullable": true }, "total_questions": { "description": "Total questions in this section", "type": "integer", "example": 25 }, "per_ques_mark": { "description": "Marks per question", "type": "number", "format": "float", "example": 4 }, "total_time": { "description": "Section duration in minutes (optional)", "type": "integer", "example": 60, "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Sections added successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "parent_test_id": { "type": "integer", "example": 1 }, "parent_test_name": { "type": "string", "example": "JEE Main Mock Test 2025" }, "sections_created": { "type": "array", "items": { "properties": { "section_id": { "type": "integer", "example": 10 }, "section_name": { "type": "string", "example": "Physics Section" }, "sequence": { "type": "integer", "example": 1 } }, "type": "object" } }, "total_sections": { "type": "integer", "example": 3 }, "message": { "type": "string", "example": "Sections created successfully. Now add questions to each section." } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Parent test series not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/updateSection/{section_id}": { "put": { "tags": [ "Tutor V2 - Test Series Sections" ], "summary": "Update test section", "description": "Updates the details of an existing test section including questions and configuration.", "operationId": "updateSection", "parameters": [ { "name": "section_id", "in": "path", "description": "Section ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "section_name": { "type": "string", "maxLength": 100, "example": "Updated Physics Section" }, "total_questions": { "type": "integer", "example": 30 }, "per_ques_mark": { "type": "number", "format": "float", "example": 4 }, "total_time": { "type": "integer", "example": 60 }, "sequence": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Section updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "section_id": { "type": "integer", "example": 10 }, "message": { "type": "string", "example": "Section updated successfully" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Section not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/test-series/{parent_id}/sections/{section_id}": { "delete": { "tags": [ "Tutor V2 - Test Series Sections" ], "summary": "Delete test section", "description": "Deletes a section from a test series along with its associated questions.", "operationId": "deleteSection", "parameters": [ { "name": "parent_id", "in": "path", "description": "Parent Test Series ID", "required": true, "schema": { "type": "integer" } }, { "name": "section_id", "in": "path", "description": "Section ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Section deleted successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Section deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Section does not belong to this test" }, "404": { "description": "Section or test series not found" }, "500": { "description": "Server error" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/testSeries-list-with-getSections": { "get": { "tags": [ "Tutor V2 - Test Series Sections" ], "summary": "Get all test series with sections", "description": "Retrieves a complete list of all test series including their sections. Useful for overview and reporting.", "operationId": "getAllTestSeriesWithSectionDetails", "responses": { "200": { "description": "All test series with sections retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "All test series with sections fetched successfully" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "JEE Main Mock Test 2025" }, "has_sections": { "type": "boolean", "example": true }, "total_marks": { "type": "number", "example": 300 }, "total_time": { "type": "integer", "example": 180 }, "sections": { "type": "array", "items": { "properties": { "section_id": { "type": "integer", "example": 10 }, "section_name": { "type": "string", "example": "Physics" }, "section_marks": { "type": "number", "example": 100 }, "question_count": { "type": "integer", "example": 25 } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/api/v2/tutor/sectionsData/{id}": { "get": { "tags": [ "Tutor V2 - Test Series Sections" ], "summary": "Get section details", "description": "Retrieves detailed information about a specific section including all questions, marks distribution, and configuration.", "operationId": "getSectionDetails", "parameters": [ { "name": "id", "in": "path", "description": "Section ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Section details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Section details fetched successfully" }, "data": { "properties": { "section_id": { "type": "integer", "example": 10 }, "parent_test_id": { "type": "integer", "example": 1 }, "parent_test_name": { "type": "string", "example": "JEE Main Mock Test 2025" }, "name": { "type": "string", "example": "Physics Section" }, "description": { "type": "string" }, "total_time": { "type": "integer", "example": 60 }, "per_ques_mark": { "type": "number", "example": 4 }, "negative_marks": { "type": "number", "example": 1 }, "sequence": { "type": "integer", "example": 1 }, "total_questions": { "type": "integer", "example": 25 }, "questions_added": { "type": "integer", "example": 20 }, "total_marks": { "type": "number", "example": 80 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Section not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/user/profile": { "get": { "tags": [ "User Authentication" ], "summary": "Get user profile", "description": "Retrieves the authenticated user's profile information.", "operationId": "getUserProfile", "responses": { "200": { "description": "Profile retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "integer", "example": 50 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "user@example.com" }, "mobile_no": { "type": "string", "example": "9876543210" }, "image": { "type": "string", "example": "http://example.com/storage/user_profile/image.jpg", "nullable": true }, "wallet_balance": { "type": "number", "format": "float", "example": 500 }, "referral_code": { "type": "string", "example": "ABC123" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } } }, "components": { "responses": { "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to retrieve batch tests" }, "error": { "type": "string" } }, "type": "object" } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "Enter your bearer token", "bearerFormat": "JWT", "scheme": "bearer" }, "sanctum": { "type": "apiKey", "description": "Enter your bearer token in the format (Bearer )", "name": "Authorization", "in": "header" } } }, "tags": [ { "name": "Teacher - Auto Generate Test Series", "description": "Auto-generate test series with AI questions and payment handling" }, { "name": "School V2", "description": "School authentication and management endpoints" }, { "name": "Tutor", "description": "Tutor V1 Management and Operations" }, { "name": "Tutor V2", "description": "Tutor V2 API Endpoints for enhanced functionality" }, { "name": "User Authentication", "description": "Student/User Authentication Endpoints" }, { "name": "Notifications", "description": "Push Notification and Device Token Management" }, { "name": "Guest user", "description": "Guest user" }, { "name": "Authentication", "description": "Authentication" }, { "name": "Utility", "description": "Utility" }, { "name": "Teacher - Test Series", "description": "Teacher - Test Series" }, { "name": "Tutor - Test Series", "description": "Tutor - Test Series" }, { "name": "Teacher", "description": "Teacher" }, { "name": "tutor", "description": "tutor" }, { "name": "user", "description": "user" }, { "name": "Test Series", "description": "Test Series" }, { "name": "notification", "description": "notification" }, { "name": "AI Question Generation V2", "description": "AI Question Generation V2" }, { "name": "Tutor V2 - Group Management", "description": "Tutor V2 - Group Management" }, { "name": "Question Bank V2", "description": "Question Bank V2" }, { "name": "School - Test Series", "description": "School - Test Series" }, { "name": "Student", "description": "Student" }, { "name": "Subject & Topics with Class", "description": "Subject & Topics with Class" }, { "name": "Tutor V2 - Test Series", "description": "Tutor V2 - Test Series" }, { "name": "Tutor V2 - Student Management", "description": "Tutor V2 - Student Management" }, { "name": "notifications", "description": "notifications" }, { "name": "PDF", "description": "PDF" }, { "name": "Student - Enrollment", "description": "Student - Enrollment" }, { "name": "Tutor V2 - Export & Assignment", "description": "Tutor V2 - Export & Assignment" }, { "name": "Tutor V2 - Question Bank", "description": "Tutor V2 - Question Bank" }, { "name": "Tutor V2 - Paper Creation", "description": "Tutor V2 - Paper Creation" }, { "name": "Tutor V2 - Class Management", "description": "Tutor V2 - Class Management" }, { "name": "Tutor V2 - School Management", "description": "Tutor V2 - School Management" }, { "name": "Tutor V2 - Test Series Basic", "description": "Tutor V2 - Test Series Basic" }, { "name": "Tutor V2 - Test Series Sections", "description": "Tutor V2 - Test Series Sections" } ] }