FileRise API (1.0.0)

Download OpenAPI specification:Download

A lightweight self-hosted file manager API

Admin

Admin

Retrieve admin configuration

Returns the admin configuration settings, decrypting the configuration file and providing default values if not set.

Responses

Response samples

Content type
application/json
{}

Update admin configuration

Updates the admin configuration settings. Requires admin privileges and a valid CSRF token.

Request Body schema: application/json
header_title
required
string
required
object
required
object
globalOtpauthUrl
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "success": "Configuration updated successfully."
}

Auth

Auth

Authenticate user

Handles user authentication via OIDC or form-based credentials. For OIDC flows, processes callbacks; otherwise, performs standard authentication with optional TOTP verification.

Request Body schema: application/json
username
required
string
password
required
string
remember_me
boolean
totp_code
string

Responses

Request samples

Content type
application/json
{
  • "username": "johndoe",
  • "password": "secretpassword",
  • "remember_me": true,
  • "totp_code": "123456"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "success": "Login successful",
  • "username": "johndoe",
  • "isAdmin": true
}

Check authentication status

Checks if the current session is authenticated. If the users file is missing or empty, returns a setup flag. Also returns information about admin privileges, TOTP status, and folder-only access.

Responses

Response samples

Content type
application/json
{
  • "authenticated": true,
  • "isAdmin": true,
  • "totp_enabled": false,
  • "username": "johndoe",
  • "folderOnly": false
}

Retrieve CSRF token and share URL

Returns the current CSRF token along with the configured share URL.

Responses

Response samples

Content type
application/json
{}

Authenticate using HTTP Basic Authentication

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.

Responses

Response samples

Content type
application/json
{
  • "success": "Login successful"
}

Logout user

Clears the session, removes persistent login tokens, and redirects the user to the login page.

Responses

Files

Files

Copy files between folders

Copies files from a source folder to a destination folder. It validates folder names, handles file renaming if a conflict exists, and updates metadata accordingly.

Request Body schema: application/json
source
required
string
destination
required
string
files
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "source": "root",
  • "destination": "Documents",
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "Files copied successfully"
}

Delete files (move to trash)

Moves the specified files from the given folder to the trash and updates metadata accordingly.

Request Body schema: application/json
folder
string
files
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "folder": "Documents",
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "Files moved to Trash: file1.pdf, file2.doc"
}

Move files between folders

Moves files from a source folder to a destination folder, updating metadata accordingly.

Request Body schema: application/json
source
required
string
destination
required
string
files
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "source": "root",
  • "destination": "Archives",
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "Files moved successfully"
}

Rename a file

Renames a file within a specified folder and updates folder metadata. If a file with the new name exists, a unique name is generated.

Request Body schema: application/json
folder
required
string
oldName
required
string
newName
required
string

Responses

Request samples

Content type
application/json
{
  • "folder": "Documents",
  • "oldName": "oldfile.pdf",
  • "newName": "newfile.pdf"
}

Response samples

Content type
application/json
{
  • "success": "File renamed successfully",
  • "newName": "newfile.pdf"
}

Save a file

Saves file content to disk in a specified folder and updates metadata accordingly.

Request Body schema: application/json
fileName
required
string
content
required
string
folder
string

Responses

Request samples

Content type
application/json
{
  • "fileName": "document.txt",
  • "content": "File content here",
  • "folder": "Documents"
}

Response samples

Content type
application/json
{
  • "success": "File saved successfully"
}

Download a file

Downloads a file from a specified folder. The file is served inline for images or as an attachment for other types.

query Parameters
file
required
string
Example: file=example.pdf

The name of the file to download

folder
string
Example: folder=Documents

The folder in which the file is located. Defaults to root.

Responses

Download a ZIP archive of selected files

Creates a ZIP archive of the specified files in a folder and serves it for download.

Request Body schema: application/json
folder
required
string
files
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "folder": "Documents",
  • "files": [
    ]
}

Extract ZIP files

Extracts ZIP archives from a specified folder and updates metadata. Returns a list of extracted files.

Request Body schema: application/json
folder
required
string
files
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "folder": "Documents",
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "extractedFiles": [
    ]
}

Access a shared file

Serves a shared file based on a share token. If the file is password protected and no password is provided, a password entry form is returned.

query Parameters
token
required
string

The share token

pass
string

The password for the share if required

Responses

Get trash items

Retrieves a list of files that have been moved to Trash, enriched with metadata such as who deleted them and when.

Responses

Response samples

Content type
application/json
[
  • { }
]

Restore trashed files

Restores files from Trash based on provided trash file identifiers and updates metadata.

Request Body schema: application/json
files
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "Items restored: file1, file2",
  • "restored": [
    ]
}

Delete trash files

Deletes trash items based on provided trash file identifiers from the trash metadata and removes the files from disk.

Request Body schema: application/json
One of
deleteAll
required
boolean

Responses

Request samples

Content type
application/json
{
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "deleted": [
    ]
}

Retrieve file tags

Retrieves tags from the createdTags.json metadata file.

Responses

Response samples

Content type
application/json
[
  • { }
]

Save file tags

Saves tag data for a specified file and updates global tag data. For folder-specific tags, saves to the folder's metadata file.

Request Body schema: application/json
file
required
string
folder
string
required
Array of objects
deleteGlobal
boolean
tagToDelete
string

Responses

Request samples

Content type
application/json
{
  • "file": "document.txt",
  • "folder": "Documents",
  • "tags": [
    ],
  • "deleteGlobal": false,
  • "tagToDelete": "OldTag"
}

Response samples

Content type
application/json
{
  • "success": "Tag data saved successfully.",
  • "globalTags": [
    ]
}

Get file list

Retrieves a list of files from a specified folder along with global tags and metadata.

query Parameters
folder
string
Example: folder=Documents

Folder name (defaults to 'root')

Responses

Response samples

Content type
application/json
{
  • "files": [
    ],
  • "globalTags": [
    ]
}

Folders

Folders

Create a new folder

Creates a new folder in the upload directory (under an optional parent) and creates an associated empty metadata file.

Request Body schema: application/json
folderName
required
string
parent
string

Responses

Request samples

Content type
application/json
{
  • "folderName": "NewFolder",
  • "parent": "Documents"
}

Response samples

Content type
application/json
{
  • "success": true
}

Delete an empty folder

Deletes a specified folder if it is empty and not the root folder, and also removes its metadata file.

Request Body schema: application/json
folder
required
string

Responses

Request samples

Content type
application/json
{
  • "folder": "Documents/Subfolder"
}

Response samples

Content type
application/json
{
  • "success": true
}

Rename a folder

Renames an existing folder and updates its associated metadata files.

Request Body schema: application/json
oldFolder
required
string
newFolder
required
string

Responses

Request samples

Content type
application/json
{
  • "oldFolder": "Documents/OldFolder",
  • "newFolder": "Documents/NewFolder"
}

Response samples

Content type
application/json
{
  • "success": true
}

Get list of folders

Retrieves the list of folders in the upload directory, including file counts and metadata file names for each folder.

query Parameters
folder
string
Example: folder=Documents

Optional folder name to filter the listing

Responses

Response samples

Content type
application/json
[
  • { }
]

Display a shared folder

Renders an HTML view of a shared folder's contents. Supports password protection, file listing with pagination, and an upload container if uploads are allowed.

query Parameters
token
required
string

The share token for the folder

pass
string

The password if the folder is protected

page
integer
Example: page=1

Page number for pagination

Responses

Download a file from a shared folder

Retrieves and serves a file from a shared folder based on a share token.

query Parameters
token
required
string

The share folder token

file
required
string

The filename to download

Responses

Upload a file to a shared folder

Handles file upload to a shared folder using a share token. Validates file size, extension, and uploads the file to the shared folder, updating metadata accordingly.

Request Body schema: multipart/form-data

Multipart form data containing the share token and file to upload.

token
required
string
fileToUpload
required
string <binary>

Responses

Uploads

Uploads

Handle file upload

Handles file uploads for both chunked and non-chunked (full) uploads. Validates CSRF, user authentication, and permissions, and processes file uploads accordingly. On success, returns a JSON status for chunked uploads or redirects for full uploads.

Request Body schema: multipart/form-data

Multipart form data for file upload. For chunked uploads, include fields like 'resumableChunkNumber', 'resumableTotalChunks', 'resumableIdentifier', 'resumableFilename', etc.

token
required
string

Share token or upload token.

fileToUpload
required
string <binary>

The file to upload.

resumableChunkNumber
integer

Chunk number for chunked uploads.

resumableTotalChunks
integer

Total number of chunks.

resumableFilename
string

Original filename.

folder
string

Target folder (default 'root').

Responses

Response samples

Content type
application/json
{
  • "success": "File uploaded successfully",
  • "newFilename": "5f2d7c123a_example.png",
  • "status": "chunk uploaded"
}

Remove chunked upload temporary directory

Removes the temporary directory used for chunked uploads, given a folder name matching the expected resumable pattern.

Request Body schema: application/json
folder
required
string

Responses

Request samples

Content type
application/json
{
  • "folder": "resumable_myupload123"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Temporary folder removed."
}

Users

Users

Retrieve a list of users

Returns a JSON array of users. Only available to authenticated admin users.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a new user

Adds a new user to the system. In setup mode, the new user is automatically made admin.

Request Body schema: application/json
username
required
string
password
required
string
isAdmin
boolean

Responses

Request samples

Content type
application/json
{
  • "username": "johndoe",
  • "password": "securepassword",
  • "isAdmin": true
}

Response samples

Content type
application/json
{
  • "success": "User added successfully"
}

Remove a user

Removes the specified user from the system. Cannot remove the currently logged-in user.

Request Body schema: application/json
username
required
string

Responses

Request samples

Content type
application/json
{
  • "username": "johndoe"
}

Response samples

Content type
application/json
{
  • "success": "User removed successfully"
}

Retrieve user permissions

Returns the permissions for the current user, or all permissions if the user is an admin.

Responses

Response samples

Content type
application/json
{ }

Update user permissions

Updates permissions for users. Only available to authenticated admin users.

Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "success": "User permissions updated successfully."
}

Change user password

Allows an authenticated user to change their password by verifying the old password and updating to a new one.

Request Body schema: application/json
oldPassword
required
string
newPassword
required
string
confirmPassword
required
string

Responses

Request samples

Content type
application/json
{
  • "oldPassword": "oldpass123",
  • "newPassword": "newpass456",
  • "confirmPassword": "newpass456"
}

Response samples

Content type
application/json
{
  • "success": "Password updated successfully."
}

Update user panel settings

Updates user panel settings by disabling TOTP when not enabled. Accessible to authenticated users.

Request Body schema: application/json
totp_enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "totp_enabled": false
}

Response samples

Content type
application/json
{
  • "success": "User panel updated: TOTP disabled"
}

TOTP

TOTP

Disable TOTP for the authenticated user

Clears the TOTP secret from the users file for the current user.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "TOTP disabled successfully."
}

Recover TOTP

Verifies a recovery code to disable TOTP and finalize login.

Request Body schema: application/json
recovery_code
required
string

Responses

Request samples

Content type
application/json
{
  • "recovery_code": "ABC123DEF456"
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Generate and save a new TOTP recovery code

Generates a new TOTP recovery code for the authenticated user, stores its hash, and returns the plain text recovery code.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "recoveryCode": "ABC123DEF456"
}

Set up TOTP and generate a QR code

Generates (or retrieves) the TOTP secret for the user and builds a QR code image for scanning.

Responses

Verify TOTP code

Verifies a TOTP code and completes login for pending users or validates TOTP for setup verification.

Request Body schema: application/json
totp_code
required
string

Responses

Request samples

Content type
application/json
{
  • "totp_code": "123456"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "message": "Login successful"
}