{"openapi":"3.0.0","info":{"title":"4SaleBackendSkeleton API","description":"A robust Go backend API with hexagonal architecture for advertisement management","version":"1.0.0","contact":{"name":"API Support","url":"https://github.com/4SaleBackendSkeleton"},"license":{"name":"MIT"}},"servers":[{"url":"https://d142fa47-5a37-4cac-a34b-c94372c9e389-00-2tdv9fq7da3mb.spock.replit.dev","description":"Replit deployment server"},{"url":"http://localhost:8080","description":"Local development server"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API Key for authentication"},"ApiSecretAuth":{"type":"apiKey","in":"header","name":"X-API-Secret","description":"API Secret for authentication (hashed before storage)"}},"schemas":{"App":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier"},"name":{"type":"string","description":"Application name"},"api_key":{"type":"string","description":"API Key (unique)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["name","api_key"]},"Advertisement":{"type":"object","description":"Complete advertisement model matching the clas_user_adv database table","properties":{"id":{"type":"integer","format":"int64","description":"Primary key (user_adv_id)","example":8003766},"business_profile_id":{"type":"integer","format":"int64","nullable":true,"description":"Business profile ID","example":218},"cat_id":{"type":"integer","nullable":true,"description":"Category ID","example":3107},"alt_cat_id":{"type":"integer","nullable":true,"description":"Alternative category ID","example":2473},"district_id":{"type":"integer","nullable":true,"description":"District ID","example":-1},"slug":{"type":"string","nullable":true,"description":"URL-friendly slug","example":"from-me-cooper-2015"},"selling_type_id":{"type":"integer","nullable":true,"description":"Selling type ID"},"user_id":{"type":"integer","nullable":true,"description":"User ID","example":2166683},"description":{"type":"string","nullable":true,"description":"Advertisement description","example":"Mini Cooper 2015 \r\nFree Delivery + Comprehensive Insurance"},"device_id":{"type":"string","nullable":true,"description":"Device ID","example":"xxxxxxxxxx"},"phone":{"type":"string","description":"Phone number (required)","example":"96500000000"},"status":{"type":"integer","format":"int8","nullable":true,"description":"Status (0=unpublished, 1=published, 2=quarantine, 3=user purged)","example":1},"is_deleted":{"type":"integer","format":"int8","nullable":true,"description":"Deletion flag","example":0},"ad_asking_price":{"type":"number","format":"double","nullable":true,"description":"Asking price","example":5700},"language":{"type":"string","nullable":true,"description":"Language code","example":"en"},"title":{"type":"string","nullable":true,"description":"Advertisement title","example":"from me cooper 2015"},"name":{"type":"string","nullable":true,"description":"Contact name"},"username":{"type":"string","nullable":true,"description":"Username"},"created_at":{"type":"string","format":"date-time","nullable":true,"description":"Creation timestamp","example":"2018-11-20T10:45:53Z"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last update timestamp"},"add_date":{"type":"string","format":"date-time","nullable":true,"description":"Addition date","example":"2018-11-20T10:45:53Z"},"date_modified":{"type":"string","format":"date-time","nullable":true,"description":"Modification date","example":"2024-12-23T14:57:39Z"},"date_refresh":{"type":"string","format":"date-time","nullable":true,"description":"Refresh date","example":"2018-11-20T10:45:53Z"},"date_expired":{"type":"string","format":"date-time","nullable":true,"description":"Expiration date"},"images":{"type":"string","nullable":true,"description":"Comma-separated list of image URLs","example":"218-1.jpg,218-2.jpg,218-3.jpg"},"region_id":{"type":"integer","nullable":true,"description":"Region ID"},"source":{"type":"string","nullable":true,"description":"Source of the advertisement","example":"third_party_integration"}}},"CreateAdvertisementRequest":{"type":"object","properties":{"title":{"type":"string","description":"Advertisement title (required)","example":"2015 Mini Cooper S - Excellent Condition"},"phone":{"type":"string","description":"Contact phone number - used for primary contact","example":"+965 12345678"},"description":{"type":"string","description":"Detailed advertisement description","example":"Well maintained car with full service history"},"cat_id":{"type":"integer","description":"Category ID","example":3107},"region_id":{"type":"integer","description":"Region ID","example":1},"ad_asking_price":{"type":"number","format":"double","description":"Asking price","example":5700.0},"language":{"type":"string","description":"Language code (en/ar)","example":"en"},"images":{"type":"array","items":{"type":"string"},"description":"Array of image URLs or paths (will be converted to comma-separated string)","example":["car1.jpg","car2.jpg","car3.jpg"]},"summary_title":{"type":"string","description":"Short summary of the title","example":"Mini Cooper 2015"},"user_id":{"type":"integer","description":"User ID (optional - can be auto-computed for office users)","example":12345},"status":{"type":"integer","description":"Initial status (0=unpublished, 1=published)","example":1},"is_draft":{"type":"integer","description":"Draft flag (0=not draft, 1=draft)","example":0},"alt_cat_id":{"type":"integer","description":"Alternative category ID (optional)","example":2473},"contact_no":{"type":"string","description":"Alternative contact number","example":"+965 87654321"},"extra_info":{"type":"object","description":"Additional JSON data (will be stored as JSON string)","example":{"type":"personal","location_info":{"lon":0,"lat":0}}}},"required":["title"]},"CategoryResponse":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID","example":3107},"label":{"type":"string","description":"Category name","example":"Cars"},"slug":{"type":"string","description":"URL-friendly slug","example":"cars"},"parent_id":{"type":"integer","nullable":true,"description":"Parent category ID (null for root categories)","example":null},"children":{"type":"array","description":"Child categories (only present in tree mode)","items":{"$ref":"#/components/schemas/CategoryResponse"}}}},"ImageUploadResponse":{"type":"object","description":"Response for image upload operations","properties":{"status":{"type":"boolean","description":"Success status of the upload","example":true},"message":{"type":"string","description":"Result message","example":"Image uploaded successfully"},"url":{"type":"string","description":"Public URL of the uploaded image (only present on success)","example":"https://your-bucket.s3.us-east-1.amazonaws.com/uploads/2025/01/550e8400-e29b-41d4-a716-446655440000.jpg"}},"required":["status","message"]},"VideoUploadResponse":{"type":"object","description":"Response for video upload operations","properties":{"status":{"type":"boolean","description":"Success status of the upload","example":true},"message":{"type":"string","description":"Result message","example":"Video uploaded successfully"},"url":{"type":"string","description":"Public URL of the uploaded video","example":"https://media.q84sale.com/video/sample-video.mp4"},"video_caption":{"type":"string","description":"Video caption (if provided)","example":"Product demonstration video"},"video_duration":{"type":"string","description":"Video duration (if provided)","example":"2:30"},"video_thumbnail":{"type":"string","description":"URL of the video thumbnail (if provided)","example":"https://media.q84sale.com/images/thumbnails/video-thumb.jpg"}},"required":["status","message","url"]},"PDFUploadResponse":{"type":"object","description":"Response for PDF upload operations","properties":{"status":{"type":"boolean","description":"Success status of the upload","example":true},"message":{"type":"string","description":"Result message","example":"PDF uploaded successfully"},"url":{"type":"string","description":"Public URL of the uploaded PDF","example":"https://media.q84sale.com/documents/document_2025.pdf"}},"required":["status","message","url"]},"BulkUploadResponse":{"type":"object","description":"Response for bulk upload operations","properties":{"status":{"type":"boolean","description":"Overall success status (true if at least one file uploaded successfully)","example":true},"message":{"type":"string","description":"Summary of the bulk upload operation","example":"Processed 5 files: 4 successful, 1 failed"},"total":{"type":"integer","description":"Total number of files processed","example":5},"successful":{"type":"integer","description":"Number of successfully uploaded files","example":4},"failed":{"type":"integer","description":"Number of failed uploads","example":1},"results":{"type":"array","description":"Individual results for each file","items":{"$ref":"#/components/schemas/BulkUploadResult"}}},"required":["status","message","total","successful","failed","results"]},"BulkUploadResult":{"type":"object","description":"Result for a single file in bulk upload","properties":{"index":{"type":"integer","description":"Index of the file in the upload array","example":0},"filename":{"type":"string","description":"Original filename","example":"product-image.jpg"},"status":{"type":"boolean","description":"Upload success status for this file","example":true},"message":{"type":"string","description":"Result message for this file","example":"Image uploaded successfully"},"url":{"type":"string","description":"Public URL of the uploaded file (only on success)","example":"https://media.q84sale.com/images/user_adv/resize1000/abc123.jpg"},"error":{"type":"string","description":"Error code if upload failed","example":"FILE_TOO_LARGE"},"video_caption":{"type":"string","description":"Video caption (only for video uploads)","example":"Product demo"},"video_duration":{"type":"string","description":"Video duration (only for video uploads)","example":"2:30"},"video_thumbnail":{"type":"string","description":"Video thumbnail URL (only for video uploads with thumbnails)","example":"https://media.q84sale.com/images/thumbnails/abc123_thumb.jpg"}},"required":["index","filename","status","message"]},"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message describing what went wrong"}}}}},"tags":[{"name":"General","description":"General API endpoints"},{"name":"Advertisements","description":"Advertisement management operations"},{"name":"Categories","description":"Category lookup operations"},{"name":"Images","description":"Image upload and processing operations"}],"paths":{"/":{"get":{"summary":"Get API information","description":"Returns basic API information and available endpoints","tags":["General"],"responses":{"200":{"description":"API information","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"message":{"type":"string","example":"4SaleBackendSkeleton is running with Hexagonal Architecture"},"endpoints":{"type":"object"},"features":{"type":"object"},"documentation":{"type":"object"}}}}}}}}},"/health":{"get":{"summary":"Health check","description":"Returns the health status of the API","tags":["General"],"responses":{"200":{"description":"Health status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"healthy"},"database":{"type":"string","example":"connected"}}}}}}}}},"/api/v1/integration-service/advertisements":{"get":{"summary":"List advertisements","description":"Retrieve a paginated list of advertisements with optional filtering","tags":["Advertisements"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"page","in":"query","description":"Page number (1-based)","schema":{"type":"integer","default":1,"minimum":1}},{"name":"page_size","in":"query","description":"Number of items per page","schema":{"type":"integer","default":10,"minimum":1,"maximum":100}},{"name":"status","in":"query","description":"Filter by status (optional)","schema":{"type":"integer","enum":[0,1,2,3]}}],"responses":{"200":{"description":"List of advertisements","content":{"application/json":{"schema":{"type":"object","properties":{"advertisements":{"type":"array","items":{"$ref":"#/components/schemas/Advertisement"}},"total":{"type":"integer","example":100},"page":{"type":"integer","example":1},"page_size":{"type":"integer","example":10}}}}}},"401":{"description":"Unauthorized - Invalid API credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create advertisement","description":"Create a new advertisement","tags":["Advertisements"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAdvertisementRequest"}}}},"responses":{"201":{"description":"Advertisement created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Advertisement"}}}},"400":{"description":"Bad request - Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Invalid API credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration-service/advertisements/bulk-upload":{"post":{"summary":"Bulk upload advertisements","description":"Upload multiple advertisements via CSV file. The CSV must contain EXACTLY these columns (no extra columns allowed):\n- title: Advertisement title (string, required)\n- cat_id: Category ID (integer, required)\n- description: Advertisement description (string, required)\n- ad_asking_price: Asking price (decimal, required)\n- language: Language code (en/ar, required)\n- contact_no: Contact phone number (string, required)\n- images: Comma-separated image URLs (string, required)\n- product_variant_id: Product variant identifier (string, required)\n\nImportant: The CSV file will be rejected if it contains any additional columns beyond those listed above.\n\nAutomatic field computation based on authenticated app:\n- source: Always set to 'third_party_integration'\n- business_profile_id/user_id/phone: Computed based on user_type\n  - For office users: Looks up office and user data from database\n  - For other users: Uses app configuration\n- district_id/region_id: From app configuration\n- product_variant_id: Embedded in extra_info as JSON\n\nThe upload is atomic - all records must be valid or none will be saved.\n","tags":["Advertisements"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"CSV file with advertisement data"}},"required":["file"]}}}},"responses":{"200":{"description":"Bulk upload successful","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Successfully uploaded 10 advertisements"},"processed":{"type":"integer","example":10}}}}}},"400":{"description":"Bad request - CSV validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"CSV validation failed"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer","example":2},"error":{"type":"string","example":"Missing required field: title"}}}}}}}}},"401":{"description":"Unauthorized - Invalid API credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration-service/advertisements/{id}":{"get":{"summary":"Get advertisement by ID","description":"Retrieve a single advertisement by its ID","tags":["Advertisements"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Advertisement ID","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Advertisement details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Advertisement"}}}},"401":{"description":"Unauthorized - Invalid API credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Advertisement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete advertisement","description":"Delete an existing advertisement","tags":["Advertisements"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Advertisement ID","schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"Advertisement deleted successfully"},"401":{"description":"Unauthorized - Invalid API credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Advertisement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration-service/ads/expire":{"post":{"summary":"Expire advertisements","description":"Expire advertisements for the authenticated office user.\nThis endpoint is only available to apps with user_type \"office\".\n\nIf no JSON body is provided:\n- Expires all advertisements where business_profile_id matches the authenticated app's user_id\n\nIf slugs array is provided:\n- Expires only advertisements that match the provided slugs AND belong to the authenticated user\n- Ads that don't exist or belong to other users are silently skipped\n","tags":["Advertisements"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"description":"Optional request body with specific slugs to expire","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"slugs":{"type":"array","description":"Array of advertisement slugs to expire","items":{"type":"string"},"example":["ad-slug-1","ad-slug-2","ad-slug-3"]}}}}}},"responses":{"200":{"description":"Advertisements expired successfully","content":{"application/json":{"schema":{"type":"object","properties":{"expired_count":{"type":"integer","description":"Number of advertisements that were expired","example":5},"message":{"type":"string","description":"Success message","example":"Successfully expired 5 advertisement(s)"},"skipped":{"type":"array","description":"List of slugs that were not found or unauthorized (only present when slugs are provided)","items":{"type":"string"},"example":["ad-slug-3"]}}}}}},"401":{"description":"Unauthorized - Invalid API credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - Only office users can expire advertisements","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration-service/categories":{"get":{"summary":"Get categories","description":"Retrieve categories in either flat or tree structure.\n- Without 'flat' parameter or flat=false: Returns root categories with nested children\n- With flat=true: Returns all categories as a flat array\n","tags":["Categories"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"flat","in":"query","description":"Return categories as flat array instead of tree structure","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CategoryResponse"}}}}},"401":{"description":"Unauthorized - Invalid API credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration-service/upload-media":{"post":{"summary":"Upload and process media (images, videos, and PDFs) - supports single and bulk uploads","description":"Upload media files with support for images, videos, and PDF documents. Supports both single file and bulk uploads.\n\n## Single File Upload\nUse the `file` parameter to upload one file at a time:\n- **Parameters**: `file`, `video_caption`, `video_duration`, `video_thumbnail`\n- **Response**: Direct response with `status`, `message`, and `url`\n- **Example**: Upload a single image or video with optional metadata\n\n## Bulk Upload\nUse the `files[]` parameter to upload multiple files in one request:\n- **Parameters**: `files[]`, `captions[]`, `durations[]`\n- **Processing**: Concurrent uploads (up to 5 files simultaneously)\n- **Response**: Aggregate response with individual results for each file\n- **Partial Success**: Some files may succeed while others fail\n- **Metadata**: Use array indices to match metadata to files (e.g., `captions[0]` for `files[0]`)\n\n## Supported Media Types\n\n### Images\n- **Formats**: jpg, jpeg, png, gif, webp, bmp, tiff, svg, ico\n- **Max Size**: 2MB\n- **Processing**: \n  - Auto-resize to 1000px width if larger\n  - \"4SALE\" watermark added to bottom-right\n  - Uploaded to S3 with UUID filename\n- **Upload Methods**: Multipart form or JSON (base64, single file only)\n\n### Videos\n- **Formats**: All video/* MIME types (mp4, avi, mov, etc.)\n- **Max Size**: 40MB\n- **Storage**: Dual paths - `video/originals/` and `video/`\n- **Metadata**: Optional caption, duration, thumbnail\n- **Upload Method**: Multipart form only\n\n### PDFs\n- **Format**: application/pdf\n- **Max Size**: 10MB\n- **Storage**: Dual paths - `documents/originals/` and `documents/`\n- **Processing**: Filename sanitization\n- **Upload Method**: Multipart form only\n","tags":["Media"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"bucket","in":"query","description":"S3 bucket name (optional, defaults to DEFAULT_S3_BUCKET)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files[]":{"type":"array","items":{"type":"string","format":"binary"},"description":"**BULK UPLOAD** - Array of media files to upload\nUse this parameter for uploading multiple files at once.\nSupports images, videos, and PDFs in a single request.\n"},"captions[]":{"type":"array","items":{"type":"string"},"description":"**BULK UPLOAD** - Array of captions for the uploaded files\nThe array index matches the files[] array index.\nExample: captions[0] is for files[0], captions[1] is for files[1], etc.\n"},"durations[]":{"type":"array","items":{"type":"string"},"description":"**BULK UPLOAD** - Array of durations for video files\nOnly relevant for video files in the files[] array.\nFormat: \"MM:SS\" or \"HH:MM:SS\"\n"},"thumbnails[]":{"type":"array","items":{"type":"string","format":"binary"},"description":"**BULK UPLOAD** - Array of thumbnail images for video files\nThe array index matches the files[] array index.\nExample: thumbnails[0] is for files[0] if it's a video.\nOnly relevant for video files in the files[] array.\n"},"file":{"type":"string","format":"binary","description":"**SINGLE FILE UPLOAD** - Media file to upload (image, video, or PDF)\nUse this parameter for uploading a single file.\n"},"video_caption":{"type":"string","description":"**SINGLE VIDEO UPLOAD** - Caption for the video\nOnly applies when uploading a single video file.\n"},"video_duration":{"type":"string","description":"**SINGLE VIDEO UPLOAD** - Duration of the video (e.g., \"2:30\")\nOnly applies when uploading a single video file.\n"},"video_thumbnail":{"type":"string","format":"binary","description":"**SINGLE VIDEO UPLOAD** - Thumbnail image for the video\nOnly applies when uploading a single video file.\n"}}}},"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"Base64 encoded media data (images only)"}},"required":["file"]}}}},"responses":{"200":{"description":"Media uploaded successfully","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ImageUploadResponse"},{"$ref":"#/components/schemas/VideoUploadResponse"},{"$ref":"#/components/schemas/PDFUploadResponse"},{"$ref":"#/components/schemas/BulkUploadResponse"}]},"examples":{"image":{"value":{"status":true,"message":"Image uploaded successfully","url":"https://your-bucket.s3.us-east-1.amazonaws.com/uploads/2025/01/550e8400-e29b-41d4-a716-446655440000.jpg"}},"video":{"value":{"status":true,"message":"Video uploaded successfully","url":"https://media.q84sale.com/video/sample-video.mp4","video_caption":"Product demonstration","video_duration":"2:30"}},"pdf":{"value":{"status":true,"message":"PDF uploaded successfully","url":"https://media.q84sale.com/documents/document_2025.pdf"}}}}}},"400":{"description":"Bad request (invalid file, size exceeded, etc)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageUploadResponse"},"examples":{"imageSize":{"value":{"status":false,"message":"Image size exceeds maximum allowed size of 2MB"}},"videoSize":{"value":{"status":false,"message":"Video file size exceeds 40MB limit"}},"pdfSize":{"value":{"status":false,"message":"PDF file size exceeds 10MB limit"}}}}}},"401":{"description":"Unauthorized - Invalid API credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity - Unsupported file type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageUploadResponse"},"example":{"status":false,"message":"Unsupported file type. Only images, videos, and PDFs are allowed"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageUploadResponse"},"example":{"status":false,"message":"Failed to upload media: AWS credentials not configured"}}}}}}},"/api/v1/integration-service/upload-profile-photo":{"post":{"summary":"Upload a profile photo","description":"Upload a profile photo with specific resizing requirements.\n\nProcessing:\n- Images wider than 450px are resized to 450px width while maintaining aspect ratio\n- Two versions are saved:\n  - Original image (unmodified) at images/profile_images/originals/<filename>\n  - Resized image at images/profile_images/<filename>\n- Compression: JPEG quality 60, PNG compression level 5\n- No watermark added\n- No cropping\n\nAccepted formats: jpg, jpeg, png, gif, webp, bmp, tiff, svg, ico\nMaximum file size: 2MB\n","tags":["Media"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"bucket","in":"query","description":"S3 bucket name (optional, defaults to DEFAULT_S3_BUCKET)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"profile_photo":{"type":"string","format":"binary","description":"Profile photo file to upload"}},"required":["profile_photo"]}}}},"responses":{"200":{"description":"Profile photo uploaded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer","example":200},"response":{"type":"object","properties":{"image":{"type":"string","example":"https://media.q84sale.com/images/profile_images/1754214072199789939.jpg"}}}}},"example":{"status":200,"response":{"image":"https://media.q84sale.com/images/profile_images/1754214072199789939.jpg"}}}}},"400":{"description":"Bad request (no file provided, size exceeded, etc)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"File size exceeds 2MB limit"}}},"example":{"success":false,"message":"File size exceeds 2MB limit"}}}},"401":{"description":"Unauthorized - Invalid API credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to upload profile photo"}}}}}}}}}}}