M
MegaVault
DashboardGitHub
Documentation

File Management API

Complete reference for file upload, download, organization, and management operations in MegaVault.

Table of Contents

File Management Overview

The File Management API provides comprehensive functionality for handling files, including upload, download, organization, metadata management, and sharing.

File Operations

Core file management

  • ✅ Upload files (multipart)
  • ✅ Download files
  • ✅ File metadata management
  • ✅ File versioning

Organization

File structure management

  • ✅ Folder creation/management
  • ✅ File moving/copying
  • ✅ Tagging and categorization
  • ✅ Search and filtering

Sharing & Security

Access control

  • ✅ Public/private files
  • ✅ Share links generation
  • ✅ Access permissions
  • ✅ Expiring links
💡

Authentication Required

All file management endpoints require authentication. Include the JWT token in the Authorization header.

List Files

Retrieve a list of files and folders with pagination, filtering, and sorting options.

Request
GET /api/files?folder=/documents&page=1&limit=20&sort=name&order=asc
Authorization: Bearer YOUR_JWT_TOKEN

Query Parameters

ParameterTypeDescription
folderstringFolder path (default: "/")
pagenumberPage number (default: 1)
limitnumberItems per page (default: 20, max: 100)
sortstringSort field: name, size, createdAt, modifiedAt
orderstringSort order: asc, desc
searchstringSearch query for file names

Response

Success Response (200)
{
  "success": true,
  "data": {
    "files": [
      {
        "id": "file_123456789",
        "name": "document.pdf",
        "type": "file",
        "mimeType": "application/pdf",
        "size": 2048576,
        "folder": "/documents",
        "url": "https://storage.example.com/files/document.pdf",
        "thumbnailUrl": "https://storage.example.com/thumbnails/document.jpg",
        "createdAt": "2024-01-15T10:30:00Z",
        "modifiedAt": "2024-01-16T14:20:00Z",
        "isPublic": false,
        "tags": ["important", "work"],
        "metadata": {
          "description": "Project specification document"
        }
      },
      {
        "id": "folder_987654321",
        "name": "images",
        "type": "folder",
        "folder": "/documents",
        "itemCount": 15,
        "createdAt": "2024-01-10T09:15:00Z",
        "modifiedAt": "2024-01-18T16:45:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    },
    "currentFolder": {
      "path": "/documents",
      "name": "Documents",
      "parent": "/"
    }
  }
}

Upload File

Upload a new file to the specified folder with optional metadata.

Request (Multipart Form Data)
POST /api/files/upload
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: multipart/form-data

Form Data:
file: [FILE_BINARY_DATA]
folder: "/documents"
description: "Important project file"
tags: "work,important"
isPublic: false

Form Fields

  • file: File binary data (required)
  • folder: Destination folder path (default: "/")
  • description: File description (optional)
  • tags: Comma-separated tags (optional)
  • isPublic: Make file publicly accessible (default: false)

Response

Success Response (201)
{
  "success": true,
  "data": {
    "id": "file_123456789",
    "name": "document.pdf",
    "originalName": "Project_Spec_v2.pdf",
    "mimeType": "application/pdf",
    "size": 2048576,
    "folder": "/documents",
    "url": "https://storage.example.com/files/document.pdf",
    "thumbnailUrl": "https://storage.example.com/thumbnails/document.jpg",
    "uploadedAt": "2024-01-20T15:30:00Z",
    "isPublic": false,
    "tags": ["work", "important"],
    "metadata": {
      "description": "Important project file"
    }
  }
}

File Size Limits

  • Free Plan: 10 MB per file
  • Pro Plan: 100 MB per file
  • Enterprise: 1 GB per file

Get File Info

Retrieve detailed information about a specific file.

Request
GET /api/files/file_123456789
Authorization: Bearer YOUR_JWT_TOKEN

Response

Success Response (200)
{
  "success": true,
  "data": {
    "id": "file_123456789",
    "name": "document.pdf",
    "originalName": "Project_Spec_v2.pdf",
    "mimeType": "application/pdf",
    "size": 2048576,
    "folder": "/documents",
    "url": "https://storage.example.com/files/document.pdf",
    "downloadUrl": "https://api.example.com/api/files/file_123456789/download",
    "thumbnailUrl": "https://storage.example.com/thumbnails/document.jpg",
    "createdAt": "2024-01-15T10:30:00Z",
    "modifiedAt": "2024-01-16T14:20:00Z",
    "lastAccessedAt": "2024-01-20T11:15:00Z",
    "downloadCount": 5,
    "isPublic": false,
    "shareLink": null,
    "tags": ["important", "work"],
    "metadata": {
      "description": "Project specification document",
      "version": "2.0"
    },
    "owner": {
      "id": "user_123",
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

Download File

Download a file by its ID. Returns the file binary data.

Request
GET /api/files/file_123456789/download
Authorization: Bearer YOUR_JWT_TOKEN

Response

Success Response (200)
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 2048576
Content-Disposition: attachment; filename="document.pdf"
Cache-Control: private, max-age=3600

[FILE_BINARY_DATA]

Query Parameters

  • inline: Display file inline instead of download (optional)
  • thumbnail: Download thumbnail version if available (optional)

Update File

Update file metadata, move to different folder, or modify sharing settings.

Request
PUT /api/files/file_123456789
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "name": "updated-document.pdf",
  "folder": "/documents/archived",
  "description": "Updated project specification",
  "tags": ["archived", "project", "spec"],
  "isPublic": true,
  "metadata": {
    "version": "3.0",
    "author": "John Doe"
  }
}

Response

Success Response (200)
{
  "success": true,
  "data": {
    "id": "file_123456789",
    "name": "updated-document.pdf",
    "folder": "/documents/archived",
    "modifiedAt": "2024-01-20T16:45:00Z",
    "isPublic": true,
    "shareLink": "https://share.example.com/f/abc123def456",
    "tags": ["archived", "project", "spec"],
    "metadata": {
      "description": "Updated project specification",
      "version": "3.0",
      "author": "John Doe"
    }
  }
}

Delete File

Permanently delete a file. This action cannot be undone.

Request
DELETE /api/files/file_123456789
Authorization: Bearer YOUR_JWT_TOKEN

Response

Success Response (200)
{
  "success": true,
  "message": "File deleted successfully",
  "data": {
    "id": "file_123456789",
    "name": "document.pdf",
    "deletedAt": "2024-01-20T17:30:00Z"
  }
}
⚠️

Permanent Deletion

File deletion is permanent and cannot be undone. Consider implementing a trash/recycle bin feature in your application for better user experience.

Folder Operations

Create, manage, and organize folders for better file organization.

Create Folder

Request
POST /api/files/folders
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "name": "New Project",
  "path": "/documents/projects",
  "description": "Project files and documentation"
}

Move Files

Request
POST /api/files/move
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "fileIds": ["file_123", "file_456"],
  "destinationFolder": "/documents/archived"
}

Copy Files

Request
POST /api/files/copy
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "fileIds": ["file_123"],
  "destinationFolder": "/backup",
  "preserveMetadata": true
}

Related Topics

Authentication →

Required for all file operations

User Management →

Manage user storage quotas

Error Handling →

Handle file operation errors