# Ramion Marketplace - API Documentation for Frontend Developers

Welcome! This document outlines all available API endpoints, their expected payloads, query/URL parameters, authentication mechanisms, and response payloads.

## General Information

- **Base URL:** `http://127.0.0.1:8000` (or your configured local/production host)
- **Authentication:**
    - Authentication is handled seamlessly using **Secure HTTP-only Cookies** (`accessToken`).
    - Upon calling the **Login** API, the server returns a `Set-Cookie` header. Modern web browsers and HTTP clients (like Axios, Fetch, or Postman) will store this cookie automatically and attach it to all subsequent requests to this domain.
    - **IMPORTANT (Axios/Fetch Frontend Config):** Make sure to enable credential inclusion on your frontend HTTP requests, e.g.:
        - Axios: `axios.defaults.withCredentials = true;`
        - Fetch: `{ credentials: 'include' }`

---

## Standard Response Structure

### Success Response (Object)

```json
{
    "success": true,
    "message": "User retrieved successfully",
    "data": {
        "id": "USR_e87f8f90",
        "name": "Test User",
        "email": "user@gmail.com",
        "isEmailVerified": true,
        "roleId": "ROL_a12b3c4d",
        "createdAt": "2026-05-07T05:29:13.000000Z",
        "updatedAt": "2026-05-07T05:29:13.000000Z"
    },
    "statusCode": 200
}
```

### Success Response (Paginated Collection)

```json
{
    "success": true,
    "message": "Users retrieved successfully",
    "data": [
        {
            "id": "USR_e87f8f90",
            "name": "Test User",
            "email": "user@gmail.com"
        }
    ],
    "statusCode": 200,
    "count": 1
}
```

### Error Response (Generic / Custom)

```json
{
    "success": false,
    "message": "Invalid email or password",
    "statusCode": 401
}
```

### Error Response (Validation Failure)

```json
{
    "success": false,
    "message": "The given data was invalid.",
    "error": {
        "email": ["Please enter a valid email address."],
        "password": ["The password field is required."]
    },
    "statusCode": 422
}
```

---

## 1. Auth Module (`/auth/*`)

### 1.1 Register

Registers a new standard user in the system.

- **Method:** `POST`
- **Route:** `/auth/register`
- **Headers:** `Accept: application/json`, `Content-Type: application/json`
- **Request Parameters (Body):**
  | Parameter | Type | Required | Validation Rules / Notes | Description |
  | :--- | :--- | :--- | :--- | :--- |
  | `name` | String | **Yes** | min:2, max:255 | Full name of the user |
  | `email` | String | **Yes** | email, max:255, unique:users | Email address (must be unique) |
  | `phoneNumber` | String | **Yes** | max:50, unique:users | Unique phone number of the user |
  | `password` | String | **Yes** | min:8, max:255, confirmed | Account password (must match confirmation) |
  | `passwordConfirmation` | String | **Yes** | min:8, max:255 | Exact password confirmation |

- **Response (201 Created):**
    ```json
    {
        "success": true,
        "message": "Your registration successfully finished",
        "data": {
            "id": "USR_df87g23a",
            "name": "John Doe",
            "email": "john@example.com",
            "phoneNumber": "+8801712345678",
            "isEmailVerified": false,
            "roleId": "ROL_user_default_id",
            "createdAt": "2026-05-07T11:51:59.000000Z",
            "updatedAt": "2026-05-07T11:51:59.000000Z"
        },
        "statusCode": 201
    }
    ```

---

### 1.2 Login (Standard User)

Authenticates a standard user (requires `user` role) and sets an HTTP-only cookie.

- **Method:** `POST`
- **Route:** `/auth/login`
- **Headers:** `Accept: application/json`, `Content-Type: application/json`
- **Request Parameters (Body):**
  | Parameter | Type | Required | Validation Rules / Notes | Description |
  | :--- | :--- | :--- | :--- | :--- |
  | `email` | String | **Yes** | email, max:255 | Login email address |
  | `password` | String | **Yes** | max:255 | Account password |

- **Response (200 OK):** _(Also sets cookie `accessToken` in browser)_
    ```json
    {
        "success": true,
        "message": "Login successful",
        "data": {
            "id": "USR_a56h78b1",
            "name": "Test User",
            "email": "user@gmail.com",
            "isEmailVerified": true,
            "roleId": "ROL_user_id",
            "createdAt": "2026-05-07T05:29:13.000000Z",
            "updatedAt": "2026-05-07T05:29:13.000000Z",
            "role": {
                "id": "ROL_user_id",
                "name": "user",
                "description": "Standard user role with limited access"
            },
            "isCurrentUser": true
        },
        "statusCode": 200
    }
    ```

---

### 1.3 Admin Login

Authenticates an administrator (requires `admin` role) and sets an HTTP-only cookie.

- **Method:** `POST`
- **Route:** `/admin/login`
- **Headers:** `Accept: application/json`, `Content-Type: application/json`
- **Request Parameters (Body):**
  | Parameter | Type | Required | Validation Rules / Notes | Description |
  | :--- | :--- | :--- | :--- | :--- |
  | `email` | String | **Yes** | email, max:255 | Admin login email address |
  | `password` | String | **Yes** | max:255 | Admin account password |

- **Response (200 OK):** _(Also sets cookie `accessToken` in browser)_
    ```json
    {
        "success": true,
        "message": "Admin login successful",
        "data": {
            "id": "USR_admin123",
            "name": "Admin User",
            "email": "admin@gmail.com",
            "isEmailVerified": true,
            "roleId": "ROL_admin_id",
            "createdAt": "2026-05-07T05:29:13.000000Z",
            "updatedAt": "2026-05-07T05:29:13.000000Z",
            "role": {
                "id": "ROL_admin_id",
                "name": "admin",
                "description": "Administrator role with full system access"
            },
            "isCurrentUser": true
        },
        "statusCode": 200
    }
    ```

---

### 1.4 Logout

Logs out the user and clears the cookie.

- **Method:** `POST`
- **Route:** `/auth/logout`
- **Headers:** `Accept: application/json` _(Requires valid Active Cookie session)_
- **Request Parameters:** None
- **Response (200 OK):** _(Clears the cookie)_
    ```json
    {
        "success": true,
        "message": "Logged out successfully",
        "data": null,
        "statusCode": 200
    }
    ```

---

### 1.5 Get Logged-in User Profile

Retrieve info of the currently logged-in session, including their extended profile details if they exist.

- **Method:** `GET`
- **Route:** `/auth/user`
- **Headers:** `Accept: application/json` _(Requires valid Active Cookie session)_
- **Request Parameters:** None
- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "User profile retrieved successfully",
        "data": {
            "id": "USR_a56h78b1",
            "name": "Test User",
            "email": "user@gmail.com",
            "phoneNumber": "+8801712345678",
            "isEmailVerified": true,
            "roleId": "ROL_user_id",
            "role": {
                "id": "ROL_user_id",
                "name": "user",
                "description": "Standard user role with limited access"
            },
            "profile": {
                "id": "PRF_7H8J9K2L",
                "userId": "USR_a56h78b1",
                "whatsappNumber": "+8801712345678",
                "state": "Dhaka",
                "city": "Dhaka",
                "area": "Dhanmondi",
                "address": "Road 27, House 4",
                "profilePictureId": "MED_abc123yz",
                "profilePicture": {
                    "id": "MED_abc123yz",
                    "fileName": "avatar_1715000000_6639b.png",
                    "originalName": "avatar.png",
                    "mimeType": "image/png",
                    "fileSize": 24510,
                    "filePath": "media/2026/05/avatar_1715000000_6639b.png",
                    "type": "image",
                    "isPublic": true,
                    "uploadedBy": "USR_a56h78b1"
                },
                "createdAt": "2026-05-07T05:30:15.000000Z",
                "updatedAt": "2026-05-07T05:30:15.000000Z"
            },
            "isCurrentUser": true,
            "createdAt": "2026-05-07T05:29:13.000000Z",
            "updatedAt": "2026-05-07T05:29:13.000000Z"
        },
        "statusCode": 200
    }
    ```

---

### 1.6 Update User Profile (Self)

Updates the logged-in user's profile information (and optional base account details). If a profile record doesn't exist yet, it is automatically created.

- **Method:** `PUT`
- **Route:** `/auth/profile`
- **Headers:** `Accept: application/json`, `Content-Type: application/json` _(Requires valid Active Cookie session)_
- **Request Parameters (Body):**
  | Parameter | Type | Required | Validation Rules / Notes | Description |
  | :--- | :--- | :--- | :--- | :--- |
  | `name` | String | No | min:2, max:255 | Optional updated full name of the user |
  | `password` | String | No | min:8, confirmed | Optional updated account password |
  | `passwordConfirmation` | String | **Yes if `password` sent** | min:8 | Password confirmation match |
  | `phoneNumber` | String | No | max:50, unique:users | Optional updated unique phone number of the user |
  | `whatsappNumber` | String | No | max:50 | Optional WhatsApp number for instant leads |
  | `state` | String | No | max:255 | Optional state |
  | `city` | String | No | max:255 | Optional city |
  | `area` | String | No | max:255 | Optional area |
  | `address` | String | No | max:1000 | Optional physical street address |
  | `profilePictureId` | String | No | exists:media,id | Optional Media ID of uploaded profile photo |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Profile updated successfully",
        "data": {
            "id": "USR_a56h78b1",
            "name": "Test User Updated",
            "email": "user@gmail.com",
            "phoneNumber": "+8801800000000",
            "isEmailVerified": true,
            "roleId": "ROL_user_id",
            "role": {
                "id": "ROL_user_id",
                "name": "user"
            },
            "profile": {
                "id": "PRF_7H8J9K2L",
                "userId": "USR_a56h78b1",
                "whatsappNumber": "+8801800000000",
                "state": "Dhaka",
                "city": "Dhaka",
                "area": "Dhanmondi",
                "address": "Road 27, House 4 (Updated)",
                "profilePictureId": "MED_abc123yz",
                "createdAt": "2026-05-07T05:30:15.000000Z",
                "updatedAt": "2026-05-07T05:35:45.000000Z"
            },
            "isCurrentUser": true,
            "createdAt": "2026-05-07T05:29:13.000000Z",
            "updatedAt": "2026-05-07T05:35:45.000000Z"
        },
        "statusCode": 200
    }
    ```

---

### 1.7 Get User Dashboard Statistics

Retrieve standard marketplace user dashboard stats, including total listings, active/approved listings, total listing views, and verification status.

- **Method:** `GET`
- **Route:** `/auth/dashboard`
- **Headers:** `Accept: application/json` _(Requires valid Active Cookie session)_
- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "User dashboard statistics retrieved successfully",
        "data": {
            "totalListings": 5,
            "activeListings": 3,
            "totalListingViews": 142,
            "isEmailVerified": true
        },
        "statusCode": 200
    }
    ```

---

### 1.8 Find User Profile by Email

Verify/Lookup public user profile using email.

- **Method:** `GET`
- **Route:** `/auth/{email}`
- **Headers:** `Accept: application/json`
- **Request Parameters (URL Route):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `email` | String | **Yes** | Email address of the user to search |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "User retrieved successfully",
        "data": {
            "id": "USR_a56h78b1",
            "name": "Test User",
            "email": "user@gmail.com"
        },
        "statusCode": 200
    }
    ```

---

## 2. User Management Module (`/user/*`)

_All endpoints under User Management require authenticating as an authorized user (typically an `admin`)._

### 2.1 List Users

Retrieve a paginated, searchable, and filterable list of users.

- **Method:** `GET`
- **Route:** `/user`
- **Request Parameters (Query):**
  | Parameter | Type | Required | Default | Description |
  | :--- | :--- | :--- | :--- | :--- |
  | `page` | Integer | No | `1` | Page number for pagination |
  | `count` | Integer | No | `10` | Number of records per page (pagination count size) |
  | `search` | String | No | - | Query to match either `name` or `email` (supports partial matches) |
  | `sort` | String | No | - | Field name to sort by (e.g. `name`, `email`, `createdAt`) |
  | `order` | String | No | `asc` | Sort direction (`asc` or `desc`) |
  | `roleId` | String (UUID) | No | - | Filters list to only users containing this Role ID |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Users retrieved successfully",
        "data": [
            {
                "id": "USR_admin123",
                "name": "Admin User",
                "email": "admin@gmail.com",
                "isEmailVerified": true,
                "roleId": "ROL_admin_id",
                "role": {
                    "id": "ROL_admin_id",
                    "name": "admin",
                    "description": "Administrator role with full system access"
                },
                "profile": {
                    "id": "PRF_7H8J9K2L",
                    "userId": "USR_admin123",
                    "whatsappNumber": "+8801800000000",
                    "state": "Dhaka",
                    "city": "Dhaka",
                    "area": "Dhanmondi",
                    "address": "Road 27, House 4",
                    "profilePictureId": null,
                    "createdAt": "2026-05-07T05:29:13.000000Z",
                    "updatedAt": "2026-05-07T05:29:13.000000Z"
                },
                "createdAt": "2026-05-07T05:29:13.000000Z",
                "updatedAt": "2026-05-07T05:29:13.000000Z"
            }
        ],
        "statusCode": 200,
        "count": 1
    }
    ```

---

### 2.2 Get User By ID

- **Method:** `GET`
- **Route:** `/user/{userId}`
- **Request Parameters (URL Route):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `userId` | String (UUID) | **Yes** | Unique identifier (UUID) of the user |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "User retrieved successfully",
        "data": {
            "id": "USR_a56h78b1",
            "name": "Test User",
            "email": "user@gmail.com",
            "isEmailVerified": true,
            "roleId": "ROL_user_id",
            "role": {
                "id": "ROL_user_id",
                "name": "user"
            },
            "createdAt": "2026-05-07T05:29:13.000000Z",
            "updatedAt": "2026-05-07T05:29:13.000000Z"
        },
        "statusCode": 200
    }
    ```

---

### 2.3 Create User

- **Method:** `POST`
- **Route:** `/user`
- **Request Parameters (Body):**
  | Parameter | Type | Required | Validation Rules / Notes | Description |
  | :--- | :--- | :--- | :--- | :--- |
  | `name` | String | **Yes** | max:255 | Full name of the user |
  | `email` | String | **Yes** | email, unique:users | Unique email address |
  | `phoneNumber` | String | **Yes** | max:50, unique:users | Unique phone number |
  | `password` | String | **Yes** | min:8 | Password for the new user |
  | `roleId` | String (UUID) | No | exists:roles,id | Role ID to assign (can be null/omitted) |

- **Response (201 Created):**
    ```json
    {
        "success": true,
        "message": "User created successfully",
        "data": {
            "id": "USR_j91h823k",
            "name": "Jane Doe",
            "email": "jane@example.com",
            "phoneNumber": "+8801712345678",
            "isActive": true,
            "status": true,
            "isEmailVerified": false,
            "roleId": "ROL_user_id",
            "createdAt": "2026-05-07T12:00:00.000000Z",
            "updatedAt": "2026-05-07T12:00:00.000000Z"
        },
        "statusCode": 201
    }
    ```

---

### 2.4 Update User

- **Method:** `PUT`
- **Route:** `/user/{userId}`
- **Request Parameters (URL Route):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `userId` | String (UUID) | **Yes** | Unique identifier (UUID) of the user |

- **Request Parameters (Body):** _(All fields are optional, send only what is changing)_
  | Parameter | Type | Required | Validation Rules / Notes | Description |
  | :--- | :--- | :--- | :--- | :--- |
  | `name` | String | No | max:255 | Updated user name |
  | `email` | String | No | email, unique:users | Updated unique email address |
  | `phoneNumber` | String | No | max:50, unique:users | Updated unique phone number |
  | `password` | String | No | min:8 | If provided, updates password |
  | `passwordConfirmation` | String | **Yes if `password` sent** | | Must match password exactly |
  | `roleId` | String (UUID) | No | exists:roles,id | Update assigned Role ID |
  | `isActive` | Boolean | No | boolean | Toggle user active state (False blocks login with message: 'User is not active. Please contact admin.') |
  | `status` | Boolean | No | boolean | Toggle user soft-deleted state (False performs soft deletion) |
  | `whatsappNumber` | String | No | max:50 | Updated WhatsApp number |
  | `state` | String | No | max:255 | Updated state |
  | `city` | String | No | max:255 | Updated city |
  | `area` | String | No | max:255 | Updated area |
  | `address` | String | No | max:1000 | Updated street address |
  | `profilePictureId` | String | No | exists:media,id | Updated profile picture Media ID |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "User updated successfully",
        "data": {
            "id": "USR_j91h823k",
            "name": "Jane Doe Updated",
            "email": "jane_updated@example.com",
            "phoneNumber": "+8801712345678",
            "isActive": true,
            "status": true,
            "isEmailVerified": false,
            "roleId": "ROL_admin_id",
            "profile": {
                "id": "PRF_7H8J9K2L",
                "userId": "USR_j91h823k",
                "whatsappNumber": "+8801712345678",
                "state": "Dhaka",
                "city": "Dhaka",
                "area": "Dhanmondi",
                "address": "Road 27, House 4",
                "profilePictureId": null,
                "createdAt": "2026-05-07T12:00:00.000000Z",
                "updatedAt": "2026-05-07T12:05:00.000000Z"
            },
            "createdAt": "2026-05-07T12:00:00.000000Z",
            "updatedAt": "2026-05-07T12:05:00.000000Z"
        },
        "statusCode": 200
    }
    ```

---

### 2.5 Delete User

- **Method:** `DELETE`
- **Route:** `/user/{userId}`
- **Request Parameters (URL Route):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `userId` | String (UUID) | **Yes** | Unique identifier (UUID) of the user |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "User deleted successfully",
        "data": null,
        "statusCode": 200
    }
    ```

---

## 3. Role Management Module (`/role/*`)

### 3.1 List Roles

- **Method:** `GET`
- **Route:** `/role`
- **Request Parameters:** None
- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Roles retrieved successfully",
        "data": [
            {
                "id": "ROL_admin_id",
                "name": "admin",
                "description": "Administrator role with full system access",
                "isActive": true
            }
        ],
        "statusCode": 200,
        "count": 1
    }
    ```

---

### 3.2 Get Role By ID

- **Method:** `GET`
- **Route:** `/role/{roleId}`
- **Request Parameters (URL Route):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `roleId` | String (UUID) | **Yes** | Unique Role identifier (UUID) |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Role retrieved successfully",
        "data": {
            "id": "ROL_admin_id",
            "name": "admin",
            "description": "Administrator role with full system access",
            "isActive": true
        },
        "statusCode": 200
    }
    ```

---

### 3.3 Create Role

- **Method:** `POST`
- **Route:** `/role`
- **Request Parameters (Body):**
  | Parameter | Type | Required | Validation Rules / Notes | Description |
  | :--- | :--- | :--- | :--- | :--- |
  | `name` | String | **Yes** | max:255, unique:roles | Unique alpha name of the role |
  | `description` | String | No | max:2000 | Description of what this role does |
  | `isActive` | Boolean | No | default: `true` | Set status of the role |

- **Response (201 Created):**
    ```json
    {
        "success": true,
        "message": "Role created successfully",
        "data": {
            "id": "ROL_editor_id",
            "name": "editor",
            "description": "Editor with publishing capabilities",
            "isActive": true
        },
        "statusCode": 201
    }
    ```

---

### 3.4 Update Role

- **Method:** `PUT`
- **Route:** `/role/{roleId}`
- **Request Parameters (URL Route):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `roleId` | String (UUID) | **Yes** | Unique Role identifier (UUID) |

- **Request Parameters (Body):** _(All fields are optional)_
  | Parameter | Type | Required | Validation Rules / Notes | Description |
  | :--- | :--- | :--- | :--- | :--- |
  | `name` | String | No | max:255, unique:roles | Updated unique role name |
  | `description` | String | No | max:2000 | Updated role description |
  | `isActive` | Boolean | No | | Toggle active/disabled status |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Role updated successfully",
        "data": {
            "id": "ROL_editor_id",
            "name": "editor-updated",
            "description": "Updated editor role description",
            "isActive": false
        },
        "statusCode": 200
    }
    ```

---

### 3.5 Get Role Permissions

Get all permissions assigned to a specific role.

- **Method:** `GET`
- **Route:** `/role/{roleId}/permissions`
- **Request Parameters (URL Route):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `roleId` | String (UUID) | **Yes** | Unique Role identifier (UUID) |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Role permissions retrieved successfully",
        "data": [
            {
                "id": "PRM_user_list",
                "name": "user.list",
                "description": "Allows listing users",
                "isActive": true
            }
        ],
        "statusCode": 200
    }
    ```

---

### 3.6 Assign Permissions to Role

Sync multiple permissions to a role. Any old permissions mapping not included in the payload will be unlinked automatically.

- **Method:** `POST`
- **Route:** `/role/{roleId}/permissions`
- **Request Parameters (URL Route):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `roleId` | String (UUID) | **Yes** | Unique Role identifier (UUID) |

- **Request Parameters (Body):**
  | Parameter | Type | Required | Validation Rules / Notes | Description |
  | :--- | :--- | :--- | :--- | :--- |
  | `permissionIds` | Array of Strings | **Yes** | exists:permissions,id | Array containing valid permission UUIDs |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Permissions assigned to role successfully",
        "data": null,
        "statusCode": 200
    }
    ```

---

### 3.7 Delete Role

- **Method:** `DELETE`
- **Route:** `/role/{roleId}`
- **Request Parameters (URL Route):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `roleId` | String (UUID) | **Yes** | Unique Role identifier (UUID) |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Role deleted successfully",
        "data": null,
        "statusCode": 200
    }
    ```

---

## 4. Permission Management Module (`/permission/*`)

### 4.1 List Permissions

Lists all available permissions inside the system.

- **Method:** `GET`
- **Route:** `/permission`
- **Request Parameters:** None
- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Permissions retrieved successfully",
        "data": [
            {
                "id": "PRM_user_list",
                "name": "user.list",
                "description": "Allows listing users",
                "isActive": true
            }
        ],
        "statusCode": 200,
        "count": 1
    }
    ```

---

## 5. SMTP Configuration Module (`/smtp-config/*`)

### 5.1 Get SMTP Settings

- **Method:** `GET`
- **Route:** `/smtp-config`
- **Request Parameters:** None
- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "SMTP configuration retrieved successfully",
        "data": {
            "id": "SMT_config_id",
            "host": "smtp.gmail.com",
            "port": 587,
            "username": "test@example.com",
            "encryption": "tls",
            "fromAddress": "noreply@accurebook.com",
            "fromName": "AccureBook System"
        },
        "statusCode": 200
    }
    ```

---

### 5.2 Update SMTP Settings

- **Method:** `PUT`
- **Route:** `/smtp-config`
- **Request Parameters (Body):**
  | Parameter | Type | Required | Validation Rules / Notes | Description |
  | :--- | :--- | :--- | :--- | :--- |
  | `host` | String | **Yes** | | SMTP outgoing server host |
  | `port` | Integer | **Yes** | | Server port (e.g., 587, 465, 25) |
  | `username` | String | No | | Account username (often an email) |
  | `password` | String | No | | Account password |
  | `encryption` | String | **Yes** | in:none,tls,ssl | Server encryption type |
  | `fromAddress` | String | **Yes** | email | Sender's email address |
  | `fromName` | String | **Yes** | | Sender's display name |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "SMTP configuration updated successfully",
        "data": {
            "id": "SMT_config_id",
            "host": "smtp.mailtrap.io",
            "port": 2525,
            "username": "mailtrap-username",
            "encryption": "tls",
            "fromAddress": "info@example.com",
            "fromName": "Marketplace Notification"
        },
        "statusCode": 200
    }
    ```

---

## 6. Media Management Module (`/media/*`)

### 6.1 Upload Media (Single or Multiple)

Uploads single or multiple files to the server. Must use `multipart/form-data` payload format.

- **Method:** `POST`
- **Route:** `/media`
- **Headers:** `Content-Type: multipart/form-data`
- **Request Parameters (Body - Form Data):**
  | Parameter | Type | Required | Validation Rules / Notes | Description |
  | :--- | :--- | :--- | :--- | :--- |
  | `file` | File | No | max:10MB (Required if `files` empty) | A single file binary upload |
  | `files` | Array of Files | No | max:10 items, 10MB each (Required if `file` empty) | Multiple files binary upload (`files[]` inside HTML/JS) |
  | `type` | String | No | in:image,document,video,audio,archive,other | File type category override. If empty, the server automatically infers it. |
  | `isPublic` | Boolean/String | No | default: `true` (Send `true`/`false` or `1`/`0`) | Sets file access restriction level. |

- **Response (201 Created - Single Upload):**
    ```json
    {
        "success": true,
        "message": "File uploaded successfully",
        "data": {
            "id": "MED_abc123yz",
            "fileName": "avatar_1715000000_6639b.png",
            "originalName": "avatar.png",
            "mimeType": "image/png",
            "fileSize": 24510,
            "filePath": "media/2026/05/avatar_1715000000_6639b.png",
            "type": "image",
            "isPublic": true,
            "uploadedBy": "USR_admin123",
            "createdAt": "2026-05-07T12:00:00.000000Z",
            "updatedAt": "2026-05-07T12:00:00.000000Z"
        },
        "statusCode": 201
    }
    ```

---

### 6.2 Stream File (Inline Content)

Renders/streams raw file content inline (e.g., to load as an `<img>` src or PDF preview).

- **Method:** `GET`
- **Route:** `/media/{mediaId}/stream`
- **Request Parameters (URL Route):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `mediaId` | String (UUID) | **Yes** | Unique Media identifier (UUID) |

- **Response (File Stream):**
    - Public file: Directly downloads or streams inline with appropriate `Content-Type` headers.
    - Private file: If `isPublic = false`, checks whether the requesting user is the owner or an admin. If not authenticated or authorized, returns `403 Access Denied`.

---

### 6.3 List Media Metadata

- **Method:** `GET`
- **Route:** `/media`
- **Request Parameters (Query):**
  | Parameter | Type | Required | Default | Description |
  | :--- | :--- | :--- | :--- | :--- |
  | `page` | Integer | No | `1` | Page number for pagination |
  | `count` | Integer | No | `10` | Number of records per page |
  | `type` | String | No | - | Filter files by type category (`image`, `document`, etc.) |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Media retrieved successfully",
        "data": [
            {
                "id": "MED_abc123yz",
                "fileName": "avatar_1715000000_6639b.png",
                "originalName": "avatar.png",
                "mimeType": "image/png",
                "fileSize": 24510,
                "filePath": "media/2026/05/avatar_1715000000_6639b.png",
                "type": "image",
                "isPublic": true,
                "uploadedBy": "USR_admin123",
                "createdAt": "2026-05-07T12:00:00.000000Z",
                "updatedAt": "2026-05-07T12:00:00.000000Z"
            }
        ],
        "statusCode": 200,
        "count": 1
    }
    ```

---

### 6.4 Delete Media

Permanently deletes the database record and the actual physical file from the storage.

- **Method:** `DELETE`
- **Route:** `/media/{mediaId}`
- **Request Parameters (URL Route):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `mediaId` | String (UUID) | **Yes** | Unique Media identifier (UUID) |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Media deleted successfully",
        "data": null,
        "statusCode": 200
    }
    ```

---

## 7. Category Management Module (`/category/*`)

Category management endpoints allow viewing, creating, updating, and deleting directory categories with their associated images.

### 7.1 List Categories

Retrieve a list of categories (paginated, searchable, and filterable), including their associated image details.

- **Method:** `GET`
- **Route:** `/category`
- **Request Parameters (Query):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `page` | Integer | No | Page number |
  | `count` | Integer | No | Page count size |
  | `search` | String | No | Search categories by `name` or `slug` |
  | `isActive` | Boolean | No | Filter by active status |
  | `imageId` | String | No | Filter categories by exact Image/Media ID |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Categories retrieved successfully",
        "data": [
            {
                "id": "CAT_9J8K7L6M",
                "name": "Real Estate",
                "slug": "real-estate",
                "imageId": "MED_abc123yz",
                "image": {
                    "id": "MED_abc123yz",
                    "fileName": "category_1715000000.png",
                    "originalName": "category_icon.png",
                    "mimeType": "image/png",
                    "fileSize": 15420,
                    "fileSizeFormatted": "15 KB",
                    "filePath": "media/2026/05/category_1715000000.png",
                    "fullUrl": "http://127.0.0.1:8000/storage/media/2026/05/category_1715000000.png",
                    "type": "image",
                    "isPublic": true,
                    "isImage": true,
                    "uploadedBy": "USR_admin123",
                    "createdAt": "2026-05-07T12:00:00.000000Z"
                },
                "isActive": true,
                "createdAt": "2026-05-07T12:00:00.000000Z",
                "updatedAt": "2026-05-07T12:00:00.000000Z"
            }
        ],
        "statusCode": 200,
        "count": 1
    }
    ```

### 7.2 Create Category

Create a new category with an optional category image association.

- **Method:** `POST`
- **Route:** `/category`
- **Headers:** `Accept: application/json`, `Content-Type: application/json` _(Requires auth)_
- **Request Parameters (Body):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `name` | String | **Yes** | Name of the category |
  | `slug` | String | **Yes** | Unique, SEO-friendly url slug |
  | `imageId` | String | No | Optional Media ID of uploaded category image (obtained from Media module upload) |
  | `isActive` | Boolean | No | Active state (default: true) |

- **Response (210 Created):**
    ```json
    {
        "success": true,
        "message": "Category created successfully",
        "data": {
            "id": "CAT_9J8K7L6M",
            "name": "Real Estate",
            "slug": "real-estate",
            "imageId": "MED_abc123yz",
            "image": {
                "id": "MED_abc123yz",
                "fileName": "category_1715000000.png",
                "originalName": "category_icon.png",
                "mimeType": "image/png",
                "fileSize": 15420,
                "fileSizeFormatted": "15 KB",
                "filePath": "media/2026/05/category_1715000000.png",
                "fullUrl": "http://127.0.0.1:8000/storage/media/2026/05/category_1715000000.png",
                "type": "image",
                "isPublic": true,
                "isImage": true,
                "uploadedBy": "USR_admin123",
                "createdAt": "2026-05-07T12:00:00.000000Z"
            },
            "isActive": true,
            "createdAt": "2026-05-07T12:30:00.000000Z",
            "updatedAt": "2026-05-07T12:30:00.000000Z"
        },
        "statusCode": 201
    }
    ```

### 7.3 Get Single Category

Retrieve details of a single category, including its associated image details if set.

- **Method:** `GET`
- **Route:** `/category/{id}`

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Category retrieved successfully",
        "data": {
            "id": "CAT_9J8K7L6M",
            "name": "Real Estate",
            "slug": "real-estate",
            "imageId": "MED_abc123yz",
            "image": {
                "id": "MED_abc123yz",
                "fileName": "category_1715000000.png",
                "originalName": "category_icon.png",
                "mimeType": "image/png",
                "fileSize": 15420,
                "fileSizeFormatted": "15 KB",
                "filePath": "media/2026/05/category_1715000000.png",
                "fullUrl": "http://127.0.0.1:8000/storage/media/2026/05/category_1715000000.png",
                "type": "image",
                "isPublic": true,
                "isImage": true,
                "uploadedBy": "USR_admin123",
                "createdAt": "2026-05-07T12:00:00.000000Z"
            },
            "isActive": true,
            "createdAt": "2026-05-07T12:30:00.000000Z",
            "updatedAt": "2026-05-07T12:30:00.000000Z"
        },
        "statusCode": 200
    }
    ```

### 7.4 Update Category

Update fields of an existing category, including changing or clearing its associated image.

- **Method:** `PUT`
- **Route:** `/category/{id}`
- **Headers:** `Accept: application/json`, `Content-Type: application/json` _(Requires auth)_
- **Request Parameters (Body):** _(All fields optional)_
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `name` | String | No | Updated category name |
  | `slug` | String | No | Updated slug |
  | `imageId` | String | No | Updated Media ID of uploaded category image (send `null` or empty string to remove image) |
  | `isActive` | Boolean | No | Updated active state status |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Category updated successfully",
        "data": {
            "id": "CAT_9J8K7L6M",
            "name": "Real Estate Updated",
            "slug": "real-estate",
            "imageId": "MED_abc123yz",
            "image": {
                "id": "MED_abc123yz",
                "fileName": "category_1715000000.png",
                "originalName": "category_icon.png",
                "mimeType": "image/png",
                "fileSize": 15420,
                "fileSizeFormatted": "15 KB",
                "filePath": "media/2026/05/category_1715000000.png",
                "fullUrl": "http://127.0.0.1:8000/storage/media/2026/05/category_1715000000.png",
                "type": "image",
                "isPublic": true,
                "isImage": true,
                "uploadedBy": "USR_admin123",
                "createdAt": "2026-05-07T12:00:00.000000Z"
            },
            "isActive": true,
            "createdAt": "2026-05-07T12:30:00.000000Z",
            "updatedAt": "2026-05-07T12:45:00.000000Z"
        },
        "statusCode": 200
    }
    ```

### 7.5 Delete Category

- **Method:** `DELETE`
- **Route:** `/category/{id}`
- **Headers:** `Accept: application/json` _(Requires auth)_

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Category deleted successfully",
        "data": null,
        "statusCode": 200
    }
    ```

---

## 8. Listings Module (`/listing/*`)

This module manages direct listings posted by standard marketplace users.

### 8.1 List Listings

Retrieve a paginated, searchable, and filterable list of active listings, including category and user details, and attached images.

- **Method:** `GET`
- **Route:** `/listing`
- **Request Parameters (Query):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `page` | Integer | No | Page number |
  | `count` | Integer | No | Page count size |
  | `search` | String | No | Full-text searches through `title`, `sortDescription`, `description`, `location` |
  | `userId` | String | No | Filter by listing creator ID |
  | `categoryId` | String | No | Filter by Category ID |
  | `status` | String | No | Filter by state (`pending`, `approved`, `rejected`) |
  | `sort` | String | No | Sort by columns (`price`, `createdAt`, etc.) |
  | `order` | String | No | Sort order direction (`asc`, `desc`) |

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Listings retrieved successfully",
        "data": [
            {
                "id": "LST_1A2B3C4D",
                "userId": "USR_a56h78b1",
                "categoryId": "CAT_9J8K7L6M",
                "title": "Toyota Axio 2018 for Sale",
                "slug": "toyota-axio-2018-for-sale",
                "sortDescription": "Super fresh hybrid family car",
                "description": "Details about the Toyota Axio Hybrid 2018...",
                "price": 2450000.0,
                "location": "Uttara, Dhaka",
                "contactPhone": "+8801712345678",
                "contactWhatsApp": "+8801712345678",
                "status": "pending",
                "viewsCount": 0,
                "createdAt": "2026-05-07T12:00:00.000000Z",
                "updatedAt": "2026-05-07T12:00:00.000000Z",
                "user": {
                    "id": "USR_a56h78b1",
                    "name": "Test User",
                    "email": "user@gmail.com"
                },
                "category": {
                    "id": "CAT_9J8K7L6M",
                    "name": "Cars",
                    "slug": "cars"
                },
                "media": [
                    {
                        "id": "MED_xyz123ab",
                        "fileName": "car_1715000000.png",
                        "originalName": "car.png",
                        "filePath": "media/2026/05/car_1715000000.png",
                        "mimeType": "image/png",
                        "isPrimary": true,
                        "order": 0
                    }
                ]
            }
        ],
        "statusCode": 200,
        "count": 1
    }
    ```

### 8.2 Create Listing

Post a new listing. The system automatically handles slug generation and assigns `userId` to the logged-in user.

- **Method:** `POST`
- **Route:** `/listing`
- **Headers:** `Accept: application/json`, `Content-Type: application/json` _(Requires auth)_
- **Request Parameters (Body):**
  | Parameter | Type | Required | Description |
  | :--- | :--- | :--- | :--- |
  | `categoryId` | String | **Yes** | ID of the category |
  | `title` | String | **Yes** | Title of the listing |
  | `slug` | String | No | Custom SEO-friendly slug (auto-generated if empty) |
  | `sortDescription` | String | No | Short headline for cards |
  | `description` | String | **Yes** | Comprehensive markdown body description |
  | `price` | Numeric | No | Numeric cost/pricing value |
  | `location` | String | **Yes** | City/area locator |
  | `isContactPhone` | Boolean | No | If true, automatically fetches and shows creator's base phone number |
  | `isContactWhatsApp` | Boolean | No | If true, automatically fetches and shows creator's profile WhatsApp number |
  | `mediaIds` | Array of Strings | No | Array of uploaded Media IDs to attach as images |

- **Response (201 Created):**
    ```json
    {
        "success": true,
        "message": "Listing created successfully",
        "data": {
            "id": "LST_1A2B3C4D",
            "userId": "USR_a56h78b1",
            "categoryId": "CAT_9J8K7L6M",
            "title": "Toyota Axio 2018 for Sale",
            "slug": "toyota-axio-2018-for-sale",
            "sortDescription": "Super fresh hybrid family car",
            "description": "Details about the Toyota Axio Hybrid 2018...",
            "price": 2450000.0,
            "location": "Uttara, Dhaka",
            "isContactPhone": true,
            "isContactWhatsApp": true,
            "contactPhone": "+8801712345678",
            "contactWhatsApp": "+8801712345678",
            "status": "pending",
            "viewsCount": 0,
            "createdAt": "2026-05-07T12:00:00.000000Z",
            "updatedAt": "2026-05-07T12:00:00.000000Z",
            "user": {
                "id": "USR_a56h78b1",
                "name": "Test User",
                "email": "user@gmail.com"
            },
            "category": {
                "id": "CAT_9J8K7L6M",
                "name": "Cars",
                "slug": "cars"
            },
            "media": []
        },
        "statusCode": 201
    }
    ```

### 8.3 Get Single Listing

- **Method:** `GET`
- **Route:** `/listing/{id}`

- **Response (200 OK):** _(Retrieved detailing all mapped relationship fields)_

### 8.4 Update Listing

- **Method:** `PUT`
- **Route:** `/listing/{id}`
- **Headers:** `Accept: application/json`, `Content-Type: application/json` _(Requires auth)_

- **Response (200 OK):** _(Returns the updated resource details)_

### 8.5 Delete Listing

- **Method:** `DELETE`
- **Route:** `/listing/{id}`
- **Headers:** `Accept: application/json` _(Requires auth)_

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Listing deleted successfully",
        "data": null,
        "statusCode": 200
    }
    ```

---

## 9. Dynamic Query Parameters System (Sorting, Searching, Filtering, Pagination)

To make front-end development incredibly dynamic and clean, the backend includes **4 Global Traits** (`HasSearch`, `HasSort`, `HasFilter`, `HasPagination`) that allow front-end developers to dynamically search, sort, filter, and paginate records on listing endpoints (`/user`, `/media`, etc.) straight out of the box using query parameters.

### 9.1 Dynamic Pagination (Count & Page)

Apply these parameters on any paginated listing endpoint to shift pages and configure the count size:

- **`page`** (Integer, default: `1`): The page number you want to retrieve.
- **`count`** (Integer, default: `10`): The page size (limit of rows returned on this page).
- **Example URL:** `http://127.0.0.1:8000/user?page=2&count=15`

### 9.2 Dynamic Sorting (Sort Column & Order Direction)

Sort rows dynamically by allowed sortable table columns:

- **`sort`** (String): The column name to sort by (e.g. `name`, `email`, `createdAt`). This must be listed in the model's allowed `$sortable` array.
- **`order`** (String, default: `asc`): The direction of sorting. Accepts either `asc` (ascending) or `desc` (descending).
- **Example URL:** `http://127.0.0.1:8000/user?sort=createdAt&order=desc`

### 9.3 Dynamic Searching

Instantly search through multiple database text columns (using SQL `LIKE` partial matches) with a single query parameter:

- **`search`** (String): The query string you want to search. Matches any column declared inside the model's allowed `$searchable` property.
    - **For Users:** Searches across both `name` and `email` columns.
- **Example URL:** `http://127.0.0.1:8000/user?search=john`

### 9.4 Dynamic Column Filtering

Filter columns based on exact values. Any parameter passed in the query string that matches the model's `$filterable` property will be applied as an exact matches filter (`where column = value`):

- **`{columnName}`** (Mixed): The filter value.
    - **For Users:** The `$filterable` list includes `roleId`. Therefore, passing `roleId` in the query string filters the user list by that role!
- **Example URL:** `http://127.0.0.1:8000/user?roleId=ROL_admin_uuid`

---

## 10. Admin Dashboard Module (`/admin/*`)

### 10.1 Admin Stats & Pending Listings

Retrieve total user, category, and listing counts, along with a list of all currently pending listings awaiting admin moderation.

- **Method:** `GET`
- **Route:** `/admin/dashboard`
- **Headers:** `Accept: application/json` _(Requires valid Active Cookie session of an `admin` user)_
- **Request Parameters:** None

- **Response (200 OK):**
    ```json
    {
        "success": true,
        "message": "Admin dashboard statistics retrieved successfully",
        "data": {
            "usersCount": 15,
            "categoriesCount": 8,
            "listingsCount": 42,
            "pendingListings": [
                {
                    "id": "LST_1A2B3C4D",
                    "userId": "USR_a56h78b1",
                    "categoryId": "CAT_9J8K7L6M",
                    "title": "Toyota Axio 2018 for Sale",
                    "slug": "toyota-axio-2018-for-sale",
                    "sortDescription": "Super fresh hybrid family car",
                    "description": "Details about the Toyota Axio Hybrid 2018...",
                    "price": 2450000.0,
                    "location": "Uttara, Dhaka",
                    "contactPhone": "+8801712345678",
                    "contactWhatsApp": "+8801712345678",
                    "status": "pending",
                    "createdAt": "2026-05-07T12:00:00.000000Z",
                    "updatedAt": "2026-05-07T12:00:00.000000Z",
                    "user": {
                        "id": "USR_a56h78b1",
                        "name": "Test User",
                        "email": "user@gmail.com"
                    },
                    "category": {
                        "id": "CAT_9J8K7L6M",
                        "name": "Cars",
                        "slug": "cars"
                    },
                    "media": []
                }
            ]
        },
        "statusCode": 200
    }
    ```

---

## 11. Dictionary: Master Summary of All Parameters

Here is a quick cheat-sheet listing all possible fields and query inputs across the whole marketplace application:

| Parameter Name             | Data Type        | Parameter Type       | Validated Constraints        | Used in Endpoint(s)                                                              | Description                                               |
| :------------------------- | :--------------- | :------------------- | :--------------------------- | :------------------------------------------------------------------------------- | :-------------------------------------------------------- |
| **`email`**                | String           | Request Body / URL   | email, max:255, unique       | `/auth/register`, `/auth/login`, `/auth/{email}`, `/user` (POST/PUT)             | User email identifier                                     |
| **`password`**             | String           | Request Body         | min:8, max:255               | `/auth/register`, `/auth/login`, `/user` (POST/PUT)                              | Account secret credentials                                |
| **`passwordConfirmation`** | String           | Request Body         | min:8, max:255               | `/auth/register`, `/user` (PUT)                                                  | Password confirmation mapping                             |
| **`name`**                 | String           | Request Body         | min:2, max:255               | `/auth/register`, `/user` (POST/PUT), `/role` (POST/PUT), `/category` (POST/PUT) | Standard name descriptor for Users, Roles, and Categories |
| **`slug`**                 | String           | Request Body         | max:255, unique, regex       | `/category` (POST/PUT), `/listing` (POST/PUT)                                    | SEO-friendly URL route slice identifier                   |
| **`isActive`**             | Boolean          | Request Body         | boolean                      | `/role` (POST/PUT), `/category` (POST/PUT)                                       | Operational status indicator                              |
| **`title`**                | String           | Request Body         | min:2, max:255               | `/listing` (POST/PUT)                                                            | Core listing heading                                      |
| **`sortDescription`**      | String           | Request Body         | max:255, nullable            | `/listing` (POST/PUT)                                                            | Brief listing caption summary                             |
| **`description`**          | String           | Request Body         | max:50000                    | `/listing` (POST/PUT)                                                            | Detailed markdown post explanation                        |
| **`price`**                | Numeric          | Request Body / Query | numeric, min:0               | `/listing` (POST/PUT)                                                            | Listing item price value                                  |
| **`location`**             | String           | Request Body         | max:255                      | `/listing` (POST/PUT)                                                            | Physical region location identifier                       |
| **`contactPhone`**         | String           | Request Body         | max:50                       | `/listing` (POST/PUT)                                                            | Primary call contact number                               |
| **`contactWhatsApp`**      | String           | Request Body         | max:50                       | `/listing` (POST/PUT)                                                            | WhatsApp messaging link contact                           |
| **`status`**               | String           | Request Body / Query | in:pending,approved,rejected | `/listing` (POST/PUT/GET)                                                        | Moderate state status category                            |
| **`mediaIds`**             | Array of Strings | Request Body         | exists:media,id              | `/listing` (POST/PUT)                                                            | Media item identification references                      |
| **`roleId`**               | String (UUID)    | Request Body / Query | exists:roles,id              | `/user` (POST/PUT/GET)                                                           | Unique identifier linking user to a Role                  |
| **`userId`**               | String (UUID)    | URL Route Parameter  | exists:users,id              | `/user/{userId}` (GET/PUT/DELETE)                                                | Unique user instance identifier                           |
| **`roleId`**               | String (UUID)    | URL Route Parameter  | exists:roles,id              | `/role/{roleId}` (GET/PUT/DELETE/permissions)                                    | Unique role instance identifier                           |
| **`permissionIds`**        | Array of Strings | Request Body         | exists:permissions,id        | `/role/{roleId}/permissions` (POST)                                              | Permissions list to map                                   |
| **`host`**                 | String           | Request Body         | required                     | `/smtp-config` (PUT)                                                             | SMTP service server host address                          |
| **`port`**                 | Integer          | Request Body         | required, integer            | `/smtp-config` (PUT)                                                             | Outgoing port number (e.g. 587)                           |
| **`username`**             | String           | Request Body         | nullable                     | `/smtp-config` (PUT)                                                             | SMTP authentication username                              |
| **`encryption`**           | String           | Request Body         | in:none,tls,ssl              | `/smtp-config` (PUT)                                                             | Security layer wrapper standard                           |
| **`fromAddress`**          | String           | Request Body         | email, required              | `/smtp-config` (PUT)                                                             | Email address displayed in 'From' field                   |
| **`fromName`**             | String           | Request Body         | required                     | `/smtp-config` (PUT)                                                             | Name displayed in 'From' field                            |
| **`file`**                 | File             | Form-data Body       | file, max:10MB               | `/media` (POST)                                                                  | Single raw file binary stream                             |
| **`files`**                | Array of Files   | Form-data Body       | array, max:10                | `/media` (POST)                                                                  | Multiple files binary array                               |
| **`type`**                 | String           | Request Body / Query | in:image,document...         | `/media` (POST/GET)                                                              | Media category classification                             |
| **`isPublic`**             | Boolean          | Request Body         | boolean                      | `/media` (POST)                                                                  | Media visibility restriction                              |
| **`mediaId`**              | String (UUID)    | URL Route Parameter  | exists:media,id              | `/media/{mediaId}` (GET/DELETE/stream)                                           | Unique media instance identifier                          |
| **`page`**                 | Integer          | Query Parameter      | integer, min:1               | `/user` (GET), `/media` (GET), `/category` (GET), `/listing` (GET)               | Selected page index (Dynamic Pagination)                  |
| **`count`**                | Integer          | Query Parameter      | integer, min:1               | `/user` (GET), `/media` (GET), `/category` (GET), `/listing` (GET)               | Selected row counts per page (Dynamic Pagination)         |
| **`search`**               | String           | Query Parameter      | string                       | `/user` (GET), `/category` (GET), `/listing` (GET)                               | Multi-column partial text filter (Dynamic Searching)      |
| **`sort`**                 | String           | Query Parameter      | string                       | `/user` (GET), `/category` (GET), `/listing` (GET)                               | Select column name to order by (Dynamic Sorting)          |
| **`order`**                | String           | Query Parameter      | `asc` or `desc`              | `/user` (GET), `/category` (GET), `/listing` (GET)                               | Direction of sort order (Dynamic Sorting)                 |