{ "openapi": "3.0.3", "info": { "title": "Task Management REST API", "description": "Production Enterprise REST API specification for Task Management. Includes authentication, user management, full task lifecycle management, date-wise workload schedule, subtasks, discussion comments, departments, academic classes/subjects, role-based access control, audit logs, system settings, and analytics.", "version": "1.0.0", "contact": { "name": "Task Management Team", "email": "support@eveapplication.local" } }, "servers": [ { "url": "/", "description": "Current Environment Server" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Enter your JWT token obtained from `/api/login`." } }, "schemas": { "StandardSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Operation completed successfully." }, "data": { "type": "object" } } }, "Task": { "type": "object", "properties": { "id": { "type": "integer", "example": 101 }, "title": { "type": "string", "example": "Physics Lecture Video Editing" }, "description": { "type": "string", "example": "Complete color grading and sound mastering." }, "assigned_to": { "type": "string", "format": "uuid", "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "department_id": { "type": "string", "format": "uuid", "nullable": true, "example": "aba4f964-aac0-4229-8d51-484c67fce326" }, "task_type": { "type": "string", "nullable": true, "description": "Category slug or code of the task (e.g. book, video, or custom type)", "example": "book" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "example": "urgent" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "revision", "review", "completed", "approved", "cancelled" ], "example": "in_progress" }, "start_date": { "type": "string", "format": "date-time", "example": "2026-10-05 4:20 P.M" }, "due_date": { "type": "string", "format": "date-time", "example": "2026-10-15 4:25 P.M" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "task_type_id": { "type": "string", "format": "uuid", "nullable": true, "example": "3b2e53fa-92b0-4581-91d1-67825bbd203e" } } }, "UserWorkload": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "department": { "type": "string", "nullable": true } } }, "summary": { "type": "object", "properties": { "total_assigned": { "type": "integer", "example": 12 }, "active_tasks": { "type": "integer", "example": 5 }, "completed_tasks": { "type": "integer", "example": 7 }, "overdue_tasks": { "type": "integer", "example": 1 } } }, "conflict_check": { "type": "object", "properties": { "checked_date": { "type": "string", "format": "date", "example": "2026-09-29" }, "has_conflict": { "type": "boolean", "example": true }, "conflict_count": { "type": "integer", "example": 2 }, "tasks_on_date": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } } }, "datewise_tasks": { "type": "object", "description": "Tasks grouped date-wise by YYYY-MM-DD or 'No Due Date'", "additionalProperties": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "date_formatted": { "type": "string", "example": "Sep 29, 2026 (Tue)" }, "task_count": { "type": "integer", "example": 2 }, "active_count": { "type": "integer", "example": 2 }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } } } } } }, "ReportSummary": { "type": "object", "properties": { "kpis": { "type": "object", "properties": { "total_tasks": { "type": "integer", "example": 45 }, "completed_tasks": { "type": "integer", "example": 32 }, "completed_ontime": { "type": "integer", "example": 25 }, "completed_ext_1": { "type": "integer", "example": 5 }, "completed_ext_2": { "type": "integer", "example": 2 }, "in_progress_tasks": { "type": "integer", "example": 8 }, "pending_tasks": { "type": "integer", "example": 3 }, "revision_tasks": { "type": "integer", "example": 2 }, "overdue_tasks": { "type": "integer", "example": 4 }, "completion_rate": { "type": "number", "format": "float", "example": 71.1 }, "total_departments": { "type": "integer", "example": 8 }, "total_employees": { "type": "integer", "example": 24 } } }, "filters_applied": { "type": "object" } } }, "DepartmentReportItem": { "type": "object", "properties": { "department_id": { "type": "string", "format": "uuid", "example": "aba4f964-aac0-4229-8d51-484c67fce326" }, "name": { "type": "string", "example": "Information Technology" }, "code": { "type": "string", "example": "IT" }, "description": { "type": "string", "example": "IT and Software Infrastructure" }, "lead": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } } }, "metrics": { "type": "object", "properties": { "total_tasks": { "type": "integer", "example": 14 }, "completed_tasks": { "type": "integer", "example": 10 }, "completed_ontime": { "type": "integer", "example": 8 }, "completed_ext_1": { "type": "integer", "example": 2 }, "completed_ext_2": { "type": "integer", "example": 0 }, "in_progress_tasks": { "type": "integer", "example": 3 }, "pending_tasks": { "type": "integer", "example": 1 }, "revision_tasks": { "type": "integer", "example": 0 }, "review_tasks": { "type": "integer", "example": 0 }, "cancelled_tasks": { "type": "integer", "example": 0 }, "overdue_tasks": { "type": "integer", "example": 1 }, "completion_rate": { "type": "number", "format": "float", "example": 71.4 } } } } }, "TaskReportItem": { "type": "object", "properties": { "id": { "type": "integer", "example": 101 }, "title": { "type": "string", "example": "Class 10 Physics Video Editing" }, "description": { "type": "string" }, "plain_description": { "type": "string" }, "status": { "type": "string", "example": "in_progress" }, "priority": { "type": "string", "example": "urgent" }, "start_date": { "type": "string", "format": "date", "example": "2026-09-25" }, "start_date_formatted": { "type": "string", "example": "Sep 25, 2026" }, "due_date": { "type": "string", "format": "date", "example": "2026-09-30" }, "due_date_formatted": { "type": "string", "example": "Sep 30, 2026" }, "extension_count": { "type": "integer", "example": 0 }, "is_overdue": { "type": "boolean", "example": false }, "completion_percentage": { "type": "integer", "example": 50 }, "department": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": "string" } } }, "assigned_to": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "department": { "type": "string", "nullable": true } } }, "created_by": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } } } } }, "MonthReportItem": { "type": "object", "properties": { "month": { "type": "integer", "example": 9 }, "month_name": { "type": "string", "example": "September" }, "month_short": { "type": "string", "example": "Sep" }, "year": { "type": "integer", "example": 2026 }, "total_tasks": { "type": "integer", "example": 18 }, "completed_tasks": { "type": "integer", "example": 14 }, "completed_ontime": { "type": "integer", "example": 12 }, "completed_extended": { "type": "integer", "example": 2 }, "in_progress_tasks": { "type": "integer", "example": 3 }, "pending_tasks": { "type": "integer", "example": 1 }, "overdue_tasks": { "type": "integer", "example": 1 }, "completion_rate": { "type": "number", "format": "float", "example": 77.8 }, "priority_breakdown": { "type": "object", "properties": { "urgent": { "type": "integer", "example": 4 }, "high": { "type": "integer", "example": 6 }, "medium": { "type": "integer", "example": 5 }, "low": { "type": "integer", "example": 3 } } } } }, "WeeklyReportItem": { "type": "object", "properties": { "week_number": { "type": "integer", "example": 39 }, "year": { "type": "integer", "example": 2026 }, "week_key": { "type": "string", "example": "2026-W39" }, "start_date": { "type": "string", "format": "date", "example": "2026-09-21" }, "end_date": { "type": "string", "format": "date", "example": "2026-09-27" }, "label": { "type": "string", "example": "Week 39 (21 Sep - 27 Sep 2026)" }, "total_tasks": { "type": "integer", "example": 8 }, "completed_tasks": { "type": "integer", "example": 6 }, "completed_ontime": { "type": "integer", "example": 5 }, "completed_extended": { "type": "integer", "example": 1 }, "in_progress_tasks": { "type": "integer", "example": 2 }, "pending_tasks": { "type": "integer", "example": 0 }, "overdue_tasks": { "type": "integer", "example": 0 }, "completion_rate": { "type": "number", "format": "float", "example": 75 } } }, "EmployeeReportItem": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Alice Walker" }, "email": { "type": "string", "example": "alice@eveapplication.com" }, "mobile_number": { "type": "string", "nullable": true }, "department": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": "string" } } }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "teacher" ] } } }, "metrics": { "type": "object", "properties": { "total_assigned": { "type": "integer", "example": 10 }, "completed": { "type": "integer", "example": 7 }, "completed_ontime": { "type": "integer", "example": 5 }, "completed_ext_1": { "type": "integer", "example": 2 }, "completed_ext_2": { "type": "integer", "example": 0 }, "in_progress": { "type": "integer", "example": 2 }, "review": { "type": "integer", "example": 0 }, "revision": { "type": "integer", "example": 1 }, "pending": { "type": "integer", "example": 0 }, "cancelled": { "type": "integer", "example": 0 }, "overdue": { "type": "integer", "example": 1 }, "completion_rate": { "type": "number", "format": "float", "example": 70 } } }, "status_distribution": { "type": "object", "properties": { "completed": { "type": "integer", "example": 7 }, "in_progress": { "type": "integer", "example": 2 }, "review": { "type": "integer", "example": 0 }, "revision": { "type": "integer", "example": 1 }, "pending": { "type": "integer", "example": 0 }, "cancelled": { "type": "integer", "example": 0 } } } } }, "Workflow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "Video Production Pipeline" }, "code": { "type": "string", "example": "VID_PIPE" }, "description": { "type": "string", "nullable": true }, "department_id": { "type": "string", "format": "uuid", "nullable": true }, "stages": { "type": "array", "items": { "type": "string" }, "example": [ "Initiated", "In Progress", "Review", "Completed" ] }, "is_active": { "type": "boolean", "example": true }, "sort_order": { "type": "integer", "example": 1 }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "tasks_count": { "type": "integer", "example": 5 }, "department": { "$ref": "#/components/schemas/Department" }, "creator": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkflowStage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "650e8400-e29b-41d4-a716-446655440001" }, "workflow_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "Script Review" }, "code": { "type": "string", "example": "SCRIPT_REVIEW" }, "color_code": { "type": "string", "example": "#4f46e5" }, "description": { "type": "string", "nullable": true, "example": "Review and approval of the script by the lead director." }, "sort_order": { "type": "integer", "example": 1 }, "is_active": { "type": "boolean", "example": true }, "workflow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkflowStageInput": { "type": "object", "required": [ "workflow_id", "name" ], "properties": { "workflow_id": { "type": "string", "format": "uuid", "description": "UUID of the selected parent workflow from workflows master table", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "Name of the stage/section", "example": "Video Editing" }, "code": { "type": "string", "description": "Unique uppercase stage code (auto-generated if omitted)", "example": "VIDEO_EDIT" }, "color_code": { "type": "string", "description": "HEX color badge for this section in the task workflow", "example": "#4f46e5" }, "description": { "type": "string", "nullable": true, "description": "Description of what happens during this stage", "example": "Trimming footage and rough cut assembly." }, "sort_order": { "type": "integer", "description": "Sequence order of the stage (1-based)", "example": 2 }, "is_active": { "type": "boolean", "description": "Whether this stage is active", "default": true } } }, "TaskTypeInput": { "type": "object", "required": [ "name" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "3b2e53fa-92b0-4581-91d1-67825bbd203e" }, "name": { "type": "string", "maxLength": 255, "description": "Unique task type name", "example": "Animation Task" }, "code": { "type": "string", "maxLength": 50, "nullable": true, "description": "Unique short code (auto-slugified from name if omitted)", "example": "animation_task" }, "is_active": { "type": "boolean", "default": true, "description": "Whether this task type is active", "example": true } } }, "Department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "aba4f964-aac0-4229-8d51-484c67fce326" }, "parent_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Parent department UUID if this is a sub-department, or null if root", "example": null }, "name": { "type": "string", "example": "Media & Content Production" }, "code": { "type": "string", "example": "MEDIA" }, "description": { "type": "string", "nullable": true, "example": "Main media and content creation division" }, "lead_id": { "type": "string", "format": "uuid", "nullable": true, "example": "a335819e-3c8d-4040-b72a-8ec007140574" }, "parent": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": "string" } } }, "lead": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } } } }, "sub_departments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "parent_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": "string" }, "lead_id": { "type": "string", "format": "uuid", "nullable": true }, "tasks_count": { "type": "integer" }, "users_count": { "type": "integer" } } } }, "tasks_count": { "type": "integer", "example": 12 }, "users_count": { "type": "integer", "example": 8 }, "sub_departments_count": { "type": "integer", "example": 3 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DepartmentInput": { "type": "object", "required": [ "name", "code", "description" ], "properties": { "name": { "type": "string", "example": "Video Editing" }, "code": { "type": "string", "example": "VID_EDIT" }, "description": { "type": "string", "example": "Video editing and post-production unit" }, "lead_id": { "type": "string", "format": "uuid", "nullable": true, "example": "a335819e-3c8d-4040-b72a-8ec007140574" }, "parent_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional UUID of the parent department. Leave null or omit to create a top-level department.", "example": "aba4f964-aac0-4229-8d51-484c67fce326" } } }, "TaskSubtask": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "task_id": { "type": "string", "format": "uuid", "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "department_id": { "type": "string", "format": "uuid", "nullable": true, "example": "aba4f964-aac0-4229-8d51-484c67fce326" }, "title": { "type": "string", "example": "Audio Sync & Sound Design" }, "description": { "type": "string", "nullable": true, "example": "Master the raw audio track" }, "page_no": { "type": "string", "nullable": true, "example": "12-15", "description": "Page number or page range" }, "assigned_to": { "type": "string", "format": "uuid", "nullable": true, "example": "9a1b2c3d-0000-0000-0000-000000000002" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "revision", "approved" ], "example": "pending" }, "start_date": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-10-06 10:00:00" }, "due_date": { "type": "object", "nullable": true, "example": { "from": "2026-10-15 10:00:00", "to": "2026-10-29 18:00:00" } }, "extension_count": { "type": "integer", "example": 0 }, "revision_date": { "type": "string", "format": "date-time", "nullable": true }, "revision_notes": { "type": "string", "nullable": true }, "approved_at": { "type": "string", "format": "date-time", "nullable": true }, "approved_by": { "type": "string", "format": "uuid", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "security": [ { "BearerAuth": [] } ], "paths": { "/api/docs": { "get": { "tags": [ "Documentation" ], "summary": "Interactive Swagger UI Documentation", "security": [], "responses": { "200": { "description": "HTML Documentation view" } } } }, "/api/swagger.json": { "get": { "tags": [ "Documentation" ], "summary": "OpenAPI 3.0 Specification JSON", "security": [], "responses": { "200": { "description": "JSON specification" } } } }, "/api/register": { "post": { "tags": [ "Authentication" ], "summary": "Register a new user or multiple users", "description": "Creates a single user or registers multiple users in bulk. Each user can be assigned multiple departments and subjects. Returns JWT tokens and user profiles.", "operationId": "register", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Single User Registration", "required": [ "name", "email", "mobile_number", "password" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@eveapplication.com" }, "mobile_number": { "type": "string", "maxLength": 20, "example": "9876543210", "description": "Also accepts mobileNumber." }, "password": { "type": "string", "format": "password", "minLength": 6, "example": "password123" }, "class_id": { "type": "string", "format": "uuid", "nullable": true, "example": null }, "department_ids": { "type": "array", "description": "List of department UUIDs assigned to the user.", "items": { "type": "string", "format": "uuid" }, "uniqueItems": true, "example": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "7fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "subject_ids": { "type": "array", "description": "List of subject UUIDs assigned to the user.", "items": { "type": "string", "format": "uuid" }, "uniqueItems": true, "example": [ "8fa85f64-5717-4562-b3fc-2c963f66afa6" ] } } }, { "type": "object", "title": "Multiple Users Registration", "required": [ "users" ], "properties": { "department_ids": { "type": "array", "description": "Department UUIDs shared by all users unless overridden by a user's department_ids.", "items": { "type": "string", "format": "uuid" }, "uniqueItems": true, "example": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "7fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "subject_ids": { "type": "array", "description": "Subject UUIDs shared by all users unless overridden by a user's subject_ids.", "items": { "type": "string", "format": "uuid" } }, "class_id": { "type": "string", "format": "uuid", "nullable": true }, "users": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "name", "email", "mobile_number", "password" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@eveapplication.com" }, "mobile_number": { "type": "string", "example": "9876543210" }, "password": { "type": "string", "format": "password", "minLength": 6, "example": "password123" }, "department_ids": { "type": "array", "description": "Optional department UUIDs specific to this user.", "items": { "type": "string", "format": "uuid" }, "uniqueItems": true }, "subject_ids": { "type": "array", "description": "Optional subject UUIDs specific to this user.", "items": { "type": "string", "format": "uuid" }, "uniqueItems": true }, "class_id": { "type": "string", "format": "uuid", "nullable": true } } } } } } ] } } } }, "responses": { "201": { "description": "User registration successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Registration successful." }, "token": { "type": "string", "example": "eyJ0eXAiOiJKV1QiLC..." }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "example": 86400 }, "refresh_token": { "type": "string" }, "userDetails": { "type": "object", "description": "Registered user profile." } } } } } }, "422": { "description": "Validation error, duplicate email/mobile number, or invalid department/subject IDs." }, "500": { "description": "Registration failed due to a server error." } } } }, "/api/login": { "post": { "tags": [ "Authentication" ], "summary": "User Login (Phone number and password only)", "description": "Authenticates user strictly via mobile phone number (`mobile_number`) and password. Tracks client IP and records audit log.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "password" ], "properties": { "mobile_number": { "type": "string", "example": "9999999999", "description": "10-digit mobile phone number" }, "password": { "type": "string", "example": "password" } } } } } }, "responses": { "200": { "description": "Authenticated successfully with JWT access token and refresh token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Login successful." }, "token": { "type": "string", "example": "eyJ0eXAiOiJKV1QiLC..." }, "refresh_token": { "type": "string", "example": "eyJ0eXAiOiJKV1QiLC..." }, "userDetails": { "type": "object" } } } } } }, "401": { "description": "Invalid mobile number or password" }, "422": { "description": "Validation error (missing mobile number or password)" } } } }, "/api/fresh-token": { "post": { "tags": [ "Authentication" ], "summary": "Obtain Fresh JWT Access Token via Refresh Token (OAuth 2.0)", "description": "Standard OAuth 2.0 refresh endpoint for React / Flutter / Web / Mobile. Validates refresh token signature and type, rotates the refresh token (RTR), provides concurrency grace window protection against parallel request race conditions, and returns a new access token and rotated refresh token.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string", "example": "eyJ0eXAiOiJKV1QiLC...", "description": "Valid refresh token (also accepted via refreshToken, X-Refresh-Token header, or Authorization: Bearer )" } } } } } }, "responses": { "200": { "description": "Token refreshed successfully with new access and rotated refresh token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Token refreshed successfully." }, "responseMessage": { "type": "string", "example": "Token refreshed successfully." }, "token": { "type": "string", "example": "eyJ0eXAiOiJKV1QiLC..." }, "access_token": { "type": "string", "example": "eyJ0eXAiOiJKV1QiLC..." }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "example": 86400 }, "refresh_token": { "type": "string", "example": "eyJ0eXAiOiJKV1QiLC..." }, "userDetails": { "type": "object" }, "user": { "type": "object" } } } } } }, "401": { "description": "Unauthorized: Invalid, expired, reused, or revoked refresh token" }, "403": { "description": "Forbidden: User account has been deactivated" }, "422": { "description": "Unprocessable Entity: Missing refresh token" } } } }, "/api/me": { "get": { "tags": [ "Authentication" ], "summary": "Get authenticated user profile and roles", "responses": { "200": { "description": "User details" } } } }, "/api/logout": { "post": { "tags": [ "Authentication" ], "summary": "User Logout", "description": "Invalidates current authentication token session.", "responses": { "200": { "description": "Logged out successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Successfully logged out." } } } } } } } } }, "/api/tasks": { "get": { "tags": [ "Tasks" ], "summary": "List tasks with search, status, priority, and department filtering", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "priority", "in": "query", "schema": { "type": "string" } }, { "name": "assigned_to", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Filter by exact start date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "start_date_from", "in": "query", "description": "Filter tasks with start date on or after this date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "start_date_to", "in": "query", "description": "Filter tasks with start date on or before this date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "due_date_from", "in": "query", "description": "Filter tasks with due date on or after this date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "due_date_to", "in": "query", "description": "Filter tasks with due date on or before this date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "task_type_id", "in": "query", "required": false, "description": "Filter tasks by task type UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of tasks", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "tasks": [ { "id": "8e051dfd-d308-4f25-b4c1-b285baf3136e", "title": "Book Publishing Task", "status": "in_progress", "priority": "medium", "extension_count": 1, "revision_count": 1, "correction_count": 0, "requested_days": 3, "approved_days": 1, "subtasks": [ { "id": "c1f71587-ba42-4545-927a-8f5339678822", "title": "Page layout typography correction", "status": "in_progress", "extension_count": 1, "revision_count": 1, "correction_count": 0, "requested_days": 3, "approved_days": 1, "approved_date": "2026-10-29 18:00:00" } ] } ], "pagination": { "total": 1, "per_page": 15, "current_page": 1, "last_page": 1 } } } } } } }, "post": { "tags": [ "Tasks" ], "summary": "Create a new task", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "priority" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "assigned_to": { "type": "string", "format": "uuid" }, "department_id": { "type": "string", "format": "uuid", "nullable": true }, "task_type_id": { "type": "string", "format": "uuid", "nullable": true }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "status": { "type": "string", "example": "pending" }, "start_date": { "type": "string", "format": "date-time", "example": "2026-10-05 4:20 P.M" }, "due_date": { "type": "string", "format": "date-time", "example": "2026-10-15 4:25 P.M" }, "reminder_at": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-10-14 09:00:00" } } } } } }, "responses": { "201": { "description": "Task created successfully" } } } }, "/api/tasks/{id}": { "get": { "tags": [ "Tasks" ], "summary": "Get task details by ID", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task retrieved successfully", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "task": { "id": "8e051dfd-d308-4f25-b4c1-b285baf3136e", "title": "Book Publishing Task", "status": "in_progress", "priority": "medium", "extension_count": 1, "revision_count": 1, "correction_count": 0, "requested_days": 3, "approved_days": 1, "subtasks": [ { "id": "c1f71587-ba42-4545-927a-8f5339678822", "title": "Page layout typography correction", "status": "in_progress", "extension_count": 1, "revision_count": 1, "correction_count": 0, "requested_days": 3, "approved_days": 1, "approved_date": "2026-10-29 18:00:00" } ] } } } } } } }, "put": { "tags": [ "Tasks" ], "summary": "Update task details", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "assigned_to": { "type": "string", "format": "uuid" }, "department_id": { "type": "string", "format": "uuid", "nullable": true }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "status": { "type": "string", "example": "in_progress" }, "start_date": { "type": "string", "format": "date-time", "example": "2026-10-05 4:20 P.M" }, "due_date": { "type": "string", "format": "date-time", "example": "2026-10-15 4:25 P.M" }, "reminder_at": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-10-14 09:00:00" } } } } } }, "responses": { "200": { "description": "Task updated successfully" } } }, "delete": { "tags": [ "Tasks" ], "summary": "Delete task by ID", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task deleted successfully" } } } }, "/api/tasks/user-workload/{userId}": { "get": { "tags": [ "Tasks - Workload & Date Schedule" ], "summary": "Get date-wise assigned tasks & workload schedule for a specific user", "description": "Returns a comprehensive date-wise breakdown of tasks assigned to the target user with summary counters (total, active, completed, overdue) and optional conflict detection against a specified ?date=YYYY-MM-DD.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target User UUID" }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Target date to check for scheduling conflicts (YYYY-MM-DD)" } ], "responses": { "200": { "description": "User workload & date-wise schedule retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWorkload" } } } }, "404": { "description": "User not found" } } } }, "/api/tasks/workload": { "get": { "tags": [ "Tasks - Workload & Date Schedule" ], "summary": "Query date-wise workload schedule by user_id and date", "description": "Alternate endpoint accepting `?user_id=UUID&date=YYYY-MM-DD` query parameters.", "parameters": [ { "name": "user_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Workload schedule retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWorkload" } } } } } } }, "/api/tasks/{id}/status": { "patch": { "tags": [ "Tasks" ], "summary": "Quick status update for task", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "in_progress", "revision", "review", "completed", "approved", "cancelled" ] } } } } } }, "responses": { "200": { "description": "Status updated" } } } }, "/api/tasks/{id}/assign": { "patch": { "tags": [ "Tasks" ], "summary": "Quick re-assign task to user", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assigned_to": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "200": { "description": "Task assigned successfully" } } } }, "/api/tasks/subtasks": { "get": { "tags": [ "Task Subtasks" ], "summary": "List all subtasks (Task ID not required)", "description": "List subtasks globally across all tasks or optionally filter by parent task ID, assignee, status, search keyword, or pagination. Task ID is NOT required.", "parameters": [ { "name": "task_id", "in": "query", "required": false, "description": "Filter subtasks by parent Task UUID or ID", "schema": { "type": "string" } }, { "name": "page_no", "in": "query", "required": false, "description": "Filter subtasks by page number or page range", "schema": { "type": "string", "example": "12-15" } }, { "name": "assigned_to", "in": "query", "required": false, "description": "Filter by assigned user UUID, 'unassigned', 'null', or 'all'", "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "required": false, "description": "Alternative alias to filter by assigned user UUID", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter subtasks by status", "schema": { "type": "string", "enum": [ "pending", "in_progress", "completed" ] } }, { "name": "search", "in": "query", "required": false, "description": "Search keyword in subtask title or description", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Number of items per page (optional pagination)", "schema": { "type": "integer", "example": 15 } } ], "responses": { "200": { "description": "Subtasks retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Subtasks retrieved successfully." }, "total": { "type": "integer", "example": 25 }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "task_id": { "type": "string", "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "title": { "type": "string", "example": "Audio Sync & Sound Design" }, "description": { "type": "string", "nullable": true, "example": "Master the raw audio track" }, "assigned_to": { "type": "string", "format": "uuid", "nullable": true, "example": "9a1b2c3d-0000-0000-0000-000000000002" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed" ], "example": "pending" }, "start_date": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-10-06 10:00:00" }, "due_date": { "nullable": true, "example": "2026-10-15 17:00:00" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "task": { "type": "object", "nullable": true, "description": "Parent task summary", "properties": { "id": { "type": "string", "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "title": { "type": "string", "example": "Physics Lecture Video Editing" }, "status": { "type": "string", "example": "in_progress" }, "priority": { "type": "string", "example": "urgent" } } }, "assigned_to_user": { "type": "object", "nullable": true, "description": "Assigned user object (null if unassigned)", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@eveapplication.com" } } } } } } } } } } } } } }, "/api/tasks/{taskId}/subtasks": { "post": { "tags": [ "Task Subtasks" ], "summary": "Create subtask(s) for a task", "description": "Create single or multiple subtasks for a task. Supports stringified JSON array of UUIDs (e.g. '[\"uuid1\",\"uuid2\"]'), native array of UUIDs, or single UUID for assigned_to. Also supports due_date as JSON object `{\"from\": \"YYYY-MM-DD\", \"to\": \"YYYY-MM-DD\"}`, natural date ranges (e.g. '2nd july to 4thjuy'), or datetime strings ('2026-10-15 17:00:00'). All insertions are executed inside an atomic database transaction.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subtasks": { "type": "array", "description": "Array of subtasks to create in a batch", "items": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "example": "Audio Sync & Sound Design" }, "description": { "type": "string", "nullable": true, "example": "Sync audio tracks with video timeline and balance audio levels." }, "assigned_to": { "description": "User UUID, stringified array of UUIDs, or array of UUIDs", "example": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed" ], "default": "pending" }, "due_date": { "type": "object", "description": "JSON object with from/to dates, or date range string", "properties": { "from": { "type": "string", "example": "2026-10-15 10:00:00" }, "to": { "type": "string", "example": "2026-10-29 18:00:00" } } }, "page_no": { "type": "string", "nullable": true, "example": "12-15", "description": "Page number or page range associated with this subtask" } } } }, "title": { "type": "string", "description": "For single subtask creation payload", "example": "Audio Sync & Sound Design" }, "description": { "type": "string", "nullable": true, "example": "Sync audio tracks with video timeline and balance audio levels." }, "assigned_to": { "description": "User UUID, stringified array of UUIDs, or array of UUIDs", "example": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed" ], "default": "pending" }, "due_date": { "type": "object", "properties": { "from": { "type": "string", "example": "2026-10-15 10:00:00" }, "to": { "type": "string", "example": "2026-10-29 18:00:00" } } }, "page_no": { "type": "string", "nullable": true, "example": "12-15", "description": "Page number or page range associated with this subtask (when submitting single subtask)" } } }, "example": { "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "subtasks": [ { "title": "Audio Sync & Sound Design", "description": "Audio Sync & Sound Design", "department_id": "3fa85f64-5717-4562-b3fc-2c963f66afa612", "assigned_to": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "status": "pending", "page_no": { "type": "string", "nullable": true, "example": "12-15", "description": "Page number or page range associated with this subtask (when submitting single subtask)" }, "due_date": { "from": "2026-10-15 10:00:00", "to": "2026-10-29 18:00:00" } }, { "title": "Color Grading", "description": "Audio Sync & Sound Design", "department_id": "3fa85f64-5717-4562-b3fc-2c963f66afa612", "assigned_to": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "status": "pending", "page_no": { "type": "string", "nullable": true, "example": "12-15", "description": "Page number or page range associated with this subtask (when submitting single subtask)" }, "due_date": { "from": "2026-10-15 10:00:00", "to": "2026-10-15 18:00:00" } } ] }, "examples": { "jsonDueDateObject": { "summary": "Subtasks with JSON due_date {from, to}", "value": { "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "subtasks": [ { "title": "Audio Sync & Sound Design", "description": "Audio Sync & Sound Design", "department_id": "3fa85f64-5717-4562-b3fc-2c963f66afa612", "assigned_to": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "status": "pending", "page_no": { "type": "string", "nullable": true, "example": "12-15", "description": "Page number or page range associated with this subtask (when submitting single subtask)" }, "due_date": { "from": "2026-10-15 10:00:00", "to": "2026-10-29 18:00:00" } }, { "title": "Color Grading", "description": "Audio Sync & Sound Design", "department_id": "3fa85f64-5717-4562-b3fc-2c963f66afa612", "assigned_to": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "status": "pending", "page_no": { "type": "string", "nullable": true, "example": "12-15", "description": "Page number or page range associated with this subtask (when submitting single subtask)" }, "due_date": { "from": "2026-10-15 10:00:00", "to": "2026-10-15 18:00:00" } } ] } }, "dateRangeString": { "summary": "Subtasks with natural date range string", "value": { "subtasks": [ { "title": "Audio Sync & Sound Design", "description": "Audio Sync & Sound Design", "department_id": "3fa85f64-5717-4562-b3fc-2c963f66afa612", "assigned_to": "[\"3fa85f64-5717-4562-b3fc-2c963f66afa6\"]", "status": "pending", "page_no": { "type": "string", "nullable": true, "example": "12-15", "description": "Page number or page range associated with this subtask (when submitting single subtask)" }, "due_date": "2nd july to 4thjuy" }, { "title": "Color Grading", "description": "Audio Sync & Sound Design", "department_id": "3fa85f64-5717-4562-b3fc-2c963f66afa612", "assigned_to": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "pending", "page_no": { "type": "string", "nullable": true, "example": "12-15", "description": "Page number or page range associated with this subtask (when submitting single subtask)" }, "due_date": "2026-10-15 17:00:00" } ] } } } } } }, "responses": { "201": { "description": "Subtask(s) created successfully" }, "422": { "description": "Validation error (invalid date format, assignee not found, or missing title)" } } }, "get": { "tags": [ "Task Subtasks" ], "summary": "List subtasks for a specific task", "description": "Retrieve all subtasks belonging to the specified task with optional filters: page_no, assigned_to, department_id, status, search, and pagination.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "page_no", "in": "query", "required": false, "description": "Filter subtasks by page number or range", "schema": { "type": "string", "example": "12-15" } }, { "name": "assigned_to", "in": "query", "required": false, "description": "Filter by assigned user UUID, \"unassigned\", or \"all\"", "schema": { "type": "string" } }, { "name": "department_id", "in": "query", "required": false, "description": "Filter by department UUID, \"unassigned\", or \"all\"", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status (pending, in_progress, completed, revision, approved)", "schema": { "type": "string", "enum": [ "pending", "in_progress", "completed", "revision", "approved" ] } }, { "name": "search", "in": "query", "required": false, "description": "Search keyword in title, description, or page_no", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Number of items per page", "schema": { "type": "integer", "example": 15 } } ], "responses": { "200": { "description": "Subtasks retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Subtasks retrieved successfully." }, "total": { "type": "integer", "example": 4 }, "data": { "type": "array", "items": { "": "#/components/schemas/TaskSubtask" } } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Task not found" } } } }, "/api/tasks/{taskId}/subtasks/{subtaskId}": { "put": { "tags": [ "Task Subtasks" ], "summary": "Update a subtask", "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "subtaskId", "in": "path", "required": true, "description": "Subtask UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string", "nullable": true, "example": "Updated subtask description and instructions." }, "assigned_to": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "revision", "approved" ] }, "due_date": { "type": "string", "format": "date-time", "nullable": true }, "revision_date": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-10-25 18:00:00" }, "revision_notes": { "type": "string", "nullable": true, "example": "Please color grade the final shot" }, "extension_count": { "type": "integer", "example": 1 }, "action": { "type": "string", "enum": [ "revision", "approve" ] }, "page_no": { "type": "string", "nullable": true, "example": "12-15", "description": "Page number or page range" } } } } } }, "responses": { "200": { "description": "Subtask updated successfully" } } }, "patch": { "tags": [ "Task Subtasks" ], "summary": "Quick update, revision request, or approve a subtask", "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "subtaskId", "in": "path", "required": true, "description": "Subtask UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision_date": { "type": "string", "format": "date-time" }, "revision_notes": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "revision", "approved" ] } } } } } }, "responses": { "200": { "description": "Subtask updated successfully" } } }, "delete": { "tags": [ "Task Subtasks" ], "summary": "Delete a subtask", "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "subtaskId", "in": "path", "required": true, "description": "Subtask UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Subtask deleted successfully" } } }, "get": { "tags": [ "Task Subtasks" ], "summary": "Get single subtask details", "description": "Retrieve details of a specific subtask under a task.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Parent Task UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "subtaskId", "in": "path", "required": true, "description": "Subtask UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Subtask retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Subtask retrieved successfully." }, "data": { "": "#/components/schemas/TaskSubtask" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Subtask not found" } } } }, "/api/tasks/{taskId}/subtasks/{subtaskId}/toggle": { "patch": { "tags": [ "Task Subtasks" ], "summary": "Toggle subtask completion status", "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "subtaskId", "in": "path", "required": true, "description": "Subtask UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Subtask completion status toggled successfully" } } } }, "/api/tasks/{taskId}/comments": { "get": { "tags": [ "Task Comments" ], "summary": "List comments and audit timeline for task", "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of comments" } } }, "post": { "tags": [ "Task Comments" ], "summary": "Post comment to task", "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "string", "example": "Please revise the audio mixing." }, "type": { "type": "string", "enum": [ "comment", "system", "status_change" ], "default": "comment" } } } } } }, "responses": { "201": { "description": "Comment posted" } } } }, "/api/tasks/{taskId}/comments/{commentId}": { "delete": { "tags": [ "Task Comments" ], "summary": "Delete comment from task", "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "Comment UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment deleted successfully" } } } }, "/api/get-departments": { "get": { "tags": [ "Departments", "Authentication" ], "summary": "Get all departments (Public / No JWT required)", "description": "Public open endpoint to get all departments without requiring JWT authentication. Ideal for public user registration forms, onboarding, and dropdown selectors.", "security": [], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search departments by name or code" }, { "name": "parent_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by parent department UUID (or 'null' / 'none' for top-level only)" }, { "name": "parents_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter only parent/root departments" }, { "name": "tree", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Set to true to return hierarchical tree structure with nested sub-departments" } ], "responses": { "200": { "description": "Departments retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Departments retrieved successfully." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "parent_id": { "type": "string", "nullable": true }, "name": { "type": "string", "example": "Bengali Editorial" }, "code": { "type": "string", "example": "BNG-ED" }, "description": { "type": "string", "nullable": true } } } }, "total": { "type": "integer", "example": 5 } } } } } } } } }, "/api/departments": { "get": { "tags": [ "Departments" ], "summary": "List all departments with task and user counts", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of departments" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to view departments" } }, "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search departments by name, code or description" }, { "name": "parent_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by parent department UUID (or \"none\" / \"null\" for top-level only)" }, { "name": "parents_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter only parent/root departments" }, { "name": "sub_departments_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter only sub-departments" }, { "name": "tree", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Retrieve hierarchical tree with nested sub-departments" }, { "name": "parent_wise", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Order departments parent-wise with sub-departments grouped under parents" } ] }, "post": { "tags": [ "Departments" ], "summary": "Create department", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "code", "description" ], "properties": { "name": { "type": "string", "example": "Quality Assurance" }, "code": { "type": "string", "example": "QA" }, "description": { "type": "string", "example": "Quality Assurance and testing department" }, "lead_id": { "type": "string", "format": "uuid", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional UUID of the parent department. If provided, creates a sub-department under that parent.", "example": "aba4f964-aac0-4229-8d51-484c67fce326" } } } } } }, "responses": { "201": { "description": "Department created successfully" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to create departments" }, "422": { "description": "Unprocessable Content - Validation failed for required parameters" } } } }, "/api/departments/parent/{parentId}": { "get": { "tags": [ "Departments" ], "summary": "Get sub-departments by parent ID (parent-wise)", "description": "Retrieves sub-departments belonging to a specified parent department ID. Pass \"root\", \"none\", or \"null\" to retrieve top-level parent departments.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string", "example": "aba4f964-aac0-4229-8d51-484c67fce326" }, "description": "UUID of the parent department, or \"root\" / \"none\" / \"null\" for top-level departments" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search sub-departments by name, code or description" } ], "responses": { "200": { "description": "Sub-departments retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Sub-departments of parent retrieved successfully." }, "parent_department": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": "string" }, "lead_id": { "type": "string", "format": "uuid", "nullable": true } } }, "data": { "type": "array", "items": { "": "#/components/schemas/Department" } }, "sub_departments": { "type": "array", "items": { "": "#/components/schemas/Department" } }, "total": { "type": "integer", "example": 2 } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to view departments" }, "404": { "description": "Parent department not found" } } } }, "/api/departments/{id}": { "get": { "tags": [ "Departments" ], "summary": "Get department details", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "aba4f964-aac0-4229-8d51-484c67fce326" } } ], "responses": { "200": { "description": "Department details" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to view departments" } } }, "put": { "tags": [ "Departments" ], "summary": "Update department", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "aba4f964-aac0-4229-8d51-484c67fce326" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "description": { "type": "string" }, "lead_id": { "type": "string", "format": "uuid", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional UUID of the parent department (cannot be itself or one of its descendants).", "example": "aba4f964-aac0-4229-8d51-484c67fce326" } } } } } }, "responses": { "200": { "description": "Department updated successfully" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to edit departments" }, "422": { "description": "Unprocessable Content - Validation failed" } } }, "delete": { "tags": [ "Departments" ], "summary": "Delete department", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "aba4f964-aac0-4229-8d51-484c67fce326" } } ], "responses": { "200": { "description": "Department deleted successfully" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to delete departments" } } } }, "/api/classes": { "get": { "tags": [ "Classes & Subjects" ], "summary": "List classes", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of classes" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to view classes" } } }, "post": { "tags": [ "Classes & Subjects" ], "summary": "Create class", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Class 10 CBSE" }, "description": { "type": "string", "example": "Secondary education curriculum" }, "is_active": { "type": "boolean", "example": true } } } } } }, "responses": { "201": { "description": "Class created successfully" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to create classes" }, "422": { "description": "Unprocessable Content - Validation failed" } } } }, "/api/classes/{id}": { "get": { "tags": [ "Classes & Subjects" ], "summary": "Get class details", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3ce7f187-df11-4980-9d97-fedad74903f2" } } ], "responses": { "200": { "description": "Class details" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to view classes" } } }, "put": { "tags": [ "Classes & Subjects" ], "summary": "Update class", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3ce7f187-df11-4980-9d97-fedad74903f2" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Class 10 CBSE - Updated" }, "description": { "type": "string", "example": "Updated curriculum description" }, "is_active": { "type": "boolean", "example": true } } } } } }, "responses": { "200": { "description": "Class updated successfully" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to edit classes" }, "422": { "description": "Unprocessable Content - Validation failed" } } }, "delete": { "tags": [ "Classes & Subjects" ], "summary": "Delete class", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3ce7f187-df11-4980-9d97-fedad74903f2" } } ], "responses": { "200": { "description": "Class deleted successfully" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to delete classes" } } } }, "/api/subjects": { "get": { "tags": [ "Classes & Subjects" ], "summary": "List subjects", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "class_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by class UUID" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by subject name or description" }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by active status" } ], "responses": { "200": { "description": "List of subjects retrieved successfully" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to view subjects" } } }, "post": { "tags": [ "Classes & Subjects" ], "summary": "Create subject", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Physics" }, "description": { "type": "string", "example": "Higher secondary physics curriculum" }, "is_active": { "type": "boolean", "example": true }, "class_id": { "type": "string", "format": "uuid", "example": "3ce7f187-df11-4980-9d97-fedad74903f2" }, "color_code": { "type": "string", "example": "#2563eb" }, "serial_no": { "type": "integer", "example": 1 } } } } } }, "responses": { "201": { "description": "Subject created successfully" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to create subjects" }, "422": { "description": "Unprocessable Content - Validation failed" } } } }, "/api/subjects/{id}": { "get": { "tags": [ "Classes & Subjects" ], "summary": "Get subject details", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3ce7f187-df11-4980-9d97-fedad74903f2" } } ], "responses": { "200": { "description": "Subject details" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to view subjects" }, "404": { "description": "Subject not found or already deleted" } } }, "put": { "tags": [ "Classes & Subjects" ], "summary": "Update subject", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3ce7f187-df11-4980-9d97-fedad74903f2" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Physics - Advanced" }, "description": { "type": "string", "example": "Updated physics syllabus" }, "is_active": { "type": "boolean", "example": true }, "class_id": { "type": "string", "format": "uuid", "example": "3ce7f187-df11-4980-9d97-fedad74903f2" }, "color_code": { "type": "string", "example": "#1d4ed8" }, "serial_no": { "type": "integer", "example": 2 } } } } } }, "responses": { "200": { "description": "Subject updated successfully" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to edit subjects" }, "404": { "description": "Subject not found or already deleted" }, "422": { "description": "Unprocessable Content - Validation failed" } } }, "delete": { "tags": [ "Classes & Subjects" ], "summary": "Delete subject", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3ce7f187-df11-4980-9d97-fedad74903f2" } } ], "responses": { "200": { "description": "Subject deleted successfully" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to delete subjects" }, "404": { "description": "Subject not found or already deleted" } } } }, "/api/roles": { "get": { "tags": [ "Access Control" ], "summary": "List roles and permission counts", "description": "Retrieve all roles with assigned permission names, permission count, and active status. Supports filtering by active status and search.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "is_active", "in": "query", "required": false, "description": "Filter by active status (true/false or 1/0)", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "required": false, "description": "Filter roles by partial name match", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Roles list" } } }, "post": { "tags": [ "Access Control" ], "summary": "Create role", "description": "Create a new role with optional initial permissions and active status.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "content_auditor" }, "guard_name": { "type": "string", "example": "web" }, "is_active": { "type": "boolean", "example": true }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "task-view", "task-edit" ] } } } } } }, "responses": { "201": { "description": "Role created" }, "422": { "description": "Validation error" } } } }, "/api/roles/{id}": { "get": { "tags": [ "Access Control" ], "summary": "Get role details", "description": "Retrieve complete role information by role ID (integer) or role name (e.g. 'superadmin', 'admin', 'teacher'), including all assigned permissions.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Role ID (e.g. 1) or Role Name (e.g. 'superadmin', 'admin', 'teacher')", "schema": { "type": "string", "example": "superadmin" } } ], "responses": { "200": { "description": "Role retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Role retrieved successfully." }, "data": { "type": "object", "properties": { "name": { "type": "string", "example": "superadmin" }, "is_active": { "type": "boolean", "example": true }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "dashboard-view", "task-view", "task-create" ] } } } } } } } }, "404": { "description": "Role not found" } } }, "put": { "tags": [ "Access Control" ], "summary": "Update role", "description": "Update role name, active status, and synced permissions. Superadmin role cannot be deactivated.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Role ID (e.g. 2) or Role Name (e.g. 'admin', 'teacher')", "schema": { "type": "string", "example": "admin" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "lead_auditor" }, "is_active": { "type": "boolean", "example": true }, "permissions": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Role updated successfully" }, "422": { "description": "Validation error or forbidden action (e.g. deactivating superadmin)" } } }, "delete": { "tags": [ "Access Control" ], "summary": "Delete role", "description": "Permanently delete role. Superadmin role cannot be deleted.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Role ID or Role Name", "schema": { "type": "string", "example": "content_auditor" } } ], "responses": { "200": { "description": "Role deleted successfully" }, "422": { "description": "Forbidden action (e.g. deleting superadmin)" } } } }, "/api/roles/{id}/toggle-status": { "patch": { "tags": [ "Access Control" ], "summary": "Toggle role active status", "description": "Toggles the `is_active` flag of a role (active ↔ inactive). Optionally accepts an explicit `{\"is_active\": boolean}` in body. Superadmin role cannot be deactivated.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Role ID or Role Name", "schema": { "type": "string", "example": "teacher" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "is_active": { "type": "boolean", "example": false } } } } } }, "responses": { "200": { "description": "Status toggled successfully" }, "404": { "description": "Role not found" }, "422": { "description": "Cannot deactivate superadmin role" } } } }, "/api/roles/{id}/permissions": { "get": { "tags": [ "Access Control" ], "summary": "Get permissions for a specific role", "description": "Returns all permissions assigned to the role (by numeric ID or name), grouped by category/module.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Role ID (e.g. 2) or Role Name (e.g. 'admin', 'teacher')", "schema": { "type": "string", "example": "admin" } } ], "responses": { "200": { "description": "Role permissions retrieved successfully" }, "404": { "description": "Role not found" } } }, "patch": { "tags": [ "Access Control" ], "summary": "Sync or assign permissions to a specific role", "description": "Assign permissions to a role by ID or Name. Accepts permission names (e.g. 'banner-view') or IDs (e.g. 42). Supports mode: 'sync' (default), 'add', or 'revoke'.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Role ID (e.g. 2) or Role Name (e.g. 'admin', 'teacher')", "schema": { "type": "string", "example": "teacher" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "description": "List of permission names or numeric IDs", "items": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "example": [ "task-view", "banner-view", "banner-create" ] }, "mode": { "type": "string", "enum": [ "sync", "add", "revoke" ], "default": "sync", "description": "sync (replaces all), add (appends permissions), or revoke (removes listed permissions)" } } } } } }, "responses": { "200": { "description": "Permissions synced successfully" }, "404": { "description": "Role not found" } } }, "delete": { "tags": [ "Access Control" ], "summary": "Revoke permissions from a role", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Role ID or Role Name", "schema": { "type": "string", "example": "teacher" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "banner-create" ] } } } } } }, "responses": { "200": { "description": "Permission(s) revoked successfully" } } } }, "/api/permissions": { "get": { "tags": [ "Access Control" ], "summary": "List system permissions", "responses": { "200": { "description": "Permissions list" } } } }, "/api/settings": { "get": { "tags": [ "System Settings" ], "summary": "Get system settings key-value dictionary", "responses": { "200": { "description": "Settings dictionary" } } }, "post": { "tags": [ "System Settings" ], "summary": "Update system settings key-values", "responses": { "200": { "description": "Settings updated" } } } }, "/api/audit-logs": { "get": { "tags": [ "Audit Logs" ], "summary": "Paginated audit trail logs", "responses": { "200": { "description": "Audit logs" } } } }, "/api/dashboard/stats": { "get": { "tags": [ "Dashboard & Reports" ], "summary": "Overview metrics & statistics", "responses": { "200": { "description": "Dashboard statistics" } } } }, "/api/reports/analytics": { "get": { "tags": [ "Dashboard & Reports" ], "summary": "Analytical reports grouped by status & priority", "responses": { "200": { "description": "Analytics report" } } } }, "/api/menus": { "get": { "tags": [ "Menus" ], "summary": "List navigation menus and sub-menus", "responses": { "200": { "description": "Menus list" } } } }, "/api/notifications": { "get": { "tags": [ "Notifications" ], "summary": "List notifications for authenticated user", "responses": { "200": { "description": "Notifications list" } } } }, "/api/reports/summary": { "get": { "tags": [ "Reports & Analytics" ], "summary": "Executive Reporting Summary & KPIs", "description": "High-level executive metrics including total tasks, completed on-time vs extended (1x, 2x+), pending, in-progress, revision, overdue counters, and overall completion rate.", "parameters": [ { "name": "department_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by department ID" }, { "name": "assigned_to", "in": "query", "schema": { "type": "string" }, "description": "Filter by assignee UUID" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter by task status" }, { "name": "priority", "in": "query", "schema": { "type": "string" }, "description": "Filter by task priority" }, { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Filter created from date (YYYY-MM-DD)" }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Filter created to date (YYYY-MM-DD)" }, { "name": "month", "in": "query", "schema": { "type": "integer" }, "description": "Month number (1-12)" }, { "name": "year", "in": "query", "schema": { "type": "integer" }, "description": "Calendar year" }, { "name": "week", "in": "query", "schema": { "type": "string" }, "description": "Week format (e.g. 2026-W39)" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search keyword in task title or description" }, { "name": "overdue_only", "in": "query", "schema": { "type": "boolean" }, "description": "Filter overdue tasks only" } ], "responses": { "200": { "description": "Executive summary report retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportSummary" } } } } } } }, "/api/reports/department-wise": { "get": { "tags": [ "Reports & Analytics" ], "summary": "Department-Wise Task Performance & Workload Report", "description": "Aggregates performance metrics, on-time and extended completions, active workload, overdue counts, and completion rate for each department.", "parameters": [ { "name": "department_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by specific department ID" }, { "name": "month", "in": "query", "schema": { "type": "integer" }, "description": "Filter by month (1-12)" }, { "name": "year", "in": "query", "schema": { "type": "integer" }, "description": "Filter by calendar year" }, { "name": "week", "in": "query", "schema": { "type": "string" }, "description": "Filter by week key (e.g. 2026-W39)" }, { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Start date range" }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "End date range" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search keyword in task title or description" }, { "name": "include_tasks", "in": "query", "schema": { "type": "boolean" }, "description": "Include recent task items for each department" } ], "responses": { "200": { "description": "Department-wise report retrieved successfully" } } } }, "/api/reports/task-wise": { "get": { "tags": [ "Reports & Analytics" ], "summary": "Task-Wise Detailed Status & Lifecycle Report", "description": "Comprehensive breakdown of tasks with rich metadata, formatted deadlines, assignee details, subtask progress, and extension tracking.", "parameters": [ { "name": "department_id", "in": "query", "schema": { "type": "integer" } }, { "name": "assigned_to", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "priority", "in": "query", "schema": { "type": "string" } }, { "name": "month", "in": "query", "schema": { "type": "integer" } }, { "name": "year", "in": "query", "schema": { "type": "integer" } }, { "name": "week", "in": "query", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "overdue_only", "in": "query", "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Task-wise report retrieved successfully" } } } }, "/api/reports/month-wise": { "get": { "tags": [ "Reports & Analytics" ], "summary": "Month-Wise Annual Performance & Productivity Report", "description": "Month-by-month breakdown across all 12 months for the specified year.", "parameters": [ { "name": "year", "in": "query", "schema": { "type": "integer", "default": 2026 } }, { "name": "department_id", "in": "query", "schema": { "type": "integer" } }, { "name": "assigned_to", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Month-wise report retrieved successfully" } } } }, "/api/reports/weekly-wise": { "get": { "tags": [ "Reports & Analytics" ], "summary": "Weekly-Wise Chronological Progress & Trend Report", "description": "Weekly breakdown across chronological weekly intervals with ISO week numbering.", "parameters": [ { "name": "weeks_count", "in": "query", "schema": { "type": "integer", "default": 8 } }, { "name": "department_id", "in": "query", "schema": { "type": "integer" } }, { "name": "assigned_to", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Weekly-wise report retrieved successfully" } } } }, "/api/reports/employee-wise": { "get": { "tags": [ "Reports & Analytics" ], "summary": "Employee-Wise Productivity & Task Distribution Report", "description": "Per-employee task metrics across all active employees or filtered by department/role.", "parameters": [ { "name": "department_id", "in": "query", "schema": { "type": "integer" } }, { "name": "role", "in": "query", "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Employee-wise report retrieved successfully" } } } }, "/api/reports/employee-wise/{userId}": { "get": { "tags": [ "Reports & Analytics" ], "summary": "Single Employee Detailed Productivity & Recent Tasks Report", "description": "In-depth reporting for a specific employee including full KPI breakdown and recent tasks.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Individual employee report retrieved successfully" }, "404": { "description": "Requested employee not found" } } } }, "/api/workflows": { "get": { "tags": [ "Workflows Master" ], "summary": "List all workflows", "description": "Retrieve all workflow pipelines with optional filtering by department, active status, and search. Accessible by admin, superadmin, and team_lead roles.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by workflow name, code or description" }, { "name": "department_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by department UUID (or \"all\")" }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by active status" } ], "responses": { "200": { "description": "Workflows retrieved successfully" }, "401": { "description": "Unauthorized - Invalid or missing token" }, "403": { "description": "Forbidden - Insufficient permission" } } }, "post": { "tags": [ "Workflows Master" ], "summary": "Create a new workflow", "description": "Create a new workflow pipeline with custom stages. Requires admin or superadmin role.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "code" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "Video Production Pipeline", "description": "Unique workflow name" }, "code": { "type": "string", "maxLength": 50, "example": "VID_PIPE", "description": "Unique short code (auto-uppercased)" }, "description": { "type": "string", "nullable": true, "example": "End-to-end video production stages" }, "department_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Linked department UUID" }, "stages": { "type": "array", "items": { "type": "string" }, "example": [ "Initiated", "In Progress", "Review", "Completed" ], "description": "Ordered stage names (defaults applied if empty)" }, "is_active": { "type": "boolean", "default": true }, "sort_order": { "type": "integer", "default": 0 } } } } } }, "responses": { "201": { "description": "Workflow created successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - admin or superadmin only" }, "422": { "description": "Validation failed - duplicate name/code or missing required fields" } } } }, "/api/workflows/{id}": { "get": { "tags": [ "Workflows Master" ], "summary": "Get a single workflow", "description": "Retrieve full details of a workflow by its UUID including department, creator, and task count.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workflow UUID" } ], "responses": { "200": { "description": "Workflow retrieved successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Workflow not found" } } }, "put": { "tags": [ "Workflows Master" ], "summary": "Update a workflow", "description": "Update an existing workflow. Supports partial updates. Requires admin or superadmin role.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workflow UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "example": "Updated Pipeline Name" }, "code": { "type": "string", "maxLength": 50, "example": "UPD_PIPE" }, "description": { "type": "string", "nullable": true }, "department_id": { "type": "string", "format": "uuid", "nullable": true }, "stages": { "type": "array", "items": { "type": "string" }, "example": [ "Draft", "Review", "Approved", "Published" ] }, "is_active": { "type": "boolean" }, "sort_order": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Workflow updated successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Workflow not found" }, "422": { "description": "Validation failed" } } }, "delete": { "tags": [ "Workflows Master" ], "summary": "Delete a workflow", "description": "Permanently delete a workflow by UUID. Requires admin or superadmin role.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workflow UUID" } ], "responses": { "200": { "description": "Workflow deleted successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Workflow not found" } } } }, "/api/workflows/{id}/stages": { "get": { "tags": [ "Workflows Master" ], "summary": "Get workflow stages", "description": "Returns the ordered stage list for a workflow. Uses defaults if no custom stages are defined.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workflow UUID" } ], "responses": { "200": { "description": "Stages list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "stages": { "type": "array", "items": { "type": "string" }, "example": [ "Initiated", "In Progress", "Review", "Completed" ] } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Workflow not found" } } } }, "/api/users": { "get": { "tags": [ "Users Management" ], "summary": "Paginated list of users with search and department filtering", "description": "Returns paginated user list with full relations (department, roles, enrolledClass).", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Search by name, email, or mobile number", "schema": { "type": "string" } }, { "name": "department_id", "in": "query", "required": false, "description": "Filter by department UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "Users retrieved successfully" }, "401": { "description": "Unauthenticated" } } } }, "/api/users/list": { "get": { "tags": [ "Users Management" ], "summary": "Lightweight user list for dropdowns & selects", "description": "Returns a non-paginated list of users with minimal fields (id, name, email, mobile_number, is_active, department, roles). Defaults to active users only. Intended for populating dropdowns, assign-to selects, and similar UI components.\n\n**Accessible by:** admin, superadmin, team_lead (read).", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Filter by name or email (partial match)", "schema": { "type": "string", "example": "john" } }, { "name": "department_id", "in": "query", "required": false, "description": "Filter by department UUID", "schema": { "type": "string", "format": "uuid", "example": "aba4f964-aac0-4229-8d51-484c67fce326" } }, { "name": "is_active", "in": "query", "required": false, "description": "Filter by active status. Defaults to `1` (active only) when omitted.", "schema": { "type": "integer", "enum": [ 0, 1 ], "example": 1 } }, { "name": "role", "in": "query", "required": false, "description": "Filter by role name (e.g. `user`, `admin`, `team_lead`)", "schema": { "type": "string", "example": "user" } } ], "responses": { "200": { "description": "User list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User list retrieved successfully." }, "total": { "type": "integer", "example": 12 }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "mobile_number": { "type": "string", "nullable": true, "example": "+919876543210" }, "is_active": { "type": "boolean", "example": true }, "department": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "HR" } } }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "user" ] }, "departments": { "type": "array", "description": "All departments attached to this user", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9d18fa71-e0c2-4912-92ab-624e73bdf01a" }, "name": { "type": "string", "example": "Animation Department" }, "code": { "type": "string", "example": "ANIM" } } } } } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission to list users" } } } }, "/api/user/me": { "get": { "tags": [ "Users Management" ], "summary": "Get authenticated user profile (with enrolled class)", "description": "Returns the currently authenticated user's profile including their enrolled class details.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Authenticated user profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "mobile_number": { "type": "string", "nullable": true, "example": "+919876543210" }, "is_active": { "type": "boolean", "example": true }, "department_id": { "type": "string", "format": "uuid", "nullable": true }, "department": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "HR" } } }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "user" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication token" } } } }, "/api/user/update-class": { "put": { "tags": [ "Users Management" ], "summary": "Update authenticated user's enrolled class", "description": "Updates the authenticated user's enrolled class. Pass `null` or omit `class_id` to un-enrol.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "class_id": { "type": "string", "format": "uuid", "nullable": true, "example": "b1c2d3e4-0000-0000-0000-000000000001", "description": "UUID of an active class, or null to un-enrol" } } } } } }, "responses": { "200": { "description": "Class updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "mobile_number": { "type": "string", "nullable": true, "example": "+919876543210" }, "is_active": { "type": "boolean", "example": true }, "department_id": { "type": "string", "format": "uuid", "nullable": true }, "department": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "HR" } } }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "user" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "422": { "description": "Unprocessable Content - Validation failed" } } } }, "/api/users/{id}": { "get": { "tags": [ "Users Management" ], "summary": "Get a single user", "description": "Fetch full details of a user by their UUID. Admin/superadmin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User UUID", "schema": { "type": "string", "format": "uuid", "example": "9a1b2c3d-0000-0000-0000-000000000001" } } ], "responses": { "200": { "description": "User retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "mobile_number": { "type": "string", "nullable": true, "example": "+919876543210" }, "is_active": { "type": "boolean", "example": true }, "department_id": { "type": "string", "format": "uuid", "nullable": true }, "department": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "HR" } } }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "user" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "department_ids": { "type": "array", "description": "Array of all department UUIDs attached to this user", "items": { "type": "string", "format": "uuid" }, "example": [ "9d18fa71-e0c2-4912-92ab-624e73bdf01a", "9d18fa71-e0c2-4912-92ab-624e73bdf02b" ] }, "departments": { "type": "array", "description": "All departments attached to this user via user_resources", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9d18fa71-e0c2-4912-92ab-624e73bdf01a" }, "name": { "type": "string", "example": "Animation Department" }, "code": { "type": "string", "example": "ANIM" } } } } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission" }, "404": { "description": "User not found" } } }, "patch": { "tags": [ "Users Management" ], "summary": "Update a user", "description": "Update user details. All fields are optional (partial update supported). Admin/superadmin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User UUID", "schema": { "type": "string", "format": "uuid", "example": "9a1b2c3d-0000-0000-0000-000000000001" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Jane Smith" }, "email": { "type": "string", "format": "email", "example": "jane@example.com" }, "mobile_number": { "type": "string", "nullable": true, "example": "+919876543210" }, "password": { "type": "string", "format": "password", "nullable": true, "example": "newpassword", "minLength": 6 }, "department_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Single department UUID (legacy/single department assignment; attaches department)." }, "class_id": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of the enrolled class (or null to unenroll)", "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "subject_id": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of the enrolled subject (or null to unenroll)", "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "admin" ] }, "department_ids": { "type": "array", "nullable": true, "description": "Array of department UUIDs to assign multiple departments to the user (syncs all). Pass [] to remove all departments.", "items": { "type": "string", "format": "uuid" }, "example": [ "9d18fa71-e0c2-4912-92ab-624e73bdf01a", "9d18fa71-e0c2-4912-92ab-624e73bdf02b" ] } } } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "mobile_number": { "type": "string", "nullable": true, "example": "+919876543210" }, "is_active": { "type": "boolean", "example": true }, "department_id": { "type": "string", "format": "uuid", "nullable": true }, "class_id": { "type": "string", "format": "uuid", "nullable": true, "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "subject_id": { "type": "string", "format": "uuid", "nullable": true, "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "department": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "HR" } } }, "enrolled_class": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Class X" }, "is_active": { "type": "boolean", "example": true } } }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "user" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "department_ids": { "type": "array", "description": "Array of all department UUIDs attached to this user", "items": { "type": "string", "format": "uuid" }, "example": [ "9d18fa71-e0c2-4912-92ab-624e73bdf01a", "9d18fa71-e0c2-4912-92ab-624e73bdf02b" ] }, "departments": { "type": "array", "description": "All departments attached to this user via user_resources", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9d18fa71-e0c2-4912-92ab-624e73bdf01a" }, "name": { "type": "string", "example": "Animation Department" }, "code": { "type": "string", "example": "ANIM" } } } } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission" }, "404": { "description": "User not found" }, "422": { "description": "Unprocessable Content - Validation failed" } } }, "delete": { "tags": [ "Users Management" ], "summary": "Delete a user", "description": "Permanently deletes the user account. Admin/superadmin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User UUID", "schema": { "type": "string", "format": "uuid", "example": "9a1b2c3d-0000-0000-0000-000000000001" } } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User deleted successfully." } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission" }, "404": { "description": "User not found" } } } }, "/api/users/{id}/toggle-status": { "patch": { "tags": [ "Users Management" ], "summary": "Toggle user active status", "description": "Toggles the `is_active` flag of a user (active ↔ inactive). Admin/superadmin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User UUID", "schema": { "type": "string", "format": "uuid", "example": "9a1b2c3d-0000-0000-0000-000000000001" } } ], "responses": { "200": { "description": "Status toggled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User active status toggled." }, "is_active": { "type": "boolean", "example": false } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission" }, "404": { "description": "User not found" } } } }, "/api/users/{id}/roles": { "post": { "tags": [ "Users Management" ], "summary": "Assign / sync roles to a user", "description": "Syncs (replaces) the user's roles with the provided list. Pass an empty array to strip all roles. Admin/superadmin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User UUID", "schema": { "type": "string", "format": "uuid", "example": "9a1b2c3d-0000-0000-0000-000000000001" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "roles" ], "properties": { "roles": { "type": "array", "items": { "type": "string" }, "example": [ "admin", "team_lead" ], "description": "Array of role names to assign (existing roles are replaced)" } } } } } }, "responses": { "200": { "description": "Roles assigned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Roles assigned successfully." }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9a1b2c3d-0000-0000-0000-000000000001" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "mobile_number": { "type": "string", "nullable": true, "example": "+919876543210" }, "is_active": { "type": "boolean", "example": true }, "department_id": { "type": "string", "format": "uuid", "nullable": true }, "department": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "HR" } } }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "user" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Insufficient permission" }, "404": { "description": "User not found" }, "422": { "description": "Unprocessable Content - Validation failed" } } } }, "/api/workflow-stages": { "get": { "tags": [ "Workflow Stages Master" ], "summary": "List all workflow stages", "description": "Retrieve all workflow stages with optional filtering by workflow_id, active status, and search query. Accessible by superadmin, admin, and team_lead.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "workflow_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter stages by parent workflow UUID" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search stages by name, code or description" }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by active status" } ], "responses": { "200": { "description": "Workflow stages retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Workflow stages retrieved successfully." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStage" } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" } } }, "post": { "tags": [ "Workflow Stages Master" ], "summary": "Create a new workflow stage", "description": "Add a new stage/section under a selected workflow master record. Accessible by superadmin and admin.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowStageInput" } } } }, "responses": { "201": { "description": "Workflow stage created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Workflow stage created successfully." }, "data": { "$ref": "#/components/schemas/WorkflowStage" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } } } }, "/api/workflow-stages/reorder": { "post": { "tags": [ "Workflow Stages Master" ], "summary": "Bulk reorder workflow stages", "description": "Reorders the sequence of stages for a workflow based on an ordered array of stage UUIDs. Accessible by superadmin and admin.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "workflow_id", "stage_ids" ], "properties": { "workflow_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "stage_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "example": [ "650e8400-e29b-41d4-a716-446655440001", "650e8400-e29b-41d4-a716-446655440002" ] } } } } } }, "responses": { "200": { "description": "Workflow stages reordered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Workflow stages reordered successfully." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStage" } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } } } }, "/api/workflow-stages/{id}": { "get": { "tags": [ "Workflow Stages Master" ], "summary": "Get a single workflow stage", "description": "Retrieve details of a workflow stage by UUID including parent workflow relation.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workflow Stage UUID" } ], "responses": { "200": { "description": "Workflow stage retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Workflow stage retrieved successfully." }, "data": { "$ref": "#/components/schemas/WorkflowStage" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Workflow stage not found" } } }, "put": { "tags": [ "Workflow Stages Master" ], "summary": "Update a workflow stage", "description": "Update properties (name, code, color, sort order, active status) of an existing workflow stage. Supports partial updates.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workflow Stage UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowStageInput" } } } }, "responses": { "200": { "description": "Workflow stage updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Workflow stage updated successfully." }, "data": { "$ref": "#/components/schemas/WorkflowStage" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Workflow stage not found" }, "422": { "description": "Validation error" } } }, "delete": { "tags": [ "Workflow Stages Master" ], "summary": "Delete a workflow stage", "description": "Permanently delete a workflow stage by UUID. Accessible by superadmin and admin.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workflow Stage UUID" } ], "responses": { "200": { "description": "Workflow stage deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Workflow stage deleted successfully." } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Workflow stage not found" } } } }, "/api/users/{id}/permissions": { "get": { "tags": [ "Users Management" ], "summary": "Get user permissions (name-wise)", "description": "Retrieve a user's permissions by UUID, including all effective permission names, direct permissions, role permissions, and permissions grouped name-wise by module prefix.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "User UUID" } ], "responses": { "200": { "description": "User permissions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User permissions retrieved successfully." }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } } } }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "task-view", "task-create", "department-view" ] }, "direct_permissions": { "type": "array", "items": { "type": "string" } }, "role_permissions": { "type": "array", "items": { "type": "string" } }, "permissions_by_group": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "total_permissions": { "type": "integer", "example": 3 } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "User not found" } } }, "patch": { "tags": [ "Users Management" ], "summary": "Add or sync permissions to a user by permission name", "description": "Assign, append, or sync permissions for a specific user using permission names. Pass either an array of permission names ('permissions') or a single name ('permission'). Optional 'mode' can be 'sync' (default for array), 'add' (append), or 'revoke'.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "User UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "string" }, "description": "Array of valid permission names to assign/sync", "example": [ "task-view", "task-create", "department-view" ] }, "permission": { "type": "string", "description": "Single permission name to add or revoke", "example": "task-view" }, "mode": { "type": "string", "enum": [ "sync", "add", "revoke" ], "description": "Operation mode: sync replaces direct permissions, add appends permissions, revoke removes specified permissions", "default": "sync" } } } } } }, "responses": { "200": { "description": "Permissions updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Permissions synced to user successfully." }, "permissions": { "type": "array", "items": { "type": "string" } }, "direct_permissions": { "type": "array", "items": { "type": "string" } }, "permissions_by_group": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "User not found" }, "422": { "description": "Validation error - Invalid permission names" } } } }, "/api/attach_resources": { "post": { "tags": [ "Users Management", "Resources Management" ], "summary": "Attach resource(s) to a user or target model", "description": "Attaches departments, subjects, or custom resources to a user or model via the polymorphic user_resources table. Accepts user_id, resource_id, department, or subject (supports both single IDs and arrays). Aliases /api/attach_respurces and /api/attach-resources are also available.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "User UUID (sets model_id=user_id and model_type=App\\Models\\User when resource_id/department/subject is provided)", "example": "9a7e6b8c-1234-5678-9abc-def012345678" }, "resource_id": { "type": "string", "format": "uuid", "description": "Target resource UUID or ID", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } }, "responses": { "200": { "description": "Resources attached successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Resources attached successfully." }, "attached_count": { "type": "integer", "example": 1 }, "model_id": { "type": "string", "example": "9a7e6b8c-1234-5678-9abc-def012345678" }, "model_type": { "type": "string", "example": "App\\Models\\User" }, "attached": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "resources_id": { "type": "string" }, "model_id": { "type": "string" }, "model_type": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error - Missing required resource or model identifiers" } } } }, "/api/detach_resources": { "post": { "tags": [ "Users Management", "Resources Management" ], "summary": "Detach resource(s) from a user or target model", "description": "Detaches previously attached resources. Accepts user_id, resource_id, department, or subject.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "resource_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Resources detached successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Resources detached successfully." }, "detached_count": { "type": "integer", "example": 1 } } } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" } } } }, "/api/attached_resources": { "get": { "tags": [ "Users Management", "Resources Management" ], "summary": "List attached resources", "description": "Fetches all attached resources for a given user or model.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "model_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of attached resources", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "count": { "type": "integer", "example": 2 }, "resources": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "Unauthorized" } } } }, "/api/user/{userId}/tasks": { "get": { "tags": [ "Tasks", "Users Management" ], "summary": "Get user tasks and subtasks in one single request", "description": "Returns all parent tasks (with nested subtasks) assigned to the specified user, plus all direct subtasks assigned to the user, user details, and an aggregate status summary in a single payload.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the user", "example": "9d36a992-0bca-4b08-9df2-51a44e548232" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "in_progress", "revision", "review", "completed", "approved", "cancelled" ] }, "description": "Filter both tasks and subtasks by status (optional)" } ], "responses": { "200": { "description": "User tasks and subtasks retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User tasks and subtasks retrieved successfully." }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9d36a992-0bca-4b08-9df2-51a44e548232" }, "name": { "type": "string", "example": "Nilanjan Mondal" }, "email": { "type": "string", "example": "nilanjan@example.com" }, "mobile_number": { "type": "string", "example": "9876543210" }, "department": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Editorial Department" }, "code": { "type": "string", "example": "EDIT" } } } } }, "summary": { "type": "object", "properties": { "tasks": { "type": "object", "properties": { "total": { "type": "integer", "example": 5 }, "pending": { "type": "integer", "example": 1 }, "in_progress": { "type": "integer", "example": 3 }, "completed": { "type": "integer", "example": 1 }, "overdue": { "type": "integer", "example": 0 } } }, "subtasks": { "type": "object", "properties": { "total": { "type": "integer", "example": 8 }, "pending": { "type": "integer", "example": 2 }, "in_progress": { "type": "integer", "example": 4 }, "completed": { "type": "integer", "example": 2 } } } } }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "example": "Mathematics Class 10 Chapter 5 Review" }, "description": { "type": "string", "example": "Complete initial review of chapter 5 manuscript." }, "status": { "type": "string", "example": "in_progress" }, "priority": { "type": "string", "example": "high" }, "start_date": { "type": "string", "format": "date-time" }, "due_date": { "type": "string", "format": "date-time" }, "assigned_to": { "type": "string", "format": "uuid" }, "department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": "string" } } }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "task_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "example": "Proofread exercise 5.1" }, "status": { "type": "string", "example": "completed" } } } } } } }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "task_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "example": "Proofread exercise 5.1" }, "status": { "type": "string", "example": "completed" }, "assigned_to": { "type": "string", "format": "uuid" }, "task": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" } } } } } } } } } } }, "404": { "description": "User not found" } } } }, "/api/task-types": { "get": { "tags": [ "Task Types Master" ], "summary": "List all task types", "description": "Retrieve all task types with optional search query (name, code, description), active status filter, and associated tasks count. Accessible by all authenticated users.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by task type name, code, or description" }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by active status (true/false)" } ], "responses": { "200": { "description": "Task types retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Task types retrieved successfully." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaskType" } }, "task_types": { "type": "array", "items": { "$ref": "#/components/schemas/TaskType" } }, "total": { "type": "integer", "example": 2 } } } } } }, "401": { "description": "Unauthorized - Missing or invalid JWT Bearer token" } } }, "post": { "tags": [ "Task Types Master" ], "summary": "Create a new task type", "description": "Create a new task type with unique name, optional short code, description, and status. If code is omitted, it will be automatically slugified from the name. Accessible by superadmin and admin roles.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskTypeInput" } } } }, "responses": { "201": { "description": "Task type created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Task type created successfully." }, "data": { "$ref": "#/components/schemas/TaskType" }, "task_type": { "$ref": "#/components/schemas/TaskType" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "422": { "description": "Validation error (e.g. duplicate name or code)" } } } }, "/api/task-types/save": { "post": { "tags": [ "Task Types Master" ], "summary": "Unified save API for task type (Create or Update)", "description": "Single unified endpoint for both create and update operations. If \"id\" is provided in the request payload, updates the existing task type; otherwise creates a new task type. Accessible by superadmin and admin roles.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskTypeInput" } } } }, "responses": { "200": { "description": "Task type updated successfully (when id is present in payload)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Task type updated successfully." }, "data": { "$ref": "#/components/schemas/TaskType" }, "task_type": { "$ref": "#/components/schemas/TaskType" } } } } } }, "201": { "description": "Task type created successfully (when id is omitted from payload)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Task type created successfully." }, "data": { "$ref": "#/components/schemas/TaskType" }, "task_type": { "$ref": "#/components/schemas/TaskType" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Task type not found for update" }, "422": { "description": "Validation error" } } } }, "/api/task-types/{id}": { "get": { "tags": [ "Task Types Master" ], "summary": "Get task type by ID or Code", "description": "Retrieve task type details by UUID or short slug code (e.g. \"book\", \"video\"), including associated tasks count. Accessible by all authenticated users.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task type UUID or unique short code" } ], "responses": { "200": { "description": "Task type retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Task type retrieved successfully." }, "data": { "$ref": "#/components/schemas/TaskType" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Task type not found" } } }, "patch": { "tags": [ "Task Types Master" ], "summary": "Partially update an existing task type", "description": "Partially update name, code, description, or active status of an existing task type by UUID.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Task type UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskTypeInput" } } } }, "responses": { "200": { "description": "Task type updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Task type updated successfully." }, "data": { "$ref": "#/components/schemas/TaskType" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Task type not found" }, "422": { "description": "Validation error" } } }, "delete": { "tags": [ "Task Types Master" ], "summary": "Delete a task type", "description": "Permanently delete a task type by UUID. Automatically and safely disassociates referencing tasks by setting their task_type_id to null before deletion. Accessible by superadmin and admin roles.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Task type UUID" } ], "responses": { "200": { "description": "Task type deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Task type 'Video' deleted successfully." } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Task type not found" } } } }, "/api/tasks/{id}/revision": { "post": { "tags": [ "Tasks" ], "summary": "Request revision or correction for a task", "description": "Sets task status parameter to \"revision\" or \"correction\", updates revision_date, due_date, increments extension_count, and logs activity.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Status parameter: \"revision\" or \"correction\" (defaults to \"revision\")", "schema": { "type": "string", "enum": [ "revision", "correction" ], "default": "revision" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "revision_date", "revision_notes" ], "properties": { "status": { "type": "string", "enum": [ "revision", "correction" ], "example": "revision", "description": "Status parameter: target status for the task (\"revision\" or \"correction\")" }, "revision_date": { "type": "string", "format": "date-time", "example": "2026-10-25 18:00:00" }, "revision_notes": { "type": "string", "example": "Please review and revise the deliverables" } } } } } }, "responses": { "200": { "description": "Task revision/correction requested successfully" }, "404": { "description": "Task not found" } } } }, "/api/revision-corrections": { "get": { "tags": [ "Revision Corrections" ], "summary": "List revision and correction records", "description": "Retrieve a list of revision and correction logs with optional status, task, and subtask filtering.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Status parameter: filter by revision, correction, pending, in_progress, resolved, approved, rejected", "schema": { "type": "string", "enum": [ "revision", "correction", "pending", "in_progress", "resolved", "approved", "rejected" ] } }, { "name": "task_id", "in": "query", "required": false, "description": "Filter by Task UUID", "schema": { "type": "string" } }, { "name": "task_subtask_id", "in": "query", "required": false, "description": "Filter by Subtask UUID", "schema": { "type": "string" } }, { "name": "extension_count", "in": "query", "required": false, "description": "Filter by extension count iteration", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Pagination per page limit", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Revision corrections retrieved successfully" } } } }, "/api/revision-corrections/{id}": { "get": { "tags": [ "Revision Corrections" ], "summary": "Get a single revision correction record", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Revision correction UUID", "schema": { "type": "string", "format": "uuid", "example": "62cf602d-ec95-468a-9dd1-1d5d371787d4" } } ], "responses": { "200": { "description": "Revision correction record retrieved" }, "404": { "description": "Record not found" } } }, "delete": { "tags": [ "Revision Corrections" ], "summary": "Delete a revision correction record", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Revision correction UUID", "schema": { "type": "string", "format": "uuid", "example": "62cf602d-ec95-468a-9dd1-1d5d371787d4" } } ], "responses": { "200": { "description": "Record deleted successfully" }, "404": { "description": "Record not found" } } } }, "/api/tasks/{taskId}/subtasks/{subtaskId}/revision-correction": { "patch": { "tags": [ "Task Subtasks" ], "summary": "Request a revision or correction for a subtask (PATCH only)", "description": "Requests a revision or correction for a specific subtask using PATCH method. Increments extension count, sets subtask status to revision or correction, and logs the request to the revision_corrections table.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task ID or UUID", "schema": { "type": "string" } }, { "name": "subtaskId", "in": "path", "required": true, "description": "Subtask ID or UUID", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Request type: revision or correction", "schema": { "type": "string", "enum": [ "revision", "correction" ], "default": "revision" } }, { "name": "status", "in": "query", "required": false, "description": "Alias for type: revision or correction", "schema": { "type": "string", "enum": [ "revision", "correction" ] } }, { "name": "date", "in": "query", "required": false, "description": "Requested effective deadline date (e.g. 2026-11-05 18:00:00)", "schema": { "type": "string" } }, { "name": "notes", "in": "query", "required": false, "description": "Details or notes explaining the revision/correction request", "schema": { "type": "string" } }, { "name": "requested_days", "in": "query", "required": false, "description": "Number of days requested for extension", "schema": { "type": "integer", "example": 3 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "revision", "correction" ], "example": "revision", "description": "Type of request: revision or correction" }, "status": { "type": "string", "enum": [ "revision", "correction" ], "example": "revision", "description": "Target subtask status (alias for type)" }, "date": { "type": "string", "format": "date-time", "example": "2026-11-05 18:00:00", "description": "Requested deadline date" }, "revision_date": { "type": "string", "format": "date-time", "example": "2026-11-05 18:00:00", "description": "Alias for date parameter" }, "extension_count": { "type": "integer", "example": 1, "description": "Extension count" }, "requested_days": { "type": "integer", "example": 3, "description": "Number of days requested for extension" }, "notes": { "type": "string", "example": "Please adjust header padding and font hierarchy to match the design spec", "description": "Request notes or details" }, "revision_notes": { "type": "string", "example": "Please adjust header padding and font hierarchy to match the design spec", "description": "Alias for notes" }, "correction_status": { "type": "string", "enum": [ "pending", "approved", "rejected" ], "example": "pending", "description": "Initial status of the revision_corrections audit record" } } }, "example": { "type": "revision", "date": "2026-11-05 18:00:00", "extension_count": 1, "requested_days": 3, "notes": "Please adjust header padding and font hierarchy to match the design spec" } } } }, "responses": { "200": { "description": "Subtask revision or correction requested successfully", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Subtask revision requested successfully.", "data": { "id": "c1f71587-ba42-4545-927a-8f5339678822", "task_id": "8e051dfd-d308-4f25-b4c1-b285baf3136e", "title": "Fix responsive navbar layout", "status": "revision", "due_date": { "from": "2026-10-28 10:00:00", "to": "2026-11-05 18:00:00" }, "extension_count": 1, "revision_count": 1, "correction_count": 0 } } } } }, "404": { "description": "Subtask or Task not found" } } } }, "/api/tasks/{taskId}/subtasks/{subtaskId}/revision-correction-approve": { "patch": { "tags": [ "Task Subtasks" ], "summary": "Approve subtask revision or extension (PATCH only)", "description": "Approves a pending revision/correction extension for a subtask using PATCH method. Updates subtask status to in_progress (or approved), extends due date with approved days, and marks the revision_corrections audit record as approved.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task ID or UUID", "schema": { "type": "string" } }, { "name": "subtaskId", "in": "path", "required": true, "description": "Subtask ID or UUID", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "in_progress", "approved" ], "default": "in_progress", "description": "Target subtask status: in_progress to resume work, or approved to finalize subtask." }, "approved_extension_count": { "type": "integer", "example": 2, "description": "Actual number of days / extensions approved by manager" }, "approved_days": { "type": "integer", "example": 2, "description": "Alias for approved_extension_count" }, "approval_date": { "type": "string", "format": "date", "example": "2026-11-04", "description": "Approval effective date" }, "extended_date": { "type": "string", "format": "date-time", "example": "2026-11-04 18:00:00", "description": "New approved deadline" }, "approval_notes": { "type": "string", "example": "Approved 2 days extension instead of 3. Please prioritize finishing this.", "description": "Manager approval notes or remarks" } } }, "example": { "status": "in_progress", "approved_extension_count": 2, "approved_days": 2, "approval_date": "2026-11-04", "extended_date": "2026-11-04 18:00:00", "approval_notes": "Approved 2 days extension instead of 3. Please prioritize finishing this." } } } }, "responses": { "200": { "description": "Subtask revision approved and extension granted successfully", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Subtask approved and extension granted successfully.", "data": { "id": "c1f71587-ba42-4545-927a-8f5339678822", "task_id": "8e051dfd-d308-4f25-b4c1-b285baf3136e", "title": "Fix responsive navbar layout", "status": "in_progress", "due_date": { "from": "2026-10-28 10:00:00", "to": "2026-11-04 18:00:00" }, "extension_count": 1, "revision_count": 1, "correction_count": 0, "latest_revision_correction": { "id": 15, "task_id": 1, "task_subtask_id": 2, "type": "revision", "status": "approved", "extension_count": 1, "notes": "Please adjust header padding and font hierarchy to match the design spec", "date": "2026-11-05", "request_by": 5, "request_at": "2026-10-29T11:20:00.000000Z", "approved_by": 2, "approval_date": "2026-11-04", "approved_at": "2026-10-29T12:00:00.000000Z", "approved_extension_count": 2, "approval_notes": "Approved 2 days extension instead of 3. Please prioritize finishing this." } } } } } }, "404": { "description": "Subtask or Task not found." } } } } }, "tags": [ { "name": "Users Management", "description": "Endpoints for listing, creating, updating, and deleting users and managing their roles. The /users/list endpoint provides a lightweight non-paginated list suitable for dropdowns and selects." }, { "name": "Reports & Analytics", "description": "Production-ready analytics and reporting endpoints covering department-wise, task-wise, month-wise, weekly-wise, and employee-wise metrics." }, { "name": "Workflows Master", "description": "Each workflow defines ordered stages that tasks move through. Accessible by admin/superadmin (read+write) and team_lead (read-only)." }, { "name": "Workflow Stages Master", "description": "Master data for individual workflow stages/sections. Select parent workflow, configure custom sequential sections, colors, and order." }, { "name": "Task Types Master", "description": "Master data entity for task categories (e.g. Book, Video, and custom types). Supports listing with task counts, single detail lookup by UUID or slug code, creation, unified save endpoint (create/update), PUT/PATCH update, and safe deletion." }, { "name": "Departments", "description": "Department and sub-department hierarchy management, parent-wise divisions, and organization structure" }, { "name": "Task Subtasks", "description": "Task subtasks management, page numbering (page_no), revisions, approvals, and team assignments" }, { "name": "Revision Corrections", "description": "Revision and correction workflows, status parameter tracking (\"pending\", \"in_progress\", \"resolved\", \"approved\", \"rejected\"), and approval lifecycle." } ] }