{
    "swagger": "2.0",
    "info": {
        "description": "Backend API for Veza platform.",
        "title": "Veza Backend API",
        "termsOfService": "http://swagger.io/terms/",
        "contact": {
            "name": "API Support",
            "url": "http://www.veza.app/support",
            "email": "support@veza.app"
        },
        "license": {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
        },
        "version": "1.2.0"
    },
    "host": "localhost:8080",
    "basePath": "/api/v1",
    "paths": {
        "/analytics": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get aggregated analytics data for tracks and playlists",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Analytics"
                ],
                "summary": "Get Analytics Data",
                "parameters": [
                    {
                        "type": "integer",
                        "description": "Number of days (default: 30)",
                        "name": "days",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Start date (ISO 8601)",
                        "name": "start_date",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End date (ISO 8601)",
                        "name": "end_date",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "period": {
                                                    "type": "object"
                                                },
                                                "playlists": {
                                                    "type": "object"
                                                },
                                                "tracks": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/analytics/events": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Record a custom analytics event",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Analytics"
                ],
                "summary": "Record Analytics Event",
                "parameters": [
                    {
                        "description": "Event Data",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.RecordEventRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/analytics/tracks/top": {
            "get": {
                "description": "Get list of top tracks by play count, optionally filtered by date range",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Analytics"
                ],
                "summary": "Get top tracks",
                "parameters": [
                    {
                        "maximum": 100,
                        "minimum": 1,
                        "type": "integer",
                        "default": 10,
                        "description": "Number of tracks to return",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Start date filter (RFC3339 format)",
                        "name": "start_date",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End date filter (RFC3339 format)",
                        "name": "end_date",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "tracks": {
                                                    "type": "array"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/analytics/tracks/{id}": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get comprehensive analytics dashboard for a track",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Analytics"
                ],
                "summary": "Get Track Analytics Dashboard",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Track ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "dashboard": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Track not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/api/v1/logs/frontend": {
            "post": {
                "description": "Receive and store a log entry from the frontend application",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Logging"
                ],
                "summary": "Receive frontend log",
                "parameters": [
                    {
                        "description": "Frontend log entry",
                        "name": "log",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.FrontendLogRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "received": {
                                                    "type": "boolean"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Invalid log entry",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/api/v1/marketplace/download/{product_id}": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get a secure download URL for a purchased product",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Marketplace"
                ],
                "summary": "Get download URL",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Product ID",
                        "name": "product_id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": {
                                "type": "string"
                            }
                        }
                    },
                    "403": {
                        "description": "No license",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/api/v1/marketplace/orders": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get all orders for the authenticated user",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Marketplace"
                ],
                "summary": "List user orders",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/veza-backend-api_internal_core_marketplace.Order"
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Purchase products",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Marketplace"
                ],
                "summary": "Create a new order",
                "parameters": [
                    {
                        "description": "Order items",
                        "name": "order",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.CreateOrderRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_core_marketplace.Order"
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/api/v1/marketplace/orders/{id}": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get details of a specific order (only order owner can access)",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Marketplace"
                ],
                "summary": "Get order details",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Order ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_core_marketplace.Order"
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden - Not order owner",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Order not found",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/api/v1/marketplace/products": {
            "get": {
                "description": "List marketplace products with filters",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Marketplace"
                ],
                "summary": "List products",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Product status",
                        "name": "status",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Seller ID",
                        "name": "seller_id",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Search query",
                        "name": "q",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Product type (track, pack, service)",
                        "name": "type",
                        "in": "query"
                    },
                    {
                        "type": "number",
                        "description": "Minimum price",
                        "name": "min_price",
                        "in": "query"
                    },
                    {
                        "type": "number",
                        "description": "Maximum price",
                        "name": "max_price",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Page number",
                        "name": "page",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Items per page",
                        "name": "limit",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/veza-backend-api_internal_core_marketplace.Product"
                            }
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Create a product (Track, Pack, Service) for sale",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Marketplace"
                ],
                "summary": "Create a new product",
                "parameters": [
                    {
                        "description": "Product info",
                        "name": "product",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.CreateProductRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_core_marketplace.Product"
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/api/v1/marketplace/products/{id}": {
            "put": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Update product details (only seller can update)",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Marketplace"
                ],
                "summary": "Update a product",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Product ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Product updates",
                        "name": "product",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.UpdateProductRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_core_marketplace.Product"
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden - Not product owner",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Product not found",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/audit/activity": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get recent activity logs for the current user",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Audit"
                ],
                "summary": "Get user activity",
                "parameters": [
                    {
                        "type": "integer",
                        "default": 50,
                        "description": "Number of activities to return",
                        "name": "limit",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "activities": {
                                                    "type": "array"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/audit/logs": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Search and filter audit logs with pagination support. Supports filtering by action, resource, date range, IP address, and user agent.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Audit"
                ],
                "summary": "Search audit logs",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Filter by action type",
                        "name": "action",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by resource type",
                        "name": "resource",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by resource ID (UUID)",
                        "name": "resource_id",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by IP address",
                        "name": "ip_address",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by user agent",
                        "name": "user_agent",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Start date filter (YYYY-MM-DD)",
                        "name": "start_date",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End date filter (YYYY-MM-DD)",
                        "name": "end_date",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "default": 1,
                        "description": "Page number",
                        "name": "page",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "default": 20,
                        "description": "Items per page",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Offset for pagination",
                        "name": "offset",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "logs": {
                                                    "type": "array"
                                                },
                                                "pagination": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/audit/stats": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get audit statistics for the current user, optionally filtered by date range",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Audit"
                ],
                "summary": "Get audit statistics",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Start date (YYYY-MM-DD)",
                        "name": "start_date",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End date (YYYY-MM-DD)",
                        "name": "end_date",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "stats": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/auth/2fa/disable": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Disable 2FA for user (requires password confirmation)",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth"
                ],
                "summary": "Disable 2FA",
                "parameters": [
                    {
                        "description": "Password Confirmation",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.DisableTwoFactorRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Invalid password or 2FA not enabled",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/auth/2fa/setup": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Generate 2FA secret and QR code for setup",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth"
                ],
                "summary": "Setup 2FA",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/definitions/internal_handlers.SetupTwoFactorResponse"
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "2FA already enabled",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/auth/2fa/status": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get 2FA enabled status for authenticated user",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth"
                ],
                "summary": "Get 2FA Status",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "enabled": {
                                                    "type": "boolean"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/auth/2fa/verify": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Verify 2FA code and enable 2FA for user",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth"
                ],
                "summary": "Verify and Enable 2FA",
                "parameters": [
                    {
                        "description": "2FA Code",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.VerifyTwoFactorRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Invalid code",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/auth/check-username": {
            "get": {
                "description": "Check if a username is already taken",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth"
                ],
                "summary": "Check Username Availability",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Username to check",
                        "name": "username",
                        "in": "query",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "available": {
                                                    "type": "boolean"
                                                },
                                                "username": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Missing Username",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/auth/login": {
            "post": {
                "description": "Authenticate user and return access token. Refresh token is set in httpOnly cookie.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth"
                ],
                "summary": "User Login",
                "parameters": [
                    {
                        "description": "Login Credentials",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_dto.LoginRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Access token returned in body, refresh token in httpOnly cookie",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_dto.LoginResponse"
                        }
                    },
                    "400": {
                        "description": "Validation or Bad Request",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Invalid credentials",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/auth/logout": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Revoke refresh token and current session",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth"
                ],
                "summary": "Logout",
                "parameters": [
                    {
                        "description": "Refresh Token to revoke",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "type": "object",
                            "properties": {
                                "refresh_token": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success message",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/auth/me": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get profile information of the currently logged-in user",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth"
                ],
                "summary": "Get Current User",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object"
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "User not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/auth/refresh": {
            "post": {
                "description": "Get a new access token using a refresh token",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth"
                ],
                "summary": "Refresh Token",
                "parameters": [
                    {
                        "description": "Refresh Token",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_dto.RefreshRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_dto.TokenResponse"
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Invalid/Expired Refresh Token",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/auth/register": {
            "post": {
                "description": "Register a new user account",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth"
                ],
                "summary": "User Registration",
                "parameters": [
                    {
                        "description": "Registration Data",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_dto.RegisterRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_dto.RegisterResponse"
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "409": {
                        "description": "User already exists",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/auth/resend-verification": {
            "post": {
                "description": "Resend the email verification link",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth"
                ],
                "summary": "Resend Verification Email",
                "parameters": [
                    {
                        "description": "Email",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_dto.ResendVerificationRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success message",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/auth/verify-email": {
            "post": {
                "description": "Verify user email address using a token",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth"
                ],
                "summary": "Verify Email",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Verification Token",
                        "name": "token",
                        "in": "query",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success message",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "400": {
                        "description": "Invalid Token",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/chat/token": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Generate a short-lived token for chat authentication",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Chat"
                ],
                "summary": "Get Chat Token",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "token": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/comments/{id}": {
            "put": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Update a comment (only by owner)",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Comment"
                ],
                "summary": "Update comment",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Comment ID (UUID)",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Updated comment content",
                        "name": "comment",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.UpdateCommentRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "comment": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden - can only edit own comments",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Comment not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/comments/{id}/replies": {
            "get": {
                "description": "Get paginated list of replies to a comment",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Comment"
                ],
                "summary": "Get comment replies",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Parent Comment ID (UUID)",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "minimum": 1,
                        "type": "integer",
                        "default": 1,
                        "description": "Page number",
                        "name": "page",
                        "in": "query"
                    },
                    {
                        "maximum": 100,
                        "minimum": 1,
                        "type": "integer",
                        "default": 20,
                        "description": "Items per page",
                        "name": "limit",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "pagination": {
                                                    "type": "object"
                                                },
                                                "replies": {
                                                    "type": "array"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Parent comment not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/playlists": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get a paginated list of playlists",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Playlist"
                ],
                "summary": "Get Playlists",
                "parameters": [
                    {
                        "type": "integer",
                        "default": 1,
                        "description": "Page number",
                        "name": "page",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "default": 20,
                        "description": "Items per page",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by User ID",
                        "name": "user_id",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "pagination": {
                                                    "type": "object"
                                                },
                                                "playlists": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/definitions/veza-backend-api_internal_models.Playlist"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Create a new playlist",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Playlist"
                ],
                "summary": "Create Playlist",
                "parameters": [
                    {
                        "description": "Playlist Metadata",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.CreatePlaylistRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "playlist": {
                                                    "$ref": "#/definitions/veza-backend-api_internal_models.Playlist"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/playlists/{id}": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get detailed information about a playlist",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Playlist"
                ],
                "summary": "Get Playlist by ID",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Playlist ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "playlist": {
                                                    "$ref": "#/definitions/veza-backend-api_internal_models.Playlist"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Invalid ID",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Playlist not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Update playlist metadata",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Playlist"
                ],
                "summary": "Update Playlist",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Playlist ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Playlist Metadata",
                        "name": "playlist",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.UpdatePlaylistRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "playlist": {
                                                    "$ref": "#/definitions/veza-backend-api_internal_models.Playlist"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Playlist not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            },
            "delete": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Permanently delete a playlist",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Playlist"
                ],
                "summary": "Delete Playlist",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Playlist ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Playlist not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/playlists/{id}/tracks": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Add a track to the playlist",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Playlist"
                ],
                "summary": "Add Track to Playlist",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Playlist ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Track ID (in body)",
                        "name": "trackId",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "type": "object",
                            "properties": {
                                "track_id": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Track already present or invalid ID",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Playlist or Track not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/playlists/{id}/tracks/reorder": {
            "put": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Reorder tracks in the playlist",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Playlist"
                ],
                "summary": "Reorder Tracks",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Playlist ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "New Track Order",
                        "name": "order",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.ReorderTracksRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/playlists/{id}/tracks/{trackId}": {
            "delete": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Remove a track from the playlist",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Playlist"
                ],
                "summary": "Remove Track from Playlist",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Playlist ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Track ID",
                        "name": "trackId",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "404": {
                        "description": "Playlist or Track not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks": {
            "get": {
                "description": "Get a paginated list of tracks with filters",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Track"
                ],
                "summary": "List Tracks",
                "parameters": [
                    {
                        "type": "integer",
                        "default": 1,
                        "description": "Page number",
                        "name": "page",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "default": 20,
                        "description": "Items per page",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by User ID",
                        "name": "user_id",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by Genre",
                        "name": "genre",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by Format",
                        "name": "format",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "default": "created_at",
                        "description": "Sort field",
                        "name": "sort_by",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "default": "desc",
                        "description": "Sort order (asc/desc)",
                        "name": "sort_order",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "pagination": {
                                                    "type": "object"
                                                },
                                                "tracks": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/definitions/veza-backend-api_internal_models.Track"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Upload a new track (audio file)",
                "consumes": [
                    "multipart/form-data"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Track"
                ],
                "summary": "Upload Track",
                "parameters": [
                    {
                        "type": "file",
                        "description": "Audio File (MP3, WAV, FLAC, OGG)",
                        "name": "file",
                        "in": "formData",
                        "required": true
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "track": {
                                                    "$ref": "#/definitions/veza-backend-api_internal_models.Track"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "No file or validation error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Quota exceeded",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks/batch/delete": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Delete multiple tracks at once",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Track"
                ],
                "summary": "Batch Delete Tracks",
                "parameters": [
                    {
                        "description": "List of Track IDs",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_core_track.BatchDeleteRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "deleted": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                },
                                                "failed": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks/chunk": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Upload a single chunk of a file",
                "consumes": [
                    "multipart/form-data"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Track"
                ],
                "summary": "Upload Chunk",
                "parameters": [
                    {
                        "type": "file",
                        "description": "Chunk Data",
                        "name": "chunk",
                        "in": "formData",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Upload ID",
                        "name": "upload_id",
                        "in": "formData",
                        "required": true
                    },
                    {
                        "type": "integer",
                        "description": "Chunk Number",
                        "name": "chunk_number",
                        "in": "formData",
                        "required": true
                    },
                    {
                        "type": "integer",
                        "description": "Total Chunks",
                        "name": "total_chunks",
                        "in": "formData",
                        "required": true
                    },
                    {
                        "type": "integer",
                        "format": "int64",
                        "description": "Total Size",
                        "name": "total_size",
                        "in": "formData",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Filename",
                        "name": "filename",
                        "in": "formData",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                },
                                                "progress": {
                                                    "type": "number",
                                                    "format": "float64"
                                                },
                                                "received_chunks": {
                                                    "type": "integer"
                                                },
                                                "upload_id": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks/complete": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Finish upload session and assemble file",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Track"
                ],
                "summary": "Complete Chunked Upload",
                "parameters": [
                    {
                        "description": "Upload ID",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_core_track.CompleteChunkedUploadRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "md5": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                },
                                                "track": {
                                                    "$ref": "#/definitions/veza-backend-api_internal_models.Track"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation or Assemblage Error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks/initiate": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Start a new chunked upload session",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Track"
                ],
                "summary": "Initiate Chunked Upload",
                "parameters": [
                    {
                        "description": "Upload Metadata",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_core_track.InitiateChunkedUploadRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                },
                                                "upload_id": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks/quota/{id}": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get remaining upload quota for the user",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Track"
                ],
                "summary": "Get Upload Quota",
                "parameters": [
                    {
                        "type": "string",
                        "description": "User ID (optional, defaults to current user)",
                        "name": "id",
                        "in": "path"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "quota": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks/resume/{uploadId}": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get state of an interrupted upload",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Track"
                ],
                "summary": "Resume Upload",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Upload ID",
                        "name": "uploadId",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "chunks_received": {
                                                    "type": "integer"
                                                },
                                                "upload_id": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "404": {
                        "description": "Upload session not found",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks/{id}": {
            "get": {
                "description": "Get detailed information about a track",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Track"
                ],
                "summary": "Get Track by ID",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Track ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "track": {
                                                    "$ref": "#/definitions/veza-backend-api_internal_models.Track"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Invalid ID",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Track not found",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Update track metadata",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Track"
                ],
                "summary": "Update Track",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Track ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Track Metadata",
                        "name": "track",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_core_track.UpdateTrackRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "track": {
                                                    "$ref": "#/definitions/veza-backend-api_internal_models.Track"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Track not found",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            },
            "delete": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Permanently delete a track",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Track"
                ],
                "summary": "Delete Track",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Track ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Track not found",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks/{id}/analytics/plays": {
            "get": {
                "description": "Get play statistics over time for a track, grouped by time period",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Analytics"
                ],
                "summary": "Get plays over time",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Track ID (UUID)",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Start date (RFC3339 format)",
                        "name": "start_date",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End date (RFC3339 format)",
                        "name": "end_date",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "default": "day",
                        "description": "Time period grouping (hour, day, week, month)",
                        "name": "interval",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "points": {
                                                    "type": "array"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Track not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks/{id}/comments": {
            "get": {
                "description": "Get paginated list of comments for a track",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Comment"
                ],
                "summary": "Get track comments",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Track ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "integer",
                        "default": 1,
                        "description": "Page number",
                        "name": "page",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "default": 20,
                        "description": "Items per page",
                        "name": "limit",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "comments": {
                                                    "type": "array"
                                                },
                                                "pagination": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Track not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Create a new comment on a track. Can be a top-level comment or a reply to another comment (using parent_id).",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Comment"
                ],
                "summary": "Create comment",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Track ID (UUID)",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Comment data",
                        "name": "comment",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.CreateCommentRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "comment": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Track not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks/{id}/comments/{comment_id}": {
            "delete": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Delete a comment (only by owner or admin)",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Comment"
                ],
                "summary": "Delete comment",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Track ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Comment ID",
                        "name": "comment_id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden - not comment owner",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Comment not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks/{id}/play": {
            "post": {
                "description": "Record a play event for a track. Can be called anonymously or with authentication.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Analytics"
                ],
                "summary": "Record play",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Track ID (UUID)",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Play event data",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.RecordPlayRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Track not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks/{id}/stats": {
            "get": {
                "description": "Get statistics for a track (plays, likes, etc.)",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Analytics"
                ],
                "summary": "Get track statistics",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Track ID (UUID)",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "stats": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Track not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/tracks/{id}/status": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get the processing status of an uploaded track",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Track"
                ],
                "summary": "Get Upload Status",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Track ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "progress": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Invalid ID",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Track not found",
                        "schema": {
                            "$ref": "#/definitions/veza-backend-api_internal_response.APIResponse"
                        }
                    }
                }
            }
        },
        "/users": {
            "get": {
                "description": "Get a paginated list of users with optional filtering",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "User"
                ],
                "summary": "List Users",
                "parameters": [
                    {
                        "type": "integer",
                        "default": 1,
                        "description": "Page number",
                        "name": "page",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "default": 20,
                        "description": "Items per page",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by role",
                        "name": "role",
                        "in": "query"
                    },
                    {
                        "type": "boolean",
                        "description": "Filter by active status",
                        "name": "is_active",
                        "in": "query"
                    },
                    {
                        "type": "boolean",
                        "description": "Filter by verified status",
                        "name": "is_verified",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Search by username, email, first_name, last_name",
                        "name": "search",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "default": "created_at",
                        "description": "Sort field (created_at, username, email, last_login_at)",
                        "name": "sort_by",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "default": "desc",
                        "description": "Sort order (asc, desc)",
                        "name": "sort_order",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "pagination": {
                                                    "type": "object"
                                                },
                                                "users": {
                                                    "type": "array"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "500": {
                        "description": "Internal Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/users/by-username/{username}": {
            "get": {
                "description": "Get public profile information for a user by username",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "User"
                ],
                "summary": "Get Profile by Username",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Username",
                        "name": "username",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "profile": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Missing username",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "User not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/users/{id}": {
            "get": {
                "description": "Get public profile information for a user",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "User"
                ],
                "summary": "Get Profile by ID",
                "parameters": [
                    {
                        "type": "string",
                        "description": "User ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "profile": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Invalid ID",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "User not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Update user profile details",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "User"
                ],
                "summary": "Update Profile",
                "parameters": [
                    {
                        "type": "string",
                        "description": "User ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Profile Data",
                        "name": "profile",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.UpdateProfileRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "profile": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation Error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            },
            "delete": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Soft delete a user (only user owner or admin can delete)",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "User"
                ],
                "summary": "Delete user",
                "parameters": [
                    {
                        "type": "string",
                        "description": "User ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "User deleted successfully",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "400": {
                        "description": "Invalid ID",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden - Not user owner or admin",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "User not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/users/{id}/analytics/stats": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get analytics statistics for a user (total plays, tracks, etc.)",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Analytics"
                ],
                "summary": "Get user statistics",
                "parameters": [
                    {
                        "type": "string",
                        "description": "User ID (UUID)",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "stats": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden - can only view own stats",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "User not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/users/{id}/completion": {
            "get": {
                "description": "Get profile completion percentage and missing fields",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "User"
                ],
                "summary": "Get Profile Completion",
                "parameters": [
                    {
                        "type": "string",
                        "description": "User ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object"
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Invalid ID",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/webhooks": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get a list of all webhooks registered by the current user",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Webhook"
                ],
                "summary": "List webhooks",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "webhooks": {
                                                    "type": "array"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Register a new webhook for receiving events",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Webhook"
                ],
                "summary": "Register webhook",
                "parameters": [
                    {
                        "description": "Webhook registration data",
                        "name": "webhook",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "type": "object"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "webhook": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Validation error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/webhooks/stats": {
            "get": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Get statistics for webhook delivery and performance",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Webhook"
                ],
                "summary": "Get webhook statistics",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "stats": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/webhooks/{id}": {
            "delete": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Delete a webhook by ID",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Webhook"
                ],
                "summary": "Delete webhook",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Webhook ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Invalid webhook ID",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Webhook not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/webhooks/{id}/regenerate-key": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Generate a new API key for a webhook (invalidates the old one)",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Webhook"
                ],
                "summary": "Regenerate webhook API key",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Webhook ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "api_key": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Invalid webhook ID",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Webhook not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        },
        "/webhooks/{id}/test": {
            "post": {
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Send a test event to a webhook to verify it's working",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Webhook"
                ],
                "summary": "Test webhook",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Webhook ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/internal_handlers.APIResponse"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Invalid webhook ID",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    },
                    "404": {
                        "description": "Webhook not found",
                        "schema": {
                            "$ref": "#/definitions/internal_handlers.APIResponse"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "internal_core_track.BatchDeleteRequest": {
            "type": "object",
            "required": [
                "track_ids"
            ],
            "properties": {
                "track_ids": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "internal_core_track.CompleteChunkedUploadRequest": {
            "type": "object",
            "required": [
                "upload_id"
            ],
            "properties": {
                "upload_id": {
                    "type": "string"
                }
            }
        },
        "internal_core_track.InitiateChunkedUploadRequest": {
            "type": "object",
            "required": [
                "filename",
                "total_chunks",
                "total_size"
            ],
            "properties": {
                "filename": {
                    "type": "string"
                },
                "total_chunks": {
                    "type": "integer",
                    "minimum": 1
                },
                "total_size": {
                    "type": "integer",
                    "minimum": 1
                }
            }
        },
        "internal_core_track.UpdateTrackRequest": {
            "type": "object",
            "properties": {
                "album": {
                    "type": "string",
                    "maxLength": 255
                },
                "artist": {
                    "type": "string",
                    "maxLength": 255
                },
                "genre": {
                    "type": "string",
                    "maxLength": 100
                },
                "is_public": {
                    "type": "boolean"
                },
                "title": {
                    "type": "string",
                    "maxLength": 255,
                    "minLength": 1
                },
                "year": {
                    "type": "integer",
                    "maximum": 2100,
                    "minimum": 1900
                }
            }
        },
        "internal_handlers.APIResponse": {
            "type": "object",
            "properties": {
                "data": {},
                "error": {},
                "success": {
                    "type": "boolean"
                }
            }
        },
        "internal_handlers.CreateCommentRequest": {
            "type": "object",
            "required": [
                "content"
            ],
            "properties": {
                "content": {
                    "type": "string",
                    "maxLength": 5000,
                    "minLength": 1
                },
                "parent_id": {
                    "description": "Changed to *uuid.UUID",
                    "type": "string"
                }
            }
        },
        "internal_handlers.CreateOrderRequest": {
            "type": "object",
            "required": [
                "items"
            ],
            "properties": {
                "items": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "type": "object",
                        "required": [
                            "product_id"
                        ],
                        "properties": {
                            "product_id": {
                                "type": "string"
                            }
                        }
                    }
                }
            }
        },
        "internal_handlers.CreatePlaylistRequest": {
            "type": "object",
            "required": [
                "title"
            ],
            "properties": {
                "description": {
                    "type": "string",
                    "maxLength": 1000
                },
                "is_public": {
                    "type": "boolean"
                },
                "title": {
                    "type": "string",
                    "maxLength": 200,
                    "minLength": 1
                }
            }
        },
        "internal_handlers.CreateProductRequest": {
            "type": "object",
            "required": [
                "price",
                "product_type",
                "title"
            ],
            "properties": {
                "description": {
                    "type": "string",
                    "maxLength": 2000
                },
                "license_type": {
                    "type": "string",
                    "enum": [
                        "standard",
                        "exclusive",
                        "commercial"
                    ]
                },
                "price": {
                    "type": "number",
                    "minimum": 0
                },
                "product_type": {
                    "type": "string",
                    "enum": [
                        "track",
                        "pack",
                        "service"
                    ]
                },
                "title": {
                    "type": "string",
                    "maxLength": 200,
                    "minLength": 3
                },
                "track_id": {
                    "description": "UUID string",
                    "type": "string"
                }
            }
        },
        "internal_handlers.DisableTwoFactorRequest": {
            "type": "object",
            "required": [
                "password"
            ],
            "properties": {
                "password": {
                    "type": "string"
                }
            }
        },
        "internal_handlers.FrontendLogRequest": {
            "type": "object",
            "properties": {
                "context": {
                    "type": "object",
                    "additionalProperties": true
                },
                "data": {},
                "level": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "timestamp": {
                    "type": "string"
                }
            }
        },
        "internal_handlers.RecordEventRequest": {
            "type": "object",
            "required": [
                "event_name"
            ],
            "properties": {
                "event_name": {
                    "type": "string",
                    "maxLength": 100,
                    "minLength": 1
                },
                "payload": {
                    "type": "object",
                    "additionalProperties": true
                }
            }
        },
        "internal_handlers.RecordPlayRequest": {
            "type": "object",
            "required": [
                "duration"
            ],
            "properties": {
                "device": {
                    "type": "string",
                    "maxLength": 100
                },
                "duration": {
                    "type": "integer",
                    "minimum": 1
                }
            }
        },
        "internal_handlers.ReorderTracksRequest": {
            "type": "object",
            "required": [
                "track_ids"
            ],
            "properties": {
                "track_ids": {
                    "description": "Changed to []uuid.UUID",
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "internal_handlers.SetupTwoFactorResponse": {
            "type": "object",
            "properties": {
                "qr_code_url": {
                    "type": "string"
                },
                "recovery_codes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "secret": {
                    "type": "string"
                }
            }
        },
        "internal_handlers.UpdateCommentRequest": {
            "type": "object",
            "required": [
                "content"
            ],
            "properties": {
                "content": {
                    "type": "string",
                    "maxLength": 5000,
                    "minLength": 1
                }
            }
        },
        "internal_handlers.UpdatePlaylistRequest": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "maxLength": 1000
                },
                "is_public": {
                    "type": "boolean"
                },
                "title": {
                    "type": "string",
                    "maxLength": 200,
                    "minLength": 1
                }
            }
        },
        "internal_handlers.UpdateProductRequest": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "maxLength": 2000
                },
                "price": {
                    "type": "number",
                    "minimum": 0
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "draft",
                        "active",
                        "archived"
                    ]
                },
                "title": {
                    "type": "string",
                    "maxLength": 200,
                    "minLength": 3
                }
            }
        },
        "internal_handlers.UpdateProfileRequest": {
            "type": "object",
            "properties": {
                "bio": {
                    "type": "string",
                    "maxLength": 500
                },
                "birthdate": {
                    "type": "string"
                },
                "first_name": {
                    "type": "string",
                    "maxLength": 100
                },
                "gender": {
                    "type": "string",
                    "enum": [
                        "Male",
                        "Female",
                        "Other",
                        "Prefer not to say"
                    ]
                },
                "last_name": {
                    "type": "string",
                    "maxLength": 100
                },
                "location": {
                    "type": "string",
                    "maxLength": 100
                },
                "social_links": {
                    "type": "object",
                    "additionalProperties": true
                },
                "username": {
                    "type": "string",
                    "maxLength": 30,
                    "minLength": 3
                }
            }
        },
        "internal_handlers.VerifyTwoFactorRequest": {
            "type": "object",
            "required": [
                "code",
                "secret"
            ],
            "properties": {
                "code": {
                    "description": "TOTP code to verify",
                    "type": "string"
                },
                "secret": {
                    "description": "Secret from setup step",
                    "type": "string"
                }
            }
        },
        "veza-backend-api_internal_core_marketplace.LicenseType": {
            "type": "string",
            "enum": [
                "basic",
                "premium",
                "exclusive"
            ],
            "x-enum-varnames": [
                "LicenseBasic",
                "LicensePremium",
                "LicenseExclusive"
            ]
        },
        "veza-backend-api_internal_core_marketplace.Order": {
            "type": "object",
            "properties": {
                "buyer_id": {
                    "type": "string"
                },
                "created_at": {
                    "type": "string"
                },
                "currency": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "items": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/veza-backend-api_internal_core_marketplace.OrderItem"
                    }
                },
                "payment_intent": {
                    "description": "Stripe PaymentIntent ID",
                    "type": "string"
                },
                "status": {
                    "description": "pending, paid, failed, refunded",
                    "type": "string"
                },
                "total_amount": {
                    "type": "number"
                },
                "updated_at": {
                    "type": "string"
                }
            }
        },
        "veza-backend-api_internal_core_marketplace.OrderItem": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string"
                },
                "order_id": {
                    "type": "string"
                },
                "price": {
                    "type": "number"
                },
                "product_id": {
                    "type": "string"
                }
            }
        },
        "veza-backend-api_internal_core_marketplace.Product": {
            "type": "object",
            "properties": {
                "created_at": {
                    "type": "string"
                },
                "currency": {
                    "type": "string"
                },
                "description": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "license_type": {
                    "$ref": "#/definitions/veza-backend-api_internal_core_marketplace.LicenseType"
                },
                "price": {
                    "type": "number"
                },
                "product_type": {
                    "description": "\"track\", \"pack\", \"service\"",
                    "type": "string"
                },
                "seller_id": {
                    "type": "string"
                },
                "status": {
                    "$ref": "#/definitions/veza-backend-api_internal_core_marketplace.ProductStatus"
                },
                "title": {
                    "type": "string"
                },
                "track_id": {
                    "description": "Liaison optionnelle avec un Track (si ProductType == \"track\")",
                    "type": "string"
                },
                "updated_at": {
                    "type": "string"
                }
            }
        },
        "veza-backend-api_internal_core_marketplace.ProductStatus": {
            "type": "string",
            "enum": [
                "draft",
                "active",
                "archived"
            ],
            "x-enum-varnames": [
                "ProductStatusDraft",
                "ProductStatusActive",
                "ProductStatusArchived"
            ]
        },
        "veza-backend-api_internal_dto.LoginRequest": {
            "type": "object",
            "required": [
                "email",
                "password"
            ],
            "properties": {
                "email": {
                    "type": "string"
                },
                "password": {
                    "type": "string"
                },
                "remember_me": {
                    "type": "boolean"
                }
            }
        },
        "veza-backend-api_internal_dto.LoginResponse": {
            "type": "object",
            "properties": {
                "requires_2fa": {
                    "description": "BE-API-001: Flag indicating 2FA is required",
                    "type": "boolean"
                },
                "token": {
                    "$ref": "#/definitions/veza-backend-api_internal_dto.TokenResponse"
                },
                "user": {
                    "$ref": "#/definitions/veza-backend-api_internal_dto.UserResponse"
                }
            }
        },
        "veza-backend-api_internal_dto.RefreshRequest": {
            "type": "object",
            "required": [
                "refresh_token"
            ],
            "properties": {
                "refresh_token": {
                    "type": "string"
                }
            }
        },
        "veza-backend-api_internal_dto.RegisterRequest": {
            "type": "object",
            "required": [
                "email",
                "password",
                "password_confirmation"
            ],
            "properties": {
                "email": {
                    "type": "string"
                },
                "password": {
                    "type": "string",
                    "minLength": 12
                },
                "password_confirmation": {
                    "type": "string"
                },
                "username": {
                    "type": "string",
                    "maxLength": 50,
                    "minLength": 3
                }
            }
        },
        "veza-backend-api_internal_dto.RegisterResponse": {
            "type": "object",
            "properties": {
                "token": {
                    "$ref": "#/definitions/veza-backend-api_internal_dto.TokenResponse"
                },
                "user": {
                    "$ref": "#/definitions/veza-backend-api_internal_dto.UserResponse"
                }
            }
        },
        "veza-backend-api_internal_dto.ResendVerificationRequest": {
            "type": "object",
            "required": [
                "email"
            ],
            "properties": {
                "email": {
                    "type": "string"
                }
            }
        },
        "veza-backend-api_internal_dto.TokenResponse": {
            "type": "object",
            "properties": {
                "access_token": {
                    "type": "string"
                },
                "expires_in": {
                    "type": "integer"
                },
                "refresh_token": {
                    "type": "string"
                }
            }
        },
        "veza-backend-api_internal_dto.UserResponse": {
            "type": "object",
            "properties": {
                "email": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "username": {
                    "type": "string"
                }
            }
        },
        "veza-backend-api_internal_models.Playlist": {
            "type": "object",
            "properties": {
                "collaborators": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/veza-backend-api_internal_models.PlaylistCollaborator"
                    }
                },
                "cover_url": {
                    "type": "string"
                },
                "created_at": {
                    "type": "string"
                },
                "description": {
                    "type": "string"
                },
                "follower_count": {
                    "type": "integer"
                },
                "id": {
                    "type": "string"
                },
                "is_public": {
                    "type": "boolean"
                },
                "title": {
                    "type": "string"
                },
                "track_count": {
                    "type": "integer"
                },
                "tracks": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/veza-backend-api_internal_models.PlaylistTrack"
                    }
                },
                "updated_at": {
                    "type": "string"
                },
                "user_id": {
                    "type": "string"
                }
            }
        },
        "veza-backend-api_internal_models.PlaylistCollaborator": {
            "type": "object",
            "properties": {
                "created_at": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "permission": {
                    "$ref": "#/definitions/veza-backend-api_internal_models.PlaylistPermission"
                },
                "playlist_id": {
                    "type": "string"
                },
                "updated_at": {
                    "type": "string"
                },
                "user": {
                    "$ref": "#/definitions/veza-backend-api_internal_models.User"
                },
                "user_id": {
                    "type": "string"
                }
            }
        },
        "veza-backend-api_internal_models.PlaylistPermission": {
            "type": "string",
            "enum": [
                "read",
                "write",
                "admin"
            ],
            "x-enum-varnames": [
                "PlaylistPermissionRead",
                "PlaylistPermissionWrite",
                "PlaylistPermissionAdmin"
            ]
        },
        "veza-backend-api_internal_models.PlaylistTrack": {
            "type": "object",
            "properties": {
                "added_at": {
                    "type": "string"
                },
                "added_by": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "playlist_id": {
                    "type": "string"
                },
                "position": {
                    "type": "integer"
                },
                "track": {
                    "$ref": "#/definitions/veza-backend-api_internal_models.Track"
                },
                "track_id": {
                    "type": "string"
                }
            }
        },
        "veza-backend-api_internal_models.Track": {
            "type": "object",
            "properties": {
                "album": {
                    "type": "string"
                },
                "artist": {
                    "type": "string"
                },
                "bitrate": {
                    "description": "kbps",
                    "type": "integer"
                },
                "cover_art_path": {
                    "type": "string"
                },
                "created_at": {
                    "type": "string"
                },
                "creator_id": {
                    "type": "string"
                },
                "duration": {
                    "description": "seconds",
                    "type": "integer"
                },
                "file_id": {
                    "description": "NULL temporairement avant création fichier",
                    "type": "string"
                },
                "file_path": {
                    "type": "string"
                },
                "file_size": {
                    "description": "bytes",
                    "type": "integer"
                },
                "format": {
                    "description": "mp3, flac, wav, etc.",
                    "type": "string"
                },
                "genre": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "is_public": {
                    "type": "boolean"
                },
                "like_count": {
                    "type": "integer"
                },
                "play_count": {
                    "type": "integer"
                },
                "sample_rate": {
                    "description": "Hz",
                    "type": "integer"
                },
                "status": {
                    "$ref": "#/definitions/veza-backend-api_internal_models.TrackStatus"
                },
                "status_message": {
                    "type": "string"
                },
                "stream_manifest_url": {
                    "type": "string"
                },
                "stream_status": {
                    "description": "pending, processing, ready, error",
                    "type": "string"
                },
                "title": {
                    "type": "string"
                },
                "updated_at": {
                    "type": "string"
                },
                "waveform_path": {
                    "type": "string"
                },
                "year": {
                    "type": "integer"
                }
            }
        },
        "veza-backend-api_internal_models.TrackStatus": {
            "type": "string",
            "enum": [
                "uploading",
                "processing",
                "completed",
                "failed"
            ],
            "x-enum-varnames": [
                "TrackStatusUploading",
                "TrackStatusProcessing",
                "TrackStatusCompleted",
                "TrackStatusFailed"
            ]
        },
        "veza-backend-api_internal_models.User": {
            "type": "object",
            "properties": {
                "avatar": {
                    "type": "string"
                },
                "bio": {
                    "type": "string"
                },
                "birthdate": {
                    "type": "string"
                },
                "created_at": {
                    "type": "string"
                },
                "email": {
                    "type": "string"
                },
                "first_name": {
                    "type": "string"
                },
                "gender": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "is_active": {
                    "type": "boolean"
                },
                "is_admin": {
                    "type": "boolean"
                },
                "is_banned": {
                    "type": "boolean"
                },
                "is_public": {
                    "type": "boolean"
                },
                "is_verified": {
                    "type": "boolean"
                },
                "last_login_at": {
                    "type": "string"
                },
                "last_name": {
                    "type": "string"
                },
                "location": {
                    "type": "string"
                },
                "login_count": {
                    "type": "integer"
                },
                "password": {
                    "description": "Virtual field for input",
                    "type": "string"
                },
                "role": {
                    "type": "string"
                },
                "slug": {
                    "type": "string"
                },
                "social_links": {
                    "type": "string"
                },
                "token_version": {
                    "type": "integer"
                },
                "updated_at": {
                    "type": "string"
                },
                "username": {
                    "type": "string"
                },
                "username_changed_at": {
                    "type": "string"
                }
            }
        },
        "veza-backend-api_internal_response.APIResponse": {
            "type": "object",
            "properties": {
                "data": {},
                "error": {},
                "success": {
                    "type": "boolean"
                }
            }
        }
    },
    "securityDefinitions": {
        "BearerAuth": {
            "description": "Type \"Bearer\" followed by a space and JWT token.",
            "type": "apiKey",
            "name": "Authorization",
            "in": "header"
        }
    }
}