Storage API ​

Overview ​

The Storage API provides comprehensive file management capabilities within the user's dedicated storage space (/mnt/swiftor/users/{username}/storage). It allows for listing, uploading, downloading, creating, deleting, and moving files and folders, as well as reading and writing text file content.

Endpoints ​

List Files & Folders (GET /) ​

Retrieves a hierarchical list of all files and folders within the user's storage space, including hidden items (those starting with .).

Response ​

Returns an object containing a files array. Each element represents a file or folder with properties like id (relative path), name, isDir, modDate, size (for files), parentId, childrenIds (for folders), and isHidden.

{
  "files": [
    {
      "id": "root",
      "name": "/",
      "isDir": true,
      "modDate": 1678886400000,
      "childrenIds": ["my_folder", "my_file.txt", ".hidden_folder"]
    },
    {
      "id": "my_folder",
      "name": "my_folder",
      "isDir": true,
      "modDate": 1678886401000,
      "parentId": "root",
      "childrenIds": ["my_folder/nested_file.log"],
      "isHidden": false
    },
    {
      "id": ".hidden_folder",
      "name": ".hidden_folder",
      "isDir": true,
      "modDate": 1678886403000,
      "parentId": "root",
      "childrenIds": [],
      "isHidden": true
    },
    {
      "id": "my_file.txt",
      "name": "my_file.txt",
      "isDir": false,
      "modDate": 1678886402000,
      "size": 1024,
      "parentId": "root",
      "isHidden": false
    },
    {
      "id": "my_folder/nested_file.log",
      "name": "nested_file.log",
      "isDir": false,
      "modDate": 1678886404000,
      "size": 512,
      "parentId": "my_folder",
      "isHidden": false
    }
    // ... other files/folders
  ]
}

Upload Files (POST /upload/{folder_path:path}) ​

Uploads one or more files to the specified folder path within the user's storage. If the target folder path doesn't exist, it will be created.

• Path Parameter:
  • {folder_path}: The relative path of the destination folder (e.g., my_folder or existing_folder/new_subfolder). Use . for the root directory.
• Request Body: multipart/form-data containing one or more files.

Response (Success) ​

{
  "success": true,
  "files": [
    { "name": "uploaded_file1.zip", "size": 20480, "modDate": 1678886405000 },
    { "name": "image.png", "size": 5120, "modDate": 1678886406000 }
  ]
}

Create Folder (POST /create-folder/{folder_path:path}) ​

Creates a new folder at the specified path. Parent directories will be created if they don't exist.

• Path Parameter:
  • {folder_path}: The relative path of the folder to create (e.g., new_data_folder or existing_folder/another_level).

Response (Success) ​

{
  "success": true,
  "folder": {
    "path": "new_data_folder",
    "modDate": 1678886407000
  }
}

Create File (POST /create-file/{file_path:path}) ​

Creates a new, empty text file (or a file with initial content) at the specified path. Parent directories will be created if they don't exist.

• Path Parameter:
  • {file_path}: The relative path of the file to create (e.g., config.json or my_folder/notes.txt).
• Request Body (optional, JSON):
  • To create with initial content: {"content": "Initial file text here"}
  • To create an empty file, send an empty body or {"content": ""}.

Response (Success) ​

{
  "success": true,
  "file": {
    "path": "my_folder/notes.txt",
    "modDate": 1678886408000,
    "size": 21 // Size of the initial content
  }
}

Delete File or Folder (DELETE /{path:path}) ​

Deletes a file or folder.

• Path Parameter:
  • {path}: The relative path of the file or folder to delete.
• Query Parameter:
  • permanent (boolean, optional):
    • If true, the item is deleted permanently.
    • If false or omitted, the item is moved to the user's trash directory (/mnt/swiftor/users/{username}/trash), preserving its relative path.

Response (Success) ​

{
  "success": true
}

Move Files/Folders (POST /move) ​

Moves one or more files or folders to a destination folder.

Request Body (JSON) ​

{
  "source_paths": ["file_to_move.txt", "folder_to_move"],
  "destination": "target_folder/sub_folder"
}

• source_paths (List[string], required): A list of relative paths of items to move.
• destination (string, required): The relative path of the destination folder. It will be created if it doesn't exist.

Response (Success) ​

{
  "success": true,
  "moved": ["file_to_move.txt", "folder_to_move"] // List of paths successfully moved
}

Download File or Folder (GET /download/{path:path}) ​

Downloads a single file or an entire folder (as a ZIP archive).

• Path Parameter:
  • {path}: The relative path of the file or folder to download.

Behavior ​

• Single File: Returns the file directly with Content-Disposition set to the filename and Content-Type: application/octet-stream.
• Folder: Creates a ZIP archive of the folder's contents in memory and returns it as a StreamingResponse with Content-Type: application/zip. The Content-Disposition filename will be {folder_name}.zip.

Response ​

The raw file data or ZIP archive data.

Download Multiple Files/Folders (POST /download-multiple) ​

Downloads multiple specified files and/or folders as a single ZIP archive.

Request Body (JSON) ​

[
  "file1.txt",
  "important_folder",
  "another_folder/data.csv"
]

• A list of relative paths of items to include in the archive.

Behavior ​

• Creates a ZIP archive containing all specified items, preserving the directory structure for included folders.
• Returns the archive as a StreamingResponse with Content-Type: application/zip.
• The Content-Disposition filename will be files_{timestamp}.zip.

Response ​

The raw ZIP archive data.

Get File Content (GET /{file_path:path}) ​

Retrieves the text content of a specified file.

• Path Parameter:
  • {file_path}: The relative path of the text file to read.

Response (Success) ​

{
  "content": "The text content of the file.\nWith multiple lines."
}

Errors ​

• 404 Not Found: If the file doesn't exist.
• 400 Bad Request: If the path points to a folder or the file is not UTF-8 decodable (binary).

Save File Content (PUT /{file_path:path}) ​

Writes or overwrites the text content of a specified file. Parent directories will be created if they don't exist.

• Path Parameter:
  • {file_path}: The relative path of the text file to write.
• Request Body (JSON):
  • {"content": "New file content to save."} (The content key is required).

Response (Success) ​

{
  "success": true,
  "file": {
    "path": "config.json",
    "size": 512,
    "modDate": 1678886409000
  }
}