{
    "openapi": "3.0.0",
    "info": {
        "title": "FileRise API",
        "version": "3.3.2"
    },
    "servers": [
        {
            "url": "/",
            "description": "Same-origin server"
        }
    ],
    "paths": {
        "/api/admin/acl/getGrants.php": {
            "get": {
                "tags": [
                    "Admin"
                ],
                "summary": "Get ACL grants for a user",
                "description": "Returns explicit and inherited folder grants for a user.",
                "operationId": "adminGetAclGrants",
                "parameters": [
                    {
                        "name": "user",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "johndoe"
                    },
                    {
                        "name": "sourceId",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "local"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Grants map",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "grants": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid user"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/acl/saveGrants.php": {
            "post": {
                "tags": [
                    "Admin"
                ],
                "summary": "Save ACL grants",
                "description": "Saves per-folder ACL grants for one user or a batch of users.",
                "operationId": "adminSaveAclGrants",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "oneOf": [
                                    {
                                        "required": [
                                            "user",
                                            "grants"
                                        ],
                                        "properties": {
                                            "user": {
                                                "type": "string",
                                                "example": "johndoe"
                                            },
                                            "sourceId": {
                                                "type": "string",
                                                "example": "local"
                                            },
                                            "grants": {
                                                "description": "Map of folder -> capabilities",
                                                "type": "object"
                                            }
                                        },
                                        "type": "object"
                                    },
                                    {
                                        "required": [
                                            "changes"
                                        ],
                                        "properties": {
                                            "sourceId": {
                                                "type": "string",
                                                "example": "local"
                                            },
                                            "changes": {
                                                "type": "array",
                                                "items": {
                                                    "required": [
                                                        "user",
                                                        "grants"
                                                    ],
                                                    "properties": {
                                                        "user": {
                                                            "type": "string",
                                                            "example": "johndoe"
                                                        },
                                                        "grants": {
                                                            "type": "object"
                                                        }
                                                    },
                                                    "type": "object"
                                                }
                                            }
                                        },
                                        "type": "object"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Save result (model-defined JSON)"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Invalid CSRF token"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/addUser.php": {
            "post": {
                "tags": [
                    "Users"
                ],
                "summary": "Add a new user",
                "description": "Adds a new user to the system. In setup mode (setup=1 with no users), auth/CSRF is not required and the new user is automatically made admin.",
                "operationId": "addUser",
                "parameters": [
                    {
                        "name": "setup",
                        "in": "query",
                        "description": "Use setup=1 to enable first-run bootstrap",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "description": "Required outside setup mode",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "username",
                                    "password"
                                ],
                                "properties": {
                                    "username": {
                                        "type": "string",
                                        "example": "johndoe"
                                    },
                                    "password": {
                                        "type": "string",
                                        "example": "securepassword"
                                    },
                                    "isAdmin": {
                                        "type": "boolean",
                                        "example": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "User added successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "string",
                                            "example": "User added successfully"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "405": {
                        "description": "Method not allowed"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/changeUserPassword.php": {
            "post": {
                "tags": [
                    "Admin"
                ],
                "summary": "Admin reset user password",
                "description": "Resets a user's password (admin only).",
                "operationId": "adminChangeUserPassword",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "username",
                                    "newPassword"
                                ],
                                "properties": {
                                    "username": {
                                        "type": "string",
                                        "example": "johndoe"
                                    },
                                    "newPassword": {
                                        "type": "string",
                                        "example": "newpass123"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Password updated"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/clamavTest.php": {
            "post": {
                "tags": [
                    "Admin"
                ],
                "summary": "Run ClamAV connectivity test",
                "description": "Runs a test scan of a temporary file and returns engine info.",
                "operationId": "adminClamavTest",
                "responses": {
                    "200": {
                        "description": "Test result",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "command": {
                                            "type": "string"
                                        },
                                        "engine": {
                                            "type": "string",
                                            "nullable": true
                                        },
                                        "details": {
                                            "type": "string"
                                        },
                                        "error": {
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/diskUsageDeleteSnapshot.php": {
            "post": {
                "tags": [
                    "Admin"
                ],
                "summary": "Delete disk usage snapshot",
                "description": "Deletes the cached disk usage snapshot file.",
                "operationId": "adminDiskUsageDeleteSnapshot",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "sourceId": {
                                        "type": "string",
                                        "example": "local"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Snapshot deleted"
                    },
                    "400": {
                        "description": "CSRF mismatch"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/diskUsageSummary.php": {
            "get": {
                "tags": [
                    "Admin"
                ],
                "summary": "Get disk usage snapshot summary",
                "description": "Returns snapshot summary and optional scan log tail.",
                "operationId": "adminDiskUsageSummary",
                "parameters": [
                    {
                        "name": "topFolders",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 5
                    },
                    {
                        "name": "topFiles",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 0
                        },
                        "example": 0
                    },
                    {
                        "name": "sourceId",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Summary payload"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "404": {
                        "description": "Snapshot not found"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/diskUsageTriggerScan.php": {
            "post": {
                "tags": [
                    "Admin"
                ],
                "summary": "Trigger disk usage scan",
                "description": "Starts a background disk usage scan to build a new snapshot.",
                "operationId": "adminDiskUsageTriggerScan",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "sourceId": {
                                        "type": "string",
                                        "example": "local"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Scan started"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/downloadProBundle.php": {
            "post": {
                "tags": [
                    "Admin"
                ],
                "summary": "Download and install latest Pro bundle",
                "description": "Downloads the latest FileRise Pro bundle from filerise.net and installs it.",
                "operationId": "adminDownloadProBundle",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Install result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "413": {
                        "description": "Bundle too large"
                    },
                    "502": {
                        "description": "Remote download failed"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/getConfig.php": {
            "get": {
                "tags": [
                    "Admin"
                ],
                "summary": "Get UI configuration",
                "description": "Returns a public subset for everyone; authenticated admins receive additional loginOptions fields.",
                "operationId": "getAdminConfig",
                "responses": {
                    "200": {
                        "description": "Configuration loaded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/AdminGetConfigPublic"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AdminGetConfigAdmin"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error"
                    }
                }
            }
        },
        "/api/admin/getUsers.php": {
            "get": {
                "tags": [
                    "Users"
                ],
                "summary": "Retrieve a list of users",
                "description": "Returns a JSON array of users. Only available to authenticated admin users.",
                "operationId": "getUsers",
                "responses": {
                    "200": {
                        "description": "Successful response with an array of users",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "properties": {
                                            "username": {
                                                "type": "string",
                                                "example": "johndoe"
                                            },
                                            "role": {
                                                "type": "string",
                                                "example": "admin"
                                            }
                                        },
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized: the user is not authenticated or is not an admin"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/installProBundle.php": {
            "post": {
                "tags": [
                    "Admin"
                ],
                "summary": "Install Pro bundle",
                "description": "Uploads and installs a FileRise Pro bundle zip.",
                "operationId": "adminInstallProBundle",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "required": [
                                    "bundle"
                                ],
                                "properties": {
                                    "bundle": {
                                        "type": "string",
                                        "format": "binary"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Install result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "413": {
                        "description": "Bundle too large"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/oidcDebugInfo.php": {
            "get": {
                "tags": [
                    "Admin"
                ],
                "summary": "Get OIDC debug info",
                "description": "Returns OIDC diagnostics for admins.",
                "operationId": "adminOidcDebugInfo",
                "responses": {
                    "200": {
                        "description": "Debug info"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/oidcTest.php": {
            "post": {
                "tags": [
                    "Admin"
                ],
                "summary": "Test OIDC discovery",
                "description": "Fetches the discovery document for a provider URL.",
                "operationId": "adminOidcTest",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "providerUrl": {
                                        "type": "string",
                                        "example": "https://issuer.example.com"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Discovery result"
                    },
                    "500": {
                        "description": "Server error"
                    }
                }
            }
        },
        "/api/admin/readMetadata.php": {
            "get": {
                "tags": [
                    "Admin"
                ],
                "summary": "Read share metadata JSON",
                "description": "Admin-only: returns the cleaned metadata for file or folder share links.",
                "operationId": "readMetadata",
                "parameters": [
                    {
                        "name": "file",
                        "in": "query",
                        "description": "Which metadata file to read",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "share_links.json",
                                "share_folder_links.json"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ShareLinksMap"
                                        },
                                        {
                                            "$ref": "#/components/schemas/ShareFolderLinksMap"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid file param"
                    },
                    "403": {
                        "description": "Forbidden (admin only)"
                    },
                    "500": {
                        "description": "Corrupted JSON"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/removeUser.php": {
            "delete": {
                "tags": [
                    "Users"
                ],
                "summary": "Remove a user",
                "description": "Removes the specified user from the system. Cannot remove the currently logged-in user. Accepts DELETE or POST.",
                "operationId": "removeUser",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "username"
                                ],
                                "properties": {
                                    "username": {
                                        "type": "string",
                                        "example": "johndoe"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "User removed successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "string",
                                            "example": "User removed successfully"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Invalid CSRF token"
                    },
                    "405": {
                        "description": "Method not allowed"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/resumableCleanup.php": {
            "post": {
                "tags": [
                    "Admin"
                ],
                "summary": "Run resumable upload cleanup sweep",
                "description": "Deletes expired resumable upload temp folders using the configured TTL.",
                "operationId": "adminResumableCleanup",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "all": {
                                        "description": "Sweep all sources when supported",
                                        "type": "boolean",
                                        "example": true
                                    },
                                    "purgeAll": {
                                        "description": "Remove all resumable temp folders, ignoring TTL",
                                        "type": "boolean",
                                        "example": true
                                    },
                                    "sourceId": {
                                        "description": "Optional source id to sweep",
                                        "type": "string",
                                        "example": "local"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Cleanup results",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "checked": {
                                            "type": "integer",
                                            "example": 12
                                        },
                                        "removed": {
                                            "type": "integer",
                                            "example": 3
                                        },
                                        "remaining": {
                                            "type": "integer",
                                            "example": 2
                                        },
                                        "sources": {
                                            "type": "integer",
                                            "example": 1
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": [],
                        "CsrfHeader": []
                    }
                ]
            }
        },
        "/api/admin/setEncryptionKey.php": {
            "post": {
                "tags": [
                    "Admin"
                ],
                "summary": "Configure encryption master key",
                "description": "Generates or clears the encryption master key file.",
                "operationId": "adminSetEncryptionKey",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "action"
                                ],
                                "properties": {
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "generate",
                                            "clear"
                                        ]
                                    },
                                    "force": {
                                        "type": "boolean",
                                        "example": false
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Operation result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/setLicense.php": {
            "post": {
                "tags": [
                    "Admin"
                ],
                "summary": "Set Pro license key",
                "description": "Stores the FileRise Pro license key.",
                "operationId": "adminSetLicense",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "license"
                                ],
                                "properties": {
                                    "license": {
                                        "type": "string",
                                        "example": "FRPRO-XXXX-XXXX"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "License stored"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/updateConfig.php": {
            "put": {
                "tags": [
                    "Admin"
                ],
                "summary": "Update admin configuration",
                "description": "Merges the provided settings into the on-disk configuration and persists them. Requires an authenticated admin session and a valid CSRF token. When OIDC is enabled (disableOIDCLogin=false), `providerUrl`, `redirectUri`, and `clientId` are required and must be HTTPS (HTTP allowed only for localhost).",
                "operationId": "updateAdminConfig",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/AdminUpdateConfigRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Configuration updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SimpleSuccess"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation error (e.g., bad authHeaderName, missing OIDC fields when enabled, or negative upload limit)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SimpleError"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Unauthorized access or invalid CSRF token",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SimpleError"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Server error while loading or saving configuration",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SimpleError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "cookieAuth": [],
                        "CsrfHeader": []
                    }
                ]
            }
        },
        "/api/admin/updateUserPermissions.php": {
            "put": {
                "tags": [
                    "Users"
                ],
                "summary": "Update user permissions",
                "description": "Updates permissions for users. Only available to authenticated admin users. Accepts PUT or POST.",
                "operationId": "updateUserPermissions",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "permissions"
                                ],
                                "properties": {
                                    "permissions": {
                                        "type": "array",
                                        "items": {
                                            "properties": {
                                                "username": {
                                                    "type": "string",
                                                    "example": "johndoe"
                                                },
                                                "folderOnly": {
                                                    "type": "boolean",
                                                    "example": true
                                                },
                                                "readOnly": {
                                                    "type": "boolean",
                                                    "example": false
                                                },
                                                "disableUpload": {
                                                    "type": "boolean",
                                                    "example": false
                                                }
                                            },
                                            "type": "object"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "User permissions updated successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "string",
                                            "example": "User permissions updated successfully."
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Invalid CSRF token"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "400": {
                        "description": "Bad Request"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/admin/virusLog.php": {
            "get": {
                "tags": [
                    "Admin"
                ],
                "summary": "Fetch virus detections log",
                "description": "Returns virus detections as JSON or CSV (Pro only).",
                "operationId": "adminVirusLog",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 200
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "json",
                                "csv"
                            ]
                        },
                        "example": "json"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Log entries or CSV"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/auth/auth.php": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Authenticate user",
                "description": "Handles user authentication via OIDC or form-based credentials. For OIDC flows, processes callbacks; otherwise, performs standard authentication with optional TOTP verification.",
                "operationId": "authUser",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "username",
                                    "password"
                                ],
                                "properties": {
                                    "username": {
                                        "type": "string",
                                        "example": "johndoe"
                                    },
                                    "password": {
                                        "type": "string",
                                        "example": "secretpassword"
                                    },
                                    "remember_me": {
                                        "type": "boolean",
                                        "example": true
                                    },
                                    "totp_code": {
                                        "type": "string",
                                        "example": "123456"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Login successful; returns user info and status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "ok"
                                        },
                                        "success": {
                                            "type": "string",
                                            "example": "Login successful"
                                        },
                                        "username": {
                                            "type": "string",
                                            "example": "johndoe"
                                        },
                                        "isAdmin": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request (e.g., missing credentials)"
                    },
                    "401": {
                        "description": "Unauthorized (e.g., invalid credentials, too many attempts)"
                    },
                    "429": {
                        "description": "Too many failed login attempts"
                    }
                }
            }
        },
        "/api/auth/checkAuth.php": {
            "get": {
                "tags": [
                    "Auth"
                ],
                "summary": "Check authentication status",
                "operationId": "checkAuth",
                "responses": {
                    "200": {
                        "description": "Authenticated status or setup flag",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "properties": {
                                                "authenticated": {
                                                    "type": "boolean",
                                                    "example": true
                                                },
                                                "isAdmin": {
                                                    "type": "boolean",
                                                    "example": true
                                                },
                                                "totp_enabled": {
                                                    "type": "boolean",
                                                    "example": false
                                                },
                                                "username": {
                                                    "type": "string",
                                                    "example": "johndoe"
                                                },
                                                "folderOnly": {
                                                    "type": "boolean",
                                                    "example": false
                                                }
                                            },
                                            "type": "object"
                                        },
                                        {
                                            "properties": {
                                                "setup": {
                                                    "type": "boolean",
                                                    "example": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/auth/login_basic.php": {
            "get": {
                "tags": [
                    "Auth"
                ],
                "summary": "Authenticate using HTTP Basic Authentication",
                "description": "Performs HTTP Basic authentication. If credentials are missing, sends a 401 response prompting for Basic auth. On valid credentials, optionally handles TOTP verification and finalizes session login.",
                "operationId": "loginBasic",
                "responses": {
                    "200": {
                        "description": "Login successful; redirects to index.html",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "string",
                                            "example": "Login successful"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized due to missing credentials or invalid credentials."
                    },
                    "429": {
                        "description": "Too many failed login attempts."
                    }
                }
            }
        },
        "/api/auth/logout.php": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Logout user",
                "description": "Clears the session, removes persistent login tokens, and redirects the user to the login page.",
                "operationId": "logoutUser",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "302": {
                        "description": "Redirects to the login page with a logout flag."
                    },
                    "401": {
                        "description": "Unauthorized"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/auth/token.php": {
            "get": {
                "tags": [
                    "Auth"
                ],
                "summary": "Retrieve CSRF token and share URL",
                "description": "Returns the current CSRF token along with the configured share URL.",
                "operationId": "getToken",
                "responses": {
                    "200": {
                        "description": "CSRF token and share URL",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "csrf_token": {
                                            "type": "string",
                                            "example": "0123456789abcdef..."
                                        },
                                        "share_url": {
                                            "type": "string",
                                            "example": "https://yourdomain.com/share.php"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/file/copyFiles.php": {
            "post": {
                "tags": [
                    "Files"
                ],
                "summary": "Copy files between folders",
                "description": "Requires read access on source and write access on destination. Enforces folder scope and ownership.",
                "operationId": "copyFiles",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "description": "CSRF token from the current session",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "source",
                                    "destination",
                                    "files"
                                ],
                                "properties": {
                                    "source": {
                                        "type": "string",
                                        "example": "root"
                                    },
                                    "destination": {
                                        "type": "string",
                                        "example": "userA/projects"
                                    },
                                    "files": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "report.pdf",
                                            "notes.txt"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Copy result (model-defined)"
                    },
                    "400": {
                        "description": "Invalid request or folder name"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/createFile.php": {
            "post": {
                "tags": [
                    "Files"
                ],
                "summary": "Create an empty file",
                "description": "Requires write access on the target folder. Enforces folder-only scope.",
                "operationId": "createFile",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder",
                                    "name"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "root"
                                    },
                                    "name": {
                                        "type": "string",
                                        "example": "new.txt"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Creation result (model-defined)"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/createShareLink.php": {
            "post": {
                "tags": [
                    "Shares"
                ],
                "summary": "Create a share link for a file",
                "description": "Requires share permission on the folder. Non-admins must own the file unless bypassOwnership.",
                "operationId": "createShareLink",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder",
                                    "file"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "root"
                                    },
                                    "file": {
                                        "type": "string",
                                        "example": "invoice.pdf"
                                    },
                                    "expirationValue": {
                                        "type": "integer",
                                        "example": 60
                                    },
                                    "expirationUnit": {
                                        "type": "string",
                                        "enum": [
                                            "seconds",
                                            "minutes",
                                            "hours",
                                            "days"
                                        ],
                                        "example": "minutes"
                                    },
                                    "password": {
                                        "type": "string",
                                        "example": ""
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Share link created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "token": {
                                            "type": "string",
                                            "example": "abc123"
                                        },
                                        "url": {
                                            "type": "string",
                                            "example": "/api/file/share.php?token=abc123"
                                        },
                                        "expires": {
                                            "type": "integer",
                                            "example": 1700000000
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/deleteFiles.php": {
            "post": {
                "tags": [
                    "Files"
                ],
                "summary": "Delete files to Trash",
                "description": "Requires write access on the folder and (for non-admins) ownership of the files.",
                "operationId": "deleteFiles",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder",
                                    "files"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "root"
                                    },
                                    "files": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "old.docx",
                                            "draft.md"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Delete result (model-defined)"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/deleteShareLink.php": {
            "post": {
                "tags": [
                    "Shares"
                ],
                "summary": "Delete a share link by token",
                "description": "Deletes a share token. Requires an authenticated admin session and a valid CSRF token.",
                "operationId": "deleteShareLink",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "required": [
                                    "token"
                                ],
                                "properties": {
                                    "token": {
                                        "type": "string",
                                        "example": "abc123"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Deletion result (success or not found)"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/deleteTrashFiles.php": {
            "post": {
                "tags": [
                    "Trash"
                ],
                "summary": "Permanently delete Trash items (admin only)",
                "operationId": "deleteTrashFiles",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "oneOf": [
                                    {
                                        "required": [
                                            "deleteAll"
                                        ],
                                        "properties": {
                                            "deleteAll": {
                                                "type": "boolean",
                                                "example": true
                                            }
                                        },
                                        "type": "object"
                                    },
                                    {
                                        "required": [
                                            "files"
                                        ],
                                        "properties": {
                                            "files": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                },
                                                "example": [
                                                    "trash/abc",
                                                    "trash/def"
                                                ]
                                            }
                                        },
                                        "type": "object"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Deletion result (model-defined)"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Admin only"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/download.php": {
            "get": {
                "tags": [
                    "Files"
                ],
                "summary": "Download a file",
                "description": "Requires view access (or own-only with ownership). Streams the file with appropriate Content-Type.",
                "operationId": "downloadFile",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "root"
                    },
                    {
                        "name": "file",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "photo.jpg"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Binary file",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid folder/file"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Not found"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/downloadZip.php": {
            "post": {
                "tags": [
                    "Files"
                ],
                "summary": "Queue an archive download",
                "description": "Queues a background archive build. Requires view access (or own-only with ownership). May be gated by account flag.",
                "operationId": "downloadZip",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder",
                                    "files"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "root"
                                    },
                                    "files": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "a.jpg",
                                            "b.png"
                                        ]
                                    },
                                    "format": {
                                        "description": "Archive format",
                                        "type": "string",
                                        "enum": [
                                            "zip",
                                            "7z"
                                        ],
                                        "example": "zip"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Archive job queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "token": {
                                            "type": "string"
                                        },
                                        "statusUrl": {
                                            "type": "string"
                                        },
                                        "downloadUrl": {
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/downloadZipFile.php": {
            "get": {
                "tags": [
                    "Files"
                ],
                "summary": "Download a finished archive by token",
                "description": "Streams the archive once; token is one-shot.",
                "operationId": "downloadZipFile",
                "parameters": [
                    {
                        "name": "k",
                        "in": "query",
                        "description": "Job token",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "name",
                        "in": "query",
                        "description": "Suggested filename",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Archive stream"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "404": {
                        "description": "Not found"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/extractZip.php": {
            "post": {
                "tags": [
                    "Files"
                ],
                "summary": "Extract archive file(s) into a folder",
                "description": "Supports ZIP/7Z and RAR extraction via server tools. Requires write access on the target folder.",
                "operationId": "extractZip",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder",
                                    "files"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "root"
                                    },
                                    "files": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "archive.zip",
                                            "archive.7z"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Extraction result (model-defined)"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/getFileList.php": {
            "get": {
                "tags": [
                    "Files"
                ],
                "summary": "List files in a folder",
                "description": "Requires view access (full) or read_own (own-only results).",
                "operationId": "getFileList",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "root"
                    },
                    {
                        "name": "sourceId",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "local"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Listing result (model-defined JSON)"
                    },
                    "400": {
                        "description": "Invalid folder"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/getFileTag.php": {
            "get": {
                "tags": [
                    "Tags"
                ],
                "summary": "Get global file tags",
                "description": "Returns tag metadata for the authenticated session.",
                "operationId": "getFileTag",
                "parameters": [
                    {
                        "name": "sourceId",
                        "in": "query",
                        "description": "Optional source id (Pro sources).",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Tags map (model-defined JSON)"
                    }
                }
            }
        },
        "/api/file/getShareLinks.php": {
            "get": {
                "tags": [
                    "Shares"
                ],
                "summary": "Get (raw) share links file",
                "description": "Returns the full share links JSON. Requires an authenticated admin session.",
                "operationId": "getShareLinks",
                "responses": {
                    "200": {
                        "description": "Share links (model-defined JSON)"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/getTrashItems.php": {
            "get": {
                "tags": [
                    "Trash"
                ],
                "summary": "List items in Trash (admin only)",
                "operationId": "getTrashItems",
                "responses": {
                    "200": {
                        "description": "Trash contents (model-defined JSON)"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Admin only"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/moveFiles.php": {
            "post": {
                "tags": [
                    "Files"
                ],
                "operationId": "moveFiles",
                "requestBody": {
                    "$ref": "#/components/requestBodies/MoveFilesRequest"
                },
                "responses": {
                    "200": {
                        "description": "Moved"
                    },
                    "400": {
                        "description": "Bad Request"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/renameFile.php": {
            "put": {
                "tags": [
                    "Files"
                ],
                "summary": "Rename a file",
                "description": "Requires write access; non-admins must own the file.",
                "operationId": "renameFile",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder",
                                    "oldName",
                                    "newName"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "root"
                                    },
                                    "oldName": {
                                        "type": "string",
                                        "example": "old.pdf"
                                    },
                                    "newName": {
                                        "type": "string",
                                        "example": "new.pdf"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Rename result (model-defined)"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/restoreFiles.php": {
            "post": {
                "tags": [
                    "Trash"
                ],
                "summary": "Restore files from Trash (admin only)",
                "operationId": "restoreFiles",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "files"
                                ],
                                "properties": {
                                    "files": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "trash/12345.json"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Restore result (model-defined)"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Admin only"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/saveFile.php": {
            "put": {
                "tags": [
                    "Files"
                ],
                "summary": "Create or overwrite a file’s content",
                "description": "Requires write access. Overwrite enforces ownership for non-admins. Certain executable extensions are denied.",
                "operationId": "saveFile",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder",
                                    "fileName",
                                    "content"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "root"
                                    },
                                    "fileName": {
                                        "type": "string",
                                        "example": "readme.txt"
                                    },
                                    "content": {
                                        "type": "string",
                                        "example": "Hello world"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Save result (model-defined)"
                    },
                    "400": {
                        "description": "Invalid input or disallowed extension"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/saveFileTag.php": {
            "post": {
                "tags": [
                    "Tags"
                ],
                "summary": "Save tags for a file (or delete one)",
                "description": "Requires write access and (for non-admins) ownership when modifying.",
                "operationId": "saveFileTag",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder",
                                    "file"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "root"
                                    },
                                    "file": {
                                        "type": "string",
                                        "example": "doc.md"
                                    },
                                    "sourceId": {
                                        "type": "string",
                                        "example": "local"
                                    },
                                    "tags": {
                                        "type": "array",
                                        "items": {
                                            "properties": {
                                                "name": {
                                                    "type": "string",
                                                    "example": "work"
                                                },
                                                "color": {
                                                    "type": "string",
                                                    "example": "#ff0000"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "example": [
                                            {
                                                "name": "work",
                                                "color": "#ff0000"
                                            },
                                            {
                                                "name": "urgent",
                                                "color": "#00ff00"
                                            }
                                        ]
                                    },
                                    "deleteGlobal": {
                                        "type": "boolean",
                                        "example": false
                                    },
                                    "tagToDelete": {
                                        "type": "string",
                                        "example": null,
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Save result (model-defined)"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/share.php": {
            "get": {
                "tags": [
                    "Shares"
                ],
                "summary": "Download a shared file",
                "description": "Returns a shared file stream. If a password is required, an HTML prompt is returned.",
                "operationId": "shareFileDownload",
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "description": "Share token",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "pass",
                        "in": "query",
                        "description": "Share password",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "view",
                        "in": "query",
                        "description": "Render share landing page when set to 1",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "enum": [
                                0,
                                1
                            ]
                        }
                    },
                    {
                        "name": "inline",
                        "in": "query",
                        "description": "Allow inline rendering for safe types",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "enum": [
                                0,
                                1
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "File stream or password prompt",
                        "content": {
                            "application/octet-stream": {},
                            "text/html": {}
                        }
                    },
                    "400": {
                        "description": "Missing/invalid token"
                    },
                    "403": {
                        "description": "Forbidden or expired"
                    },
                    "404": {
                        "description": "Not found"
                    }
                }
            }
        },
        "/api/file/snippet.php": {
            "get": {
                "tags": [
                    "Files"
                ],
                "summary": "Get a small text snippet from a file for hover previews",
                "description": "Returns a short UTF-8 text snippet from supported file types (txt, md, csv, code, DOCX, XLSX, PPTX, etc.) for use in quick previews.",
                "operationId": "getFileSnippet",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "description": "Logical folder path (e.g. root, clients/acme)",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "file",
                        "in": "query",
                        "description": "File name",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Snippet JSON",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "snippet": {
                                            "type": "string"
                                        },
                                        "truncated": {
                                            "type": "boolean"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing/invalid input"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "File not found"
                    },
                    "500": {
                        "description": "Internal error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/thumbnail.php": {
            "get": {
                "tags": [
                    "Files"
                ],
                "summary": "Get a video thumbnail image",
                "description": "Returns a cached JPEG thumbnail for supported video files.",
                "operationId": "getVideoThumbnail",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "root"
                    },
                    {
                        "name": "file",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "clip.mp4"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Thumbnail image",
                        "content": {
                            "image/jpeg": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid folder/file"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Not found"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/file/zipStatus.php": {
            "get": {
                "tags": [
                    "Files"
                ],
                "summary": "Check status of a background archive build",
                "description": "Returns status for the authenticated user's token.",
                "operationId": "zipStatus",
                "parameters": [
                    {
                        "name": "k",
                        "in": "query",
                        "description": "Job token",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Status payload"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "404": {
                        "description": "Not found"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/capabilities.php": {
            "get": {
                "tags": [
                    "Folders"
                ],
                "summary": "Get folder capabilities",
                "description": "Returns effective permissions and capability flags for a folder.",
                "operationId": "getFolderCapabilities",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "root"
                    },
                    {
                        "name": "sourceId",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "local"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Capabilities payload"
                    },
                    "401": {
                        "description": "Unauthorized"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/createFolder.php": {
            "post": {
                "tags": [
                    "Folders"
                ],
                "summary": "Create a new folder",
                "description": "Requires authentication, CSRF token, and write access to the parent folder. Seeds ACL owner.",
                "operationId": "createFolder",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "description": "CSRF token from the current session",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folderName"
                                ],
                                "properties": {
                                    "folderName": {
                                        "type": "string",
                                        "example": "reports"
                                    },
                                    "parent": {
                                        "description": "Parent folder (default root)",
                                        "type": "string",
                                        "example": "root",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Creation result (model-defined JSON)"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "405": {
                        "description": "Method not allowed"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/createShareFolderLink.php": {
            "post": {
                "tags": [
                    "Shared Folders"
                ],
                "summary": "Create a share link for a folder",
                "description": "Requires authentication, CSRF token, and share permission. Non-admins must own the folder (unless bypass) and cannot share root.",
                "operationId": "createShareFolderLink",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "team/reports"
                                    },
                                    "expirationValue": {
                                        "type": "integer",
                                        "example": 60
                                    },
                                    "expirationUnit": {
                                        "type": "string",
                                        "enum": [
                                            "seconds",
                                            "minutes",
                                            "hours",
                                            "days"
                                        ],
                                        "example": "minutes"
                                    },
                                    "password": {
                                        "type": "string",
                                        "example": ""
                                    },
                                    "allowUpload": {
                                        "type": "integer",
                                        "enum": [
                                            0,
                                            1
                                        ],
                                        "example": 0
                                    },
                                    "allowSubfolders": {
                                        "type": "integer",
                                        "enum": [
                                            0,
                                            1
                                        ],
                                        "example": 0
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Share folder link created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "token": {
                                            "type": "string",
                                            "example": "sf_abc123"
                                        },
                                        "link": {
                                            "type": "string",
                                            "example": "/api/folder/shareFolder.php?token=sf_abc123"
                                        },
                                        "expires": {
                                            "type": "integer",
                                            "example": 1700000000
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/deleteFolder.php": {
            "post": {
                "tags": [
                    "Folders"
                ],
                "summary": "Delete a folder",
                "description": "Requires authentication, CSRF token, write scope, and (for non-admins) folder ownership.",
                "operationId": "deleteFolder",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "userA/reports"
                                    },
                                    "sourceId": {
                                        "type": "string",
                                        "example": "local"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Deletion result (model-defined JSON)"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "405": {
                        "description": "Method not allowed"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/deleteShareFolderLink.php": {
            "post": {
                "tags": [
                    "Shared Folders",
                    "Admin"
                ],
                "summary": "Delete a shared-folder link by token (admin only)",
                "description": "Requires authentication, CSRF token, and admin privileges.",
                "operationId": "deleteShareFolderLink",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "token"
                                ],
                                "properties": {
                                    "token": {
                                        "type": "string",
                                        "example": "sf_abc123"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Deleted"
                    },
                    "400": {
                        "description": "No token provided"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Admin only"
                    },
                    "404": {
                        "description": "Not found"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/downloadSharedFile.php": {
            "get": {
                "tags": [
                    "Shared Folders"
                ],
                "summary": "Download a file from a shared folder (by token)",
                "description": "Public endpoint; validates token and file name, then streams the file.",
                "operationId": "downloadSharedFile",
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "pass",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "file",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "report.pdf"
                    },
                    {
                        "name": "path",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "subfolder/report.pdf"
                    },
                    {
                        "name": "inline",
                        "in": "query",
                        "description": "Allow inline rendering for safe types",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "enum": [
                                0,
                                1
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Binary file",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "403": {
                        "description": "Password required"
                    },
                    "404": {
                        "description": "Not found"
                    }
                }
            }
        },
        "/api/folder/downloadSharedFolder.php": {
            "get": {
                "tags": [
                    "Shared Folders"
                ],
                "summary": "Download a shared folder as a ZIP",
                "description": "Public endpoint; validates token/path and streams a ZIP archive.",
                "operationId": "downloadSharedFolder",
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "pass",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "path",
                        "in": "query",
                        "description": "Subfolder path within the shared folder",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ZIP archive",
                        "content": {
                            "application/zip": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "403": {
                        "description": "Password required"
                    },
                    "404": {
                        "description": "Not found"
                    }
                }
            }
        },
        "/api/folder/encryptionJobStart.php": {
            "post": {
                "tags": [
                    "Folders"
                ],
                "summary": "Start folder encryption/decryption job",
                "description": "Queues an encryption or decryption job for a folder.",
                "operationId": "startFolderEncryptionJob",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder",
                                    "mode"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "team/reports"
                                    },
                                    "mode": {
                                        "type": "string",
                                        "enum": [
                                            "encrypt",
                                            "decrypt"
                                        ]
                                    },
                                    "totalFiles": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "totalBytes": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Job started"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/encryptionJobStatus.php": {
            "get": {
                "tags": [
                    "Folders"
                ],
                "summary": "Get folder encryption job status",
                "operationId": "getFolderEncryptionJobStatus",
                "parameters": [
                    {
                        "name": "jobId",
                        "in": "query",
                        "description": "Job id",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Job status"
                    },
                    "400": {
                        "description": "Invalid job id"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Job not found"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/encryptionJobTick.php": {
            "post": {
                "tags": [
                    "Folders"
                ],
                "summary": "Process encryption job tick",
                "description": "Processes a small batch for an active encryption/decryption job.",
                "operationId": "tickFolderEncryptionJob",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "jobId"
                                ],
                                "properties": {
                                    "jobId": {
                                        "type": "string",
                                        "example": "a1b2c3d4e5f6"
                                    },
                                    "maxFiles": {
                                        "type": "integer",
                                        "example": 2
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Tick result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Job not found"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/encryptionPlan.php": {
            "get": {
                "tags": [
                    "Folders"
                ],
                "summary": "Plan folder encryption/decryption",
                "description": "Scans a folder to estimate file/byte counts for encryption jobs.",
                "operationId": "planFolderEncryption",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "root"
                    },
                    {
                        "name": "mode",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "encrypt",
                                "decrypt"
                            ]
                        },
                        "example": "encrypt"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Plan result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/getFolderColors.php": {
            "get": {
                "tags": [
                    "Folders"
                ],
                "summary": "Get folder color map",
                "operationId": "getFolderColors",
                "responses": {
                    "200": {
                        "description": "Folder color map"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/getFolderEncryption.php": {
            "get": {
                "tags": [
                    "Folders"
                ],
                "summary": "Get folder encryption capabilities",
                "operationId": "getFolderEncryption",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "root"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Encryption capability payload"
                    },
                    "401": {
                        "description": "Unauthorized"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/getFolderList.php": {
            "get": {
                "tags": [
                    "Folders"
                ],
                "summary": "List folders (optionally under a parent)",
                "description": "Requires authentication. Non-admins see folders for which they have full view or own-only access.",
                "operationId": "getFolderList",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "description": "Parent folder to include and descend (default all); use 'root' for top-level",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "root"
                    },
                    {
                        "name": "sourceId",
                        "in": "query",
                        "description": "Optional source id (admin can target disabled sources)",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "local"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of folders",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "properties": {
                                            "folder": {
                                                "type": "string",
                                                "example": "team/reports"
                                            },
                                            "fileCount": {
                                                "type": "integer",
                                                "example": 12
                                            },
                                            "metadataFile": {
                                                "type": "string",
                                                "example": "/path/to/meta.json"
                                            }
                                        },
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid folder"
                    },
                    "401": {
                        "description": "Unauthorized"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/getShareFolderLinks.php": {
            "get": {
                "tags": [
                    "Shared Folders",
                    "Admin"
                ],
                "summary": "List active shared-folder links (admin only)",
                "description": "Returns all non-expired shared-folder links. Admin-only.",
                "operationId": "getShareFolderLinks",
                "responses": {
                    "200": {
                        "description": "Active share-folder links (model-defined JSON)"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Admin only"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/isEmpty.php": {
            "get": {
                "tags": [
                    "Folders"
                ],
                "summary": "Check if folder is empty",
                "description": "ACL-aware check used for folder tree icons.",
                "operationId": "folderIsEmpty",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "root"
                    },
                    {
                        "name": "sourceId",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "local"
                    },
                    {
                        "name": "deep",
                        "in": "query",
                        "description": "When 1, return recursive totals.",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "depth",
                        "in": "query",
                        "description": "Max recursive depth when deep=1 (0 = unlimited).",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        },
                        "example": 2
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Stats payload"
                    },
                    "401": {
                        "description": "Unauthorized"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/listChildren.php": {
            "get": {
                "tags": [
                    "Folders"
                ],
                "summary": "List folder children",
                "description": "Returns a paged list of child folders for tree navigation.",
                "operationId": "listFolderChildren",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "root"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 2000,
                            "minimum": 1
                        },
                        "example": 500
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Child list payload"
                    },
                    "401": {
                        "description": "Unauthorized"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/moveFolder.php": {
            "post": {
                "tags": [
                    "Folders"
                ],
                "summary": "Move or copy a folder",
                "description": "Moves (default) or copies a folder into a destination folder.",
                "operationId": "moveFolder",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "source",
                                    "destination"
                                ],
                                "properties": {
                                    "source": {
                                        "type": "string",
                                        "example": "team/q1"
                                    },
                                    "destination": {
                                        "type": "string",
                                        "example": "archive"
                                    },
                                    "mode": {
                                        "type": "string",
                                        "example": "move"
                                    },
                                    "sourceId": {
                                        "type": "string",
                                        "example": "local"
                                    },
                                    "destSourceId": {
                                        "type": "string",
                                        "example": "s3-main"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Move result (model-defined JSON)"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/renameFolder.php": {
            "post": {
                "tags": [
                    "Folders"
                ],
                "summary": "Rename or move a folder",
                "description": "Requires authentication, CSRF token, scope checks on old and new paths, and (for non-admins) ownership of the source folder.",
                "operationId": "renameFolder",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "oldFolder",
                                    "newFolder"
                                ],
                                "properties": {
                                    "oldFolder": {
                                        "type": "string",
                                        "example": "team/q1"
                                    },
                                    "newFolder": {
                                        "type": "string",
                                        "example": "team/quarter-1"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Rename result (model-defined JSON)"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "405": {
                        "description": "Method not allowed"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/saveFolderColor.php": {
            "post": {
                "tags": [
                    "Folders"
                ],
                "summary": "Save folder color",
                "description": "Sets or clears a custom folder color.",
                "operationId": "saveFolderColor",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "team/reports"
                                    },
                                    "color": {
                                        "description": "Empty string clears",
                                        "type": "string",
                                        "example": "#ff9900",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Save result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/setFolderEncryption.php": {
            "post": {
                "tags": [
                    "Folders"
                ],
                "summary": "Set folder encryption state",
                "description": "Enables or disables folder encryption (v1 compatibility).",
                "operationId": "setFolderEncryption",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder",
                                    "encrypted"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "team/reports"
                                    },
                                    "encrypted": {
                                        "type": "boolean",
                                        "example": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Update result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Folder not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/folder/shareFolder.php": {
            "get": {
                "tags": [
                    "Shared Folders"
                ],
                "summary": "Open a shared folder by token (HTML UI)",
                "description": "If the share is password-protected and no password is supplied, an HTML password form is returned. Otherwise renders an HTML listing with optional upload form.",
                "operationId": "shareFolder",
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "pass",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "path",
                        "in": "query",
                        "description": "Subfolder path within the shared folder",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "HTML page (password form or folder listing)",
                        "content": {
                            "text/html": {}
                        }
                    },
                    "400": {
                        "description": "Missing/invalid token"
                    },
                    "403": {
                        "description": "Forbidden or wrong password"
                    }
                }
            }
        },
        "/api/folder/uploadToSharedFolder.php": {
            "post": {
                "tags": [
                    "Shared Folders"
                ],
                "summary": "Upload a file into a shared folder (by token)",
                "description": "Public form-upload endpoint. Only allowed when the share link has uploads enabled. On success responds with a redirect to the share page.",
                "operationId": "uploadToSharedFolder",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "required": [
                                    "token",
                                    "fileToUpload"
                                ],
                                "properties": {
                                    "token": {
                                        "description": "Share token",
                                        "type": "string"
                                    },
                                    "pass": {
                                        "description": "Share password (if required)",
                                        "type": "string"
                                    },
                                    "path": {
                                        "description": "Optional subfolder path within the shared folder",
                                        "type": "string"
                                    },
                                    "fileToUpload": {
                                        "description": "File to upload",
                                        "type": "string",
                                        "format": "binary"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "302": {
                        "description": "Redirect to /api/folder/shareFolder.php?token=..."
                    },
                    "400": {
                        "description": "Upload error or invalid input"
                    },
                    "405": {
                        "description": "Method not allowed"
                    }
                }
            }
        },
        "/api/media/getProgress.php": {
            "get": {
                "tags": [
                    "Media"
                ],
                "summary": "Get media playback progress",
                "operationId": "getMediaProgress",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "root"
                    },
                    {
                        "name": "file",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "video.mp4"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Progress state"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/media/getViewedMap.php": {
            "get": {
                "tags": [
                    "Media"
                ],
                "summary": "Get viewed media map",
                "operationId": "getViewedMediaMap",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "root"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Viewed map"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/media/updateProgress.php": {
            "post": {
                "tags": [
                    "Media"
                ],
                "summary": "Update media playback progress",
                "operationId": "updateMediaProgress",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder",
                                    "file"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "root"
                                    },
                                    "file": {
                                        "type": "string",
                                        "example": "video.mp4"
                                    },
                                    "seconds": {
                                        "type": "number",
                                        "format": "float",
                                        "example": 42.5
                                    },
                                    "duration": {
                                        "type": "number",
                                        "format": "float",
                                        "example": 3600,
                                        "nullable": true
                                    },
                                    "completed": {
                                        "type": "boolean",
                                        "nullable": true
                                    },
                                    "clear": {
                                        "type": "boolean",
                                        "example": false
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Update result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/onlyoffice/callback.php": {
            "post": {
                "tags": [
                    "ONLYOFFICE"
                ],
                "summary": "ONLYOFFICE save callback",
                "parameters": [
                    {
                        "name": "sourceId",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK / error JSON"
                    }
                }
            }
        },
        "/api/onlyoffice/config.php": {
            "get": {
                "tags": [
                    "ONLYOFFICE"
                ],
                "summary": "Get editor config for a file (signed URLs, callback)",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "file",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "sourceId",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Editor config"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Disabled / Not found"
                    }
                }
            }
        },
        "/api/onlyoffice/signed-download.php": {
            "get": {
                "tags": [
                    "ONLYOFFICE"
                ],
                "summary": "Serve a signed file blob to ONLYOFFICE",
                "parameters": [
                    {
                        "name": "tok",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "File stream"
                    },
                    "403": {
                        "description": "Signature/expiry invalid"
                    }
                }
            }
        },
        "/api/onlyoffice/status.php": {
            "get": {
                "tags": [
                    "ONLYOFFICE"
                ],
                "summary": "ONLYOFFICE availability & supported extensions",
                "responses": {
                    "200": {
                        "description": "Status JSON"
                    }
                }
            }
        },
        "/api/pro/audit/exportCsv.php": {
            "get": {
                "tags": [
                    "Pro"
                ],
                "summary": "Export audit log as CSV",
                "description": "Exports audit log entries as CSV.",
                "operationId": "proAuditExportCsv",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "team"
                    },
                    {
                        "name": "user",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "action",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "source",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "storage",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "description": "ISO timestamp or epoch",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 5000,
                            "minimum": 1
                        },
                        "example": 1000
                    }
                ],
                "responses": {
                    "200": {
                        "description": "CSV stream",
                        "content": {
                            "text/csv": {}
                        }
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/audit/list.php": {
            "get": {
                "tags": [
                    "Pro"
                ],
                "summary": "List audit log entries",
                "description": "Returns audit log entries for admins, or for a specific folder when non-admin.",
                "operationId": "proAuditList",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "team"
                    },
                    {
                        "name": "user",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "action",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "source",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "storage",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "description": "ISO timestamp or epoch",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 500,
                            "minimum": 1
                        },
                        "example": 200
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Audit list payload"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/diskUsageChildren.php": {
            "get": {
                "tags": [
                    "Pro"
                ],
                "summary": "Get disk usage children",
                "description": "Returns per-folder usage children for the storage explorer (Pro).",
                "operationId": "proDiskUsageChildren",
                "parameters": [
                    {
                        "name": "folder",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "root"
                    },
                    {
                        "name": "sourceId",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Children payload"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "404": {
                        "description": "Snapshot not found"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/diskUsageDeleteFilePermanent.php": {
            "post": {
                "tags": [
                    "Pro"
                ],
                "summary": "Permanently delete a file",
                "description": "Deletes a single file from storage explorer (Pro, admin).",
                "operationId": "proDiskUsageDeleteFilePermanent",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "root"
                                    },
                                    "name": {
                                        "type": "string",
                                        "example": "large.zip"
                                    },
                                    "sourceId": {
                                        "type": "string",
                                        "example": "local"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Delete result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/diskUsageDeleteFolderRecursive.php": {
            "post": {
                "tags": [
                    "Pro"
                ],
                "summary": "Permanently delete a folder",
                "description": "Recursively deletes a folder from storage explorer (Pro, admin).",
                "operationId": "proDiskUsageDeleteFolderRecursive",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "team/archive"
                                    },
                                    "sourceId": {
                                        "type": "string",
                                        "example": "local"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Delete result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/diskUsageTopFiles.php": {
            "get": {
                "tags": [
                    "Pro"
                ],
                "summary": "Get top files by size",
                "description": "Returns the largest files across the instance (Pro).",
                "operationId": "proDiskUsageTopFiles",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 100
                    },
                    {
                        "name": "sourceId",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Top files payload"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "404": {
                        "description": "Snapshot not found"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/groups/list.php": {
            "get": {
                "tags": [
                    "Pro"
                ],
                "summary": "List Pro groups",
                "description": "Returns user groups defined in FileRise Pro.",
                "operationId": "proGroupsList",
                "responses": {
                    "200": {
                        "description": "Groups payload"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/groups/save.php": {
            "post": {
                "tags": [
                    "Pro"
                ],
                "summary": "Save Pro groups",
                "description": "Saves group definitions in FileRise Pro.",
                "operationId": "proGroupsSave",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "groups"
                                ],
                                "properties": {
                                    "groups": {
                                        "type": "object"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Save result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/portals/get.php": {
            "get": {
                "tags": [
                    "Pro"
                ],
                "summary": "Get portal by slug",
                "description": "Returns portal metadata (public).",
                "operationId": "proPortalsGet",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "client-portal"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Portal payload"
                    },
                    "404": {
                        "description": "Portal not found"
                    }
                }
            }
        },
        "/api/pro/portals/list.php": {
            "get": {
                "tags": [
                    "Pro"
                ],
                "summary": "List portals",
                "description": "Returns all portals (admin only, Pro).",
                "operationId": "proPortalsList",
                "responses": {
                    "200": {
                        "description": "Portals payload"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/portals/publicMeta.php": {
            "get": {
                "tags": [
                    "Pro"
                ],
                "summary": "Get public portal metadata",
                "description": "Returns the public metadata needed for the portal login page.",
                "operationId": "proPortalsPublicMeta",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "client-portal"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Public portal payload"
                    },
                    "400": {
                        "description": "Missing slug"
                    },
                    "404": {
                        "description": "Portal not found or Pro inactive"
                    },
                    "410": {
                        "description": "Portal expired"
                    },
                    "500": {
                        "description": "Server error"
                    }
                }
            }
        },
        "/api/pro/portals/save.php": {
            "post": {
                "tags": [
                    "Pro"
                ],
                "summary": "Save portals",
                "description": "Saves portal definitions (admin only, Pro).",
                "operationId": "proPortalsSave",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "portals"
                                ],
                                "properties": {
                                    "portals": {
                                        "type": "object"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Save result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/portals/submissions.php": {
            "get": {
                "tags": [
                    "Pro"
                ],
                "summary": "List portal submissions",
                "description": "Returns submissions for a portal (admin only, Pro).",
                "operationId": "proPortalsSubmissions",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "client-portal"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Submissions payload"
                    },
                    "400": {
                        "description": "Missing slug"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/portals/submitForm.php": {
            "post": {
                "tags": [
                    "Pro"
                ],
                "summary": "Submit portal form",
                "description": "Submits a portal form payload (requires auth, Pro).",
                "operationId": "proPortalsSubmitForm",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "slug",
                                    "form"
                                ],
                                "properties": {
                                    "slug": {
                                        "type": "string",
                                        "example": "client-portal"
                                    },
                                    "form": {
                                        "properties": {
                                            "name": {
                                                "type": "string",
                                                "example": "Jane Doe"
                                            },
                                            "email": {
                                                "type": "string",
                                                "example": "jane@example.com"
                                            },
                                            "reference": {
                                                "type": "string",
                                                "example": "PO-123"
                                            },
                                            "notes": {
                                                "type": "string",
                                                "example": "Please review"
                                            }
                                        },
                                        "type": "object"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Submission saved"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/portals/uploadLogo.php": {
            "post": {
                "tags": [
                    "Pro"
                ],
                "summary": "Upload portal logo",
                "description": "Uploads a portal logo image (admin only, Pro).",
                "operationId": "proPortalsUploadLogo",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "required": [
                                    "portal_logo"
                                ],
                                "properties": {
                                    "portal_logo": {
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "slug": {
                                        "type": "string",
                                        "example": "client-portal"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Upload result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/search/query.php": {
            "get": {
                "tags": [
                    "Pro"
                ],
                "summary": "Search files (Pro)",
                "description": "Searches across folders using the Pro search index.",
                "operationId": "proSearchQuery",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Search query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 50
                    },
                    {
                        "name": "sourceId",
                        "in": "query",
                        "description": "Source id or 'all'",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "force",
                        "in": "query",
                        "description": "Admins only: force refresh",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Search results"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "503": {
                        "description": "Search disabled"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/pro/uploadBrandLogo.php": {
            "post": {
                "tags": [
                    "Pro"
                ],
                "summary": "Upload branding logo",
                "description": "Uploads a branding logo image (admin only, Pro).",
                "operationId": "proUploadBrandLogo",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "required": [
                                    "brand_logo"
                                ],
                                "properties": {
                                    "brand_logo": {
                                        "type": "string",
                                        "format": "binary"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Upload result"
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "403": {
                        "description": "Forbidden or Pro required"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/profile/changePassword.php": {
            "post": {
                "tags": [
                    "Users"
                ],
                "summary": "Change user password",
                "description": "Allows an authenticated user to change their password by verifying the old password and updating to a new one.",
                "operationId": "changePassword",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "oldPassword",
                                    "newPassword",
                                    "confirmPassword"
                                ],
                                "properties": {
                                    "oldPassword": {
                                        "type": "string",
                                        "example": "oldpass123"
                                    },
                                    "newPassword": {
                                        "type": "string",
                                        "example": "newpass456"
                                    },
                                    "confirmPassword": {
                                        "type": "string",
                                        "example": "newpass456"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Password updated successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "string",
                                            "example": "Password updated successfully."
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Invalid CSRF token"
                    },
                    "405": {
                        "description": "Method not allowed"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/profile/getCurrentUser.php": {
            "get": {
                "tags": [
                    "Users"
                ],
                "operationId": "getCurrentUser",
                "responses": {
                    "200": {
                        "description": "Current user",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "username",
                                        "isAdmin",
                                        "totp_enabled",
                                        "profile_picture"
                                    ],
                                    "properties": {
                                        "username": {
                                            "type": "string",
                                            "example": "ryan"
                                        },
                                        "isAdmin": {
                                            "type": "boolean"
                                        },
                                        "totp_enabled": {
                                            "type": "boolean"
                                        },
                                        "profile_picture": {
                                            "type": "string",
                                            "example": "/api/public/profilePic.php?file=ryan.png"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/profile/getUserPermissions.php": {
            "get": {
                "tags": [
                    "Users"
                ],
                "summary": "Retrieve user permissions",
                "description": "Returns the permissions for the current user, or all permissions if the user is an admin.",
                "operationId": "getUserPermissions",
                "responses": {
                    "200": {
                        "description": "Successful response with user permissions",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/profile/totp_disable.php": {
            "put": {
                "tags": [
                    "TOTP"
                ],
                "summary": "Disable TOTP for the authenticated user",
                "description": "Clears the TOTP secret from the users file for the current user. Accepts PUT or POST.",
                "operationId": "disableTOTP",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "TOTP disabled successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "TOTP disabled successfully."
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing username"
                    },
                    "403": {
                        "description": "Not authenticated or invalid CSRF token"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "500": {
                        "description": "Failed to disable TOTP"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/profile/totp_recover.php": {
            "post": {
                "tags": [
                    "TOTP"
                ],
                "summary": "Recover TOTP",
                "description": "Verifies a recovery code to disable TOTP and finalize login.",
                "operationId": "recoverTOTP",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "recovery_code"
                                ],
                                "properties": {
                                    "recovery_code": {
                                        "type": "string",
                                        "example": "ABC123DEF456"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Recovery successful",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "ok"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid input or recovery code"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Invalid CSRF token"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "429": {
                        "description": "Too many attempts"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/profile/totp_saveCode.php": {
            "post": {
                "tags": [
                    "TOTP"
                ],
                "summary": "Generate and save a new TOTP recovery code",
                "description": "Generates a new TOTP recovery code for the authenticated user, stores its hash, and returns the plain text recovery code.",
                "operationId": "totpSaveCode",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recovery code generated successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "ok"
                                        },
                                        "recoveryCode": {
                                            "type": "string",
                                            "example": "ABC123DEF456"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Invalid CSRF token or unauthorized"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/profile/totp_setup.php": {
            "get": {
                "tags": [
                    "TOTP"
                ],
                "summary": "Set up TOTP and generate a QR code",
                "description": "Generates (or retrieves) the TOTP secret for the user and builds a QR code image for scanning.",
                "operationId": "setupTOTP",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "QR code image for TOTP setup",
                        "content": {
                            "image/png": {}
                        }
                    },
                    "400": {
                        "description": "Missing username"
                    },
                    "403": {
                        "description": "Not authorized or invalid CSRF token"
                    },
                    "500": {
                        "description": "Server error"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/profile/totp_verify.php": {
            "post": {
                "tags": [
                    "TOTP"
                ],
                "summary": "Verify TOTP code",
                "description": "Verifies a TOTP code and completes login for pending users or validates TOTP for setup verification.",
                "operationId": "verifyTOTP",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "totp_code"
                                ],
                                "properties": {
                                    "totp_code": {
                                        "type": "string",
                                        "example": "123456"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "TOTP successfully verified",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "ok"
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Login successful"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request (e.g., invalid input)"
                    },
                    "403": {
                        "description": "Not authenticated or invalid CSRF token"
                    },
                    "429": {
                        "description": "Too many attempts. Try again later."
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/profile/updateUserPanel.php": {
            "put": {
                "tags": [
                    "Users"
                ],
                "summary": "Update user panel settings",
                "description": "Updates user panel settings. Accessible to authenticated users. Accepts PUT or POST.",
                "operationId": "updateUserPanel",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "totp_enabled"
                                ],
                                "properties": {
                                    "totp_enabled": {
                                        "type": "boolean",
                                        "example": false
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "User panel updated successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "string",
                                            "example": "User panel updated: TOTP disabled"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Invalid CSRF token"
                    },
                    "405": {
                        "description": "Method not allowed"
                    },
                    "400": {
                        "description": "Bad Request"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/profile/uploadPicture.php": {
            "post": {
                "tags": [
                    "Users"
                ],
                "summary": "Upload or replace the current user's profile picture",
                "description": "Accepts a single image file (JPEG, PNG, or GIF) up to 2&nbsp;MB. Requires a valid session cookie and CSRF token.",
                "operationId": "uploadProfilePicture",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "description": "Anti-CSRF token associated with the current session.",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "required": [
                                    "profile_picture"
                                ],
                                "properties": {
                                    "profile_picture": {
                                        "description": "JPEG, PNG, or GIF image. Max size: 2 MB.",
                                        "type": "string",
                                        "format": "binary"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Profile picture updated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "success",
                                        "url"
                                    ],
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "url": {
                                            "type": "string",
                                            "example": "/api/public/profilePic.php?file=alice_9f3c2e1a8bcd.png"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "No file uploaded, invalid file type, or file too large."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "500": {
                        "description": "Server error while saving the picture."
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/public/siteConfig.php": {
            "get": {
                "tags": [
                    "Config"
                ],
                "summary": "Get public site configuration",
                "description": "Returns the public site configuration used by the frontend.",
                "operationId": "getSiteConfig",
                "responses": {
                    "200": {
                        "description": "Site config payload"
                    },
                    "500": {
                        "description": "Server error"
                    }
                }
            }
        },
        "/api/upload/checkExisting.php": {
            "post": {
                "tags": [
                    "Uploads"
                ],
                "summary": "Check for existing files before upload",
                "description": "Checks whether the provided relative paths already exist in the target folder.",
                "operationId": "checkUploadExisting",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "folder",
                                    "files"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "root"
                                    },
                                    "sourceId": {
                                        "type": "string",
                                        "example": "local"
                                    },
                                    "files": {
                                        "type": "array",
                                        "items": {
                                            "required": [
                                                "path"
                                            ],
                                            "properties": {
                                                "path": {
                                                    "type": "string",
                                                    "example": "team/reports/report.pdf"
                                                },
                                                "size": {
                                                    "type": "integer",
                                                    "format": "int64",
                                                    "example": 123456
                                                }
                                            },
                                            "type": "object"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Existing files",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "existing": {
                                            "type": "array",
                                            "items": {
                                                "properties": {
                                                    "path": {
                                                        "type": "string"
                                                    },
                                                    "size": {
                                                        "type": "integer",
                                                        "format": "int64",
                                                        "nullable": true
                                                    },
                                                    "sameSize": {
                                                        "type": "boolean",
                                                        "nullable": true
                                                    }
                                                },
                                                "type": "object"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Invalid CSRF token"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/upload/removeChunks.php": {
            "post": {
                "tags": [
                    "Uploads"
                ],
                "summary": "Remove temporary chunk directory",
                "description": "Deletes the temporary directory used for a chunked upload. Requires a valid CSRF token in the form field.",
                "operationId": "removeChunks",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "required": [
                                    "folder",
                                    "csrf_token"
                                ],
                                "properties": {
                                    "folder": {
                                        "type": "string",
                                        "example": "resumable_myupload123"
                                    },
                                    "csrf_token": {
                                        "description": "CSRF token for this session",
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Removal result",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Temporary folder removed."
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid input"
                    },
                    "403": {
                        "description": "Invalid CSRF token"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        },
        "/api/upload/upload.php": {
            "post": {
                "tags": [
                    "Uploads"
                ],
                "summary": "Upload a file (supports chunked + full uploads)",
                "description": "Requires a session (cookie) and a CSRF token (header preferred; falls back to form field). Checks user/account flags and folder-level WRITE ACL, then delegates to the model. Returns JSON for chunked uploads; full uploads may redirect after success.",
                "operationId": "handleUpload",
                "parameters": [
                    {
                        "name": "X-CSRF-Token",
                        "in": "header",
                        "description": "CSRF token for this session (preferred). If omitted, send as form field `csrf_token`.",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "required": [
                                    "fileToUpload"
                                ],
                                "properties": {
                                    "fileToUpload": {
                                        "description": "File or chunk payload.",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "folder": {
                                        "description": "Target folder (defaults to 'root' if omitted).",
                                        "type": "string",
                                        "example": "root"
                                    },
                                    "csrf_token": {
                                        "description": "CSRF token (form fallback).",
                                        "type": "string"
                                    },
                                    "upload_token": {
                                        "description": "Legacy alias for CSRF token (accepted by server).",
                                        "type": "string"
                                    },
                                    "resumableChunkNumber": {
                                        "type": "integer"
                                    },
                                    "resumableTotalChunks": {
                                        "type": "integer"
                                    },
                                    "resumableChunkSize": {
                                        "type": "integer"
                                    },
                                    "resumableCurrentChunkSize": {
                                        "type": "integer"
                                    },
                                    "resumableTotalSize": {
                                        "type": "integer"
                                    },
                                    "resumableType": {
                                        "type": "string"
                                    },
                                    "resumableIdentifier": {
                                        "type": "string"
                                    },
                                    "resumableFilename": {
                                        "type": "string"
                                    },
                                    "resumableRelativePath": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "JSON result (success, chunk status, or CSRF refresh).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "properties": {
                                                "success": {
                                                    "type": "string",
                                                    "example": "File uploaded successfully"
                                                },
                                                "newFilename": {
                                                    "type": "string",
                                                    "example": "5f2d7c123a_example.png"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        {
                                            "properties": {
                                                "status": {
                                                    "type": "string",
                                                    "example": "chunk uploaded"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        {
                                            "properties": {
                                                "csrf_expired": {
                                                    "type": "boolean",
                                                    "example": true
                                                },
                                                "csrf_token": {
                                                    "type": "string",
                                                    "example": "b1c2...f9"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "302": {
                        "description": "Redirect after a successful full upload.",
                        "headers": {
                            "Location": {
                                "description": "Where the client is redirected",
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request (missing/invalid fields, model error)"
                    },
                    "401": {
                        "description": "Unauthorized (no session)"
                    },
                    "403": {
                        "description": "Forbidden (upload disabled or no WRITE to folder)"
                    },
                    "500": {
                        "description": "Server error while processing upload"
                    }
                },
                "security": [
                    {
                        "cookieAuth": []
                    }
                ]
            }
        }
    },
    "components": {
        "schemas": {
            "SimpleSuccess": {
                "properties": {
                    "success": {
                        "type": "boolean",
                        "example": true
                    }
                },
                "type": "object"
            },
            "SimpleError": {
                "properties": {
                    "error": {
                        "type": "string",
                        "example": "Something went wrong"
                    }
                },
                "type": "object"
            },
            "ShareLinkEntry": {
                "properties": {
                    "folder": {
                        "type": "string",
                        "example": "root"
                    },
                    "file": {
                        "type": "string",
                        "example": "invoice.pdf"
                    },
                    "expires": {
                        "type": "integer",
                        "format": "int64",
                        "example": 1735689600
                    },
                    "password": {
                        "type": "string",
                        "example": "***",
                        "nullable": true
                    },
                    "token": {
                        "type": "string",
                        "example": "0123456789abcdef0123456789abcdef"
                    },
                    "sourceId": {
                        "type": "string",
                        "example": "local"
                    },
                    "sourceName": {
                        "type": "string",
                        "example": "Local"
                    }
                },
                "type": "object"
            },
            "ShareLinksMap": {
                "type": "object",
                "additionalProperties": {
                    "$ref": "#/components/schemas/ShareLinkEntry"
                }
            },
            "ShareFolderLinkEntry": {
                "properties": {
                    "folder": {
                        "type": "string",
                        "example": "shared/reports"
                    },
                    "expires": {
                        "type": "integer",
                        "format": "int64",
                        "example": 1735689600
                    },
                    "password": {
                        "type": "string",
                        "example": "***",
                        "nullable": true
                    },
                    "allowUpload": {
                        "type": "integer",
                        "example": 1
                    },
                    "token": {
                        "type": "string",
                        "example": "0123456789abcdef0123456789abcdef"
                    },
                    "sourceId": {
                        "type": "string",
                        "example": "local"
                    },
                    "sourceName": {
                        "type": "string",
                        "example": "Local"
                    }
                },
                "type": "object"
            },
            "ShareFolderLinksMap": {
                "type": "object",
                "additionalProperties": {
                    "$ref": "#/components/schemas/ShareFolderLinkEntry"
                }
            },
            "LoginOptionsPublic": {
                "properties": {
                    "disableFormLogin": {
                        "type": "boolean"
                    },
                    "disableBasicAuth": {
                        "type": "boolean"
                    },
                    "disableOIDCLogin": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "LoginOptionsAdminExtra": {
                "properties": {
                    "authBypass": {
                        "type": "boolean",
                        "nullable": true
                    },
                    "authHeaderName": {
                        "type": "string",
                        "example": "X-Remote-User",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "OIDCConfigPublic": {
                "properties": {
                    "providerUrl": {
                        "type": "string",
                        "example": "https://accounts.example.com"
                    },
                    "redirectUri": {
                        "type": "string",
                        "example": "https://your.filerise.app/callback"
                    }
                },
                "type": "object"
            },
            "AdminGetConfigPublic": {
                "required": [
                    "header_title",
                    "loginOptions",
                    "globalOtpauthUrl",
                    "enableWebDAV",
                    "sharedMaxUploadSize",
                    "uploads",
                    "oidc"
                ],
                "properties": {
                    "header_title": {
                        "type": "string",
                        "example": "FileRise"
                    },
                    "loginOptions": {
                        "$ref": "#/components/schemas/LoginOptionsPublic"
                    },
                    "globalOtpauthUrl": {
                        "type": "string"
                    },
                    "enableWebDAV": {
                        "type": "boolean"
                    },
                    "sharedMaxUploadSize": {
                        "type": "integer",
                        "format": "int64"
                    },
                    "uploads": {
                        "properties": {
                            "resumableChunkMb": {
                                "type": "number",
                                "format": "float",
                                "maximum": 100,
                                "minimum": 0.5,
                                "example": 1.5
                            },
                            "resumableTtlHours": {
                                "type": "number",
                                "format": "float",
                                "maximum": 168,
                                "minimum": 0.5,
                                "example": 6
                            }
                        },
                        "type": "object",
                        "additionalProperties": false
                    },
                    "oidc": {
                        "$ref": "#/components/schemas/OIDCConfigPublic"
                    }
                },
                "type": "object"
            },
            "AdminGetConfigAdmin": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/AdminGetConfigPublic"
                    },
                    {
                        "properties": {
                            "loginOptions": {
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/LoginOptionsPublic"
                                    },
                                    {
                                        "$ref": "#/components/schemas/LoginOptionsAdminExtra"
                                    }
                                ]
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "AdminUpdateConfigRequest": {
                "properties": {
                    "header_title": {
                        "type": "string",
                        "maxLength": 100,
                        "example": "FileRise"
                    },
                    "loginOptions": {
                        "properties": {
                            "disableFormLogin": {
                                "type": "boolean",
                                "example": false
                            },
                            "disableBasicAuth": {
                                "type": "boolean",
                                "example": false
                            },
                            "disableOIDCLogin": {
                                "description": "false = OIDC enabled",
                                "type": "boolean",
                                "example": true
                            },
                            "authBypass": {
                                "type": "boolean",
                                "example": false
                            },
                            "authHeaderName": {
                                "description": "Letters/numbers/dashes only",
                                "type": "string",
                                "pattern": "^[A-Za-z0-9\\\\-]+$",
                                "example": "X-Remote-User"
                            }
                        },
                        "type": "object",
                        "additionalProperties": false
                    },
                    "globalOtpauthUrl": {
                        "type": "string",
                        "example": "otpauth://totp/{label}?secret={secret}&issuer=FileRise"
                    },
                    "enableWebDAV": {
                        "type": "boolean",
                        "example": false
                    },
                    "sharedMaxUploadSize": {
                        "type": "integer",
                        "format": "int64",
                        "minimum": 0,
                        "example": 52428800
                    },
                    "uploads": {
                        "properties": {
                            "resumableChunkMb": {
                                "type": "number",
                                "format": "float",
                                "maximum": 100,
                                "minimum": 0.5,
                                "example": 1.5
                            },
                            "resumableTtlHours": {
                                "type": "number",
                                "format": "float",
                                "maximum": 168,
                                "minimum": 0.5,
                                "example": 6
                            }
                        },
                        "type": "object",
                        "additionalProperties": false
                    },
                    "oidc": {
                        "description": "When disableOIDCLogin=false (OIDC enabled), providerUrl, redirectUri, and clientId are required.",
                        "properties": {
                            "providerUrl": {
                                "type": "string",
                                "format": "uri",
                                "example": "https://issuer.example.com"
                            },
                            "clientId": {
                                "type": "string",
                                "example": "my-client-id"
                            },
                            "clientSecret": {
                                "type": "string",
                                "writeOnly": true,
                                "example": "***"
                            },
                            "redirectUri": {
                                "type": "string",
                                "format": "uri",
                                "example": "https://app.example.com/auth/callback"
                            },
                            "groupClaim": {
                                "type": "string",
                                "example": "groups",
                                "nullable": true
                            },
                            "extraScopes": {
                                "type": "string",
                                "example": "groups",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "additionalProperties": false
                    }
                },
                "type": "object",
                "additionalProperties": false
            }
        },
        "responses": {
            "Unauthorized": {
                "description": "Unauthorized (no session)",
                "content": {
                    "application/json": {
                        "schema": {
                            "properties": {
                                "error": {
                                    "type": "string",
                                    "example": "Unauthorized"
                                }
                            },
                            "type": "object"
                        }
                    }
                }
            },
            "Forbidden": {
                "description": "Forbidden (not enough privileges)",
                "content": {
                    "application/json": {
                        "schema": {
                            "properties": {
                                "error": {
                                    "type": "string",
                                    "example": "Invalid CSRF token."
                                }
                            },
                            "type": "object"
                        }
                    }
                }
            }
        },
        "requestBodies": {
            "MoveFilesRequest": {
                "required": true,
                "content": {
                    "application/json": {
                        "schema": {
                            "required": [
                                "source",
                                "destination",
                                "files"
                            ],
                            "properties": {
                                "source": {
                                    "type": "string",
                                    "example": "inbox"
                                },
                                "destination": {
                                    "type": "string",
                                    "example": "archive"
                                },
                                "files": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                }
                            },
                            "type": "object"
                        }
                    }
                }
            }
        },
        "securitySchemes": {
            "cookieAuth": {
                "type": "apiKey",
                "description": "Session cookie used for authenticated endpoints",
                "name": "PHPSESSID",
                "in": "cookie"
            },
            "CsrfHeader": {
                "type": "apiKey",
                "description": "CSRF token header required for state-changing requests",
                "name": "X-CSRF-Token",
                "in": "header"
            }
        }
    },
    "tags": [
        {
            "name": "Admin",
            "description": "Admin endpoints"
        },
        {
            "name": "Users",
            "description": "Users"
        },
        {
            "name": "Auth",
            "description": "Auth"
        },
        {
            "name": "Files",
            "description": "Files"
        },
        {
            "name": "Shares",
            "description": "Shares"
        },
        {
            "name": "Trash",
            "description": "Trash"
        },
        {
            "name": "Tags",
            "description": "Tags"
        },
        {
            "name": "Folders",
            "description": "Folders"
        },
        {
            "name": "Shared Folders",
            "description": "Shared Folders"
        },
        {
            "name": "Media",
            "description": "Media"
        },
        {
            "name": "ONLYOFFICE",
            "description": "ONLYOFFICE"
        },
        {
            "name": "Pro",
            "description": "Pro"
        },
        {
            "name": "TOTP",
            "description": "TOTP"
        },
        {
            "name": "Config",
            "description": "Config"
        },
        {
            "name": "Uploads",
            "description": "Uploads"
        }
    ]
}
