GlueAuth Filebox API Documentation

Overview

FileBox is a comprehensive file management system that provides secure file storage, organization, and collaboration features. This API enables you to upload, manage, and organize files with advanced features like virus scanning, folder management, and usage analytics.

Base URL: https://api.filebox.com/api/v1 API Version: v1 Authentication: Bearer Token (JWT)

Authentication

User Authentication

Register Account

POST /auth/register

Creates a new user account with email verification.

Request Body:

{
  "phoneNumber": "+1234567890",
  "password": "SecurePass123!",
  "email": "user@example.com",
  "verificationChannel": "EMAIL"
}

Response:

{
  "success": true,
  "httpStatus": "CREATED",
  "message": "User account created successful, please verify your email",
  "action_time": "2025-01-20T10:30:00"
}

Login

POST /auth/login

Authenticate user and receive access tokens.

Request Body:

{
  "phoneEmailOrUserName": "user@example.com",
  "password": "SecurePass123!"
}

Response:

{
  "success": true,
  "message": "Account login successful",
  "data": {
    "accessToken": "eyJhbGciOiJIUzM4NCJ9...",
    "refreshToken": "eyJhbGciOiJIUzM4NCJ9...",
    "userData": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userName": "user123",
      "email": "user@example.com",
      "isVerified": true,
      "roles": ["ROLE_NORMAL_USER"]
    }
  }
}

Refresh Token

POST /auth/refreshToken

Refresh expired access token using refresh token.

Request Body:

{
  "refreshToken": "eyJhbGciOiJIUzM4NCJ9..."
}

Verify Email OTP

POST /auth/verify-otp

Verify email address using OTP code.

Request Body:

{
  "email": "user@example.com",
  "code": "123456"
}

Request New OTP

POST /auth/request-otp

Request a new OTP for email verification.

Request Body:

{
  "email": "user@example.com"
}

Password Reset

Request Password Reset

POST /auth/psw-request-otp

Request OTP for password reset.

Request Body:

{
  "email": "user@example.com"
}

Verify OTP and Reset Password

POST /auth/verify-otp-and-reset

Verify OTP and set new password.

Request Body:

{
  "email": "user@example.com",
  "code": "123456",
  "newPassword": "NewSecurePass123!"
}

User Management

Get All Users

GET /auth/all-users

Retrieve all registered users (admin only).

Get Single User

GET /auth/single-user/{userId}

Retrieve specific user information.

API Key Management

API Keys provide programmatic access to FileBox services with specific permissions and environments.

Generate API Key

POST /api-key/generate

Generate a new API key with specified permissions.

Request Body:

{
  "name": "Production File Access",
  "permissions": ["FILES_READ", "FILES_WRITE", "FOLDERS_READ"],
  "environment": "PRODUCTION",
  "description": "API key for production file operations"
}

Response:

{
  "success": true,
  "message": "Api key generated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production File Access",
    "apiKey": "fbk_live_1234567890abcdef...",
    "apiKeyPrefix": "fbk_***************************cdef",
    "permissions": ["FILES_READ", "FILES_WRITE", "FOLDERS_READ"],
    "environment": "PRODUCTION",
    "description": "API key for production file operations",
    "active": true,
    "createdAt": "2025-01-20T10:30:00"
  }
}

Get API Key Details

GET /api-key/{apiKeyId}

Retrieve details of a specific API key.

Response:

{
  "success": true,
  "data": {
    "apiKeyId": "550e8400-e29b-41d4-a716-446655440000",
    "apiKeyPrefix": "fbk_***************************cdef",
    "description": "API key for production file operations",
    "active": true,
    "name": "Production File Access",
    "environment": "PRODUCTION",
    "lastUsed": "2025-01-20T15:45:00",
    "usageCount": 1247
  }
}

List My API Keys

GET /api-key/my-keys

Retrieve all API keys for the authenticated user.

File Management

File Upload

Single File Upload (Synchronous)

POST /files/upload-single-sync
Content-Type: multipart/form-data

Upload a single file synchronously with immediate response.

Form Data:

file: File to upload (required)
folderId: Target folder UUID (optional, null = root)

Response:

{
  "success": true,
  "message": "File uploaded successfully",
  "data": {
    "fileId": "550e8400-e29b-41d4-a716-446655440000",
    "fileName": "document.pdf",
    "folderId": "660e8400-e29b-41d4-a716-446655440000",
    "folderPath": "Documents/Work",
    "fileSize": 2048576,
    "mimeType": "application/pdf",
    "scanStatus": "CLEAN",
    "uploadedAt": "2025-01-20T10:30:00"
  }
}

Batch File Upload (Synchronous)

POST /files/upload-batch-sync
Content-Type: multipart/form-data

Upload multiple files synchronously.

Form Data:

files: Multiple files to upload (required)
folderId: Target folder UUID (optional)
stopOnFirstError: Stop if any file fails (default: false)
allowDuplicates: Allow duplicate filenames (default: false)

Response:

{
  "success": true,
  "message": "Uploaded 3 file(s), 1 failed",
  "data": {
    "totalFilesRequested": 4,
    "successfulUploads": 3,
    "failedUploads": 1,
    "uploadedFiles": [
      {
        "fileId": "550e8400-e29b-41d4-a716-446655440000",
        "fileName": "document1.pdf",
        "fileSize": 2048576,
        "scanStatus": "CLEAN"
      }
    ],
    "failures": [
      {
        "fileName": "large_file.zip",
        "reason": "File size exceeds maximum limit of 100MB",
        "fileSize": 104857600
      }
    ],
    "summary": "Uploaded 3 file(s), 1 failed"
  }
}

Single File Upload (Asynchronous)

POST /files/upload-single-async
Content-Type: multipart/form-data

Upload a single file asynchronously with real-time progress tracking.

Response:

{
  "success": true,
  "message": "Upload started in background",
  "data": {
    "uploadId": "upload_1234567890",
    "statusUrl": "/api/v1/files/upload-status/upload_1234567890"
  }
}

Batch File Upload (Asynchronous)

POST /files/upload-batch-async
Content-Type: multipart/form-data

Upload multiple files asynchronously with detailed progress tracking.

Form Data:

files: Multiple files to upload
folderId: Target folder UUID (optional)
maxConcurrentUploads: Maximum concurrent uploads (default: 3, max: 10)
stopOnFirstError: Stop batch on first error (default: false)
allowDuplicates: Allow duplicate filenames (default: false)

Response:

{
  "success": true,
  "message": "Batch upload started",
  "data": {
    "batchId": "batch_1234567890",
    "totalFiles": 5,
    "statusUrl": "/api/v1/files/batch-status/batch_1234567890",
    "streamUrl": "/api/v1/files/batch-status/batch_1234567890/stream"
  }
}

Upload Progress Tracking

Get Upload Status

GET /files/upload-status/{uploadId}

Get current status of an asynchronous upload.

Response:

{
  "uploadId": "upload_1234567890",
  "fileName": "document.pdf",
  "stage": "UPLOADING",
  "progress": 75,
  "message": "Uploading to storage...",
  "completed": false,
  "failed": false,
  "startTime": "2025-01-20T10:30:00",
  "lastUpdated": "2025-01-20T10:31:30"
}

Stream Upload Progress (SSE)

GET /files/upload-status/{uploadId}/stream
Accept: text/event-stream

Real-time upload progress via Server-Sent Events.

Event Types:

progress: Upload progress updates
complete: Upload completion
error: Upload errors

Get Batch Upload Status

GET /files/batch-status/{batchId}

Get status of batch upload operation.

Response:

{
  "success": true,
  "message": "Batch status retrieved successfully",
  "data": {
    "batchId": "batch_1234567890",
    "totalFiles": 5,
    "completedFiles": 3,
    "failedFiles": 1,
    "overallProgress": 75.0,
    "status": "PROCESSING",
    "startTime": "2025-01-20T10:30:00",
    "lastUpdated": "2025-01-20T10:33:00",
    "files": {
      "file_001": {
        "uploadId": "file_001",
        "fileName": "doc1.pdf",
        "stage": "COMPLETED",
        "progress": 100,
        "completed": true
      }
    },
    "message": "Processing files..."
  }
}

Stream Batch Progress (SSE)

GET /files/batch-status/{batchId}/stream
Accept: text/event-stream

Real-time batch upload progress via Server-Sent Events.

Event Types:

batch-progress: Overall batch progress
file-progress: Individual file progress
batch-complete: Batch completion
batch-error: Batch errors

Cancel Batch Upload

POST /files/batch-status/{batchId}/cancel

Cancel an ongoing batch upload (best effort).

Cleanup Batch Status

DELETE /files/batch-status/{batchId}

Clean up batch upload status and progress data.

File Operations

Get File Information

GET /files/{fileId}

Retrieve detailed information about a file.

Response:

{
  "success": true,
  "message": "File info retrieved successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "document.pdf",
    "size": 2048576,
    "sizeFormatted": "2.0 MB",
    "mimeType": "application/pdf",
    "extension": "pdf",
    "category": "document",
    "scanStatus": "CLEAN",
    "folderPath": "Documents/Work",
    "canPreview": true,
    "canDownload": true,
    "uploadedAt": "2025-01-20T10:30:00",
    "updatedAt": "2025-01-20T10:30:00"
  }
}

Download File

GET /files/{fileId}/download

Download a file. Returns the file content with appropriate headers.

Response Headers:

Content-Type: application/pdf
Content-Disposition: attachment; filename="document.pdf"
Content-Length: 2048576

Preview File

GET /files/{fileId}/preview

Preview a file (for supported file types like images, PDFs, text files).

Response Headers:

Content-Type: application/pdf
Content-Disposition: inline; filename="document.pdf"

Move File to Trash

POST /files/{fileId}/trash

Move a file to trash (soft delete).

Response:

{
  "success": true,
  "message": "File moved to trash successfully"
}

Restore File from Trash

POST /files/{fileId}/restore

Restore a file from trash.

Move File

POST /files/{fileId}/move

Move a file to a different folder.

Request Body:

{
  "destinationFolderId": "660e8400-e29b-41d4-a716-446655440000"
}

Copy File

POST /files/{fileId}/copy

Create a copy of a file in a different location.

Request Body:

{
  "destinationFolderId": "660e8400-e29b-41d4-a716-446655440000"
}

Bulk Operations

Bulk Delete Files

POST /files/bulk-trash

Move multiple files to trash.

Request Body:

{
  "fileIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440000"
  ]
}

Response:

{
  "success": true,
  "message": "Successfully moved 2 file(s) to trash",
  "data": {
    "totalFilesRequested": 2,
    "successfulDeletions": 2,
    "failedDeletions": 0,
    "deletedFileIds": [
      "550e8400-e29b-41d4-a716-446655440000",
      "660e8400-e29b-41d4-a716-446655440000"
    ],
    "failures": [],
    "summary": "Successfully moved 2 file(s) to trash"
  }
}

Bulk Copy Files

POST /files/bulk-copy

Copy multiple files to a destination folder.

Request Body:

{
  "fileIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "destinationFolderId": "770e8400-e29b-41d4-a716-446655440000"
}

Bulk Move Files

POST /files/bulk-move

Move multiple files to a destination folder.

Bulk Restore Files

POST /files/bulk-restore

Restore multiple files from trash.

Request Body:

{
  "fileIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440000"
  ]
}

Trash Management

Get Trash Files

GET /files/trash?page=0&size=20

Retrieve files in trash with pagination.

Query Parameters:

page: Page number (default: 0)
size: Page size (default: 20, max: 100)

Response:

{
  "success": true,
  "message": "Trash files retrieved successfully",
  "data": {
    "summary": {
      "totalTrashFiles": 15,
      "totalTrashSize": 50331648,
      "totalTrashSizeFormatted": "48.0 MB",
      "oldestDeletedAt": "2025-01-15T14:30:00",
      "newestDeletedAt": "2025-01-20T16:45:00"
    },
    "files": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "old_document.pdf",
        "size": 2048576,
        "sizeFormatted": "2.0 MB",
        "mimeType": "application/pdf",
        "extension": "pdf",
        "category": "document",
        "scanStatus": "CLEAN",
        "originalFolderPath": "Documents/Work",
        "deletedAt": "2025-01-20T16:45:00",
        "originalCreatedAt": "2025-01-15T10:30:00",
        "canRestore": true
      }
    ],
    "pagination": {
      "page": 0,
      "size": 20,
      "totalElements": 15,
      "totalPages": 1,
      "hasNext": false,
      "hasPrevious": false,
      "isFirst": true,
      "isLast": true
    }
  }
}

Empty Trash

POST /files/empty-trash

Permanently delete files from trash.

Request Body:

{
  "fileIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "continueOnError": true
}

Response:

{
  "success": true,
  "message": "Permanently deleted 1 file(s)",
  "data": {
    "totalFilesProcessed": 1,
    "successfulDeletions": 1,
    "failedDeletions": 0,
    "permanentlyDeletedFileIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "failures": [],
    "summary": "Permanently deleted 1 file(s)",
    "totalSpaceFreed": 2048576,
    "totalSpaceFreedFormatted": "2.0 MB"
  }
}

Search

Search Files and Folders

GET /files/search?q=document&page=0&size=20

Search for files and folders across the entire account.

Query Parameters:

q: Search query (required)
page: Page number (default: 0)
size: Page size (default: 20, max: 100)

Response:

{
  "success": true,
  "message": "Search completed successfully",
  "data": {
    "query": "document",
    "contents": {
      "folders": [
        {
          "id": "660e8400-e29b-41d4-a716-446655440000",
          "name": "Documents",
          "type": "folder",
          "folderPath": "Root",
          "itemCount": 25,
          "hasSubfolders": true,
          "createdAt": "2025-01-15T10:00:00",
          "updatedAt": "2025-01-20T14:30:00"
        }
      ],
      "files": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "important_document.pdf",
          "type": "file",
          "size": 2048576,
          "sizeFormatted": "2.0 MB",
          "mimeType": "application/pdf",
          "extension": "pdf",
          "category": "document",
          "scanStatus": "CLEAN",
          "folderPath": "Documents/Work",
          "canPreview": true,
          "canDownload": true,
          "createdAt": "2025-01-18T15:30:00",
          "updatedAt": "2025-01-18T15:30:00"
        }
      ]
    },
    "pagination": {
      "page": 0,
      "size": 20,
      "totalElements": 12,
      "totalPages": 1,
      "hasNext": false,
      "hasPrevious": false,
      "isFirst": true,
      "isLast": true
    },
    "summary": {
      "totalResults": 12,
      "totalFolders": 3,
      "totalFiles": 9
    }
  }
}

Search in Specific Folder

GET /files/search-in-folder?folderId={folderId}&q=document&page=0&size=20

Search for files and folders within a specific folder.

Query Parameters:

folderId: Target folder UUID (optional, null = search from root)
q: Search query (required)
page: Page number (default: 0)
size: Page size (default: 20, max: 100)

Folder Management

Folder Operations

Create Folder

POST /folders

Create a new folder.

Request Body:

{
  "folderName": "New Project",
  "parentFolderId": "660e8400-e29b-41d4-a716-446655440000"
}

Response:

{
  "success": true,
  "message": "Folder created successfully",
  "data": {
    "folderId": "770e8400-e29b-41d4-a716-446655440000",
    "folderName": "New Project",
    "parentFolderId": "660e8400-e29b-41d4-a716-446655440000",
    "fullPath": "Documents/New Project",
    "createdAt": "2025-01-20T10:30:00"
  }
}

Get Root Folders

GET /folders

Retrieve all root-level folders for the authenticated user.

Response:

{
  "success": true,
  "message": "Root folders retrieved successfully",
  "data": [
    {
      "folderId": "660e8400-e29b-41d4-a716-446655440000",
      "folderName": "Documents",
      "parentFolderId": null,
      "fullPath": "Documents",
      "createdAt": "2025-01-15T10:00:00",
      "hasSubFolders": true,
      "fileCount": 15
    },
    {
      "folderId": "770e8400-e29b-41d4-a716-446655440000",
      "folderName": "Images",
      "parentFolderId": null,
      "fullPath": "Images",
      "createdAt": "2025-01-16T14:20:00",
      "hasSubFolders": false,
      "fileCount": 8
    }
  ]
}

Get Subfolders

GET /folders/{parentFolderId}/children

Retrieve all subfolders of a specific folder.

Get Folder Contents

GET /folders/{folderId}/contents?page=0&size=20

Retrieve contents (files and subfolders) of a specific folder with pagination.

Query Parameters:

page: Page number (default: 0)
size: Page size (default: 20)
maxSize: Maximum page size (default: 100)

Response:

{
  "success": true,
  "message": "Folder contents retrieved successfully",
  "data": {
    "folder": {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Documents",
      "fullPath": "Documents",
      "isRoot": false,
      "createdAt": "2025-01-15T10:00:00",
      "updatedAt": "2025-01-20T14:30:00",
      "breadcrumbs": [
        {
          "id": null,
          "name": "Root",
          "path": "",
          "isCurrent": false
        },
        {
          "id": "660e8400-e29b-41d4-a716-446655440000",
          "name": "Documents",
          "path": "Documents",
          "isCurrent": true
        }
      ]
    },
    "statistics": {
      "totalItems": 18,
      "totalFolders": 3,
      "totalFiles": 15,
      "totalSize": 52428800,
      "totalSizeFormatted": "50.0 MB",
      "currentPage": {
        "items": 18,
        "folders": 3,
        "files": 15
      }
    },
    "contents": {
      "folders": [
        {
          "id": "770e8400-e29b-41d4-a716-446655440000",
          "name": "Work",
          "type": "folder",
          "itemCount": 12,
          "size": null,
          "sizeFormatted": null,
          "hasSubfolders": true,
          "createdAt": "2025-01-16T09:15:00",
          "updatedAt": "2025-01-19T16:30:00"
        }
      ],
      "files": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "report.pdf",
          "type": "file",
          "size": 2048576,
          "sizeFormatted": "2.0 MB",
          "mimeType": "application/pdf",
          "extension": "pdf",
          "category": "document",
          "scanStatus": "CLEAN",
          "scanDate": "2025-01-18T15:30:00",
          "createdAt": "2025-01-18T15:30:00",
          "updatedAt": "2025-01-18T15:30:00"
        }
      ]
    },
    "pagination": {
      "page": 0,
      "size": 20,
      "totalElements": 18,
      "totalPages": 1,
      "hasNext": false,
      "hasPrevious": false,
      "isFirst": true,
      "isLast": true
    }
  }
}

Get Root Folder Contents

GET /folders/root/contents?page=0&size=20

Retrieve contents of the root folder (equivalent to GET /folders/null/contents).

Analytics and Usage

Usage Analytics

Get Usage Summary

GET /analytics/usage-summary

Get comprehensive usage summary for the authenticated user.

Response:

{
  "success": true,
  "message": "Usage summary retrieved successfully",
  "data": {
    "userInfo": {
      "userName": "john_doe",
      "email": "john@example.com",
      "accountCreated": "2025-01-01T10:00:00",
      "lastLogin": "2025-01-20T16:45:00",
      "isVerified": true,
      "accountStatus": "Active"
    },
    "storageInfo": {
      "totalStorageUsed": 104857600,
      "totalStorageUsedFormatted": "100.0 MB",
      "activeStorageUsed": 94371840,
      "activeStorageUsedFormatted": "90.0 MB",
      "trashStorageUsed": 10485760,
      "trashStorageUsedFormatted": "10.0 MB",
      "storageQuota": 5368709120,
      "storageQuotaFormatted": "5.0 GB",
      "availableStorage": 5273837480,
      "availableStorageFormatted": "4.9 GB",
      "storageUsagePercentage": 1.95
    },
    "fileStatistics": {
      "totalFiles": 125,
      "activeFiles": 120,
      "deletedFiles": 5,
      "cleanFiles": 118,
      "infectedFiles": 0,
      "pendingScanFiles": 2,
      "averageFileSize": 838860.8,
      "averageFileSizeFormatted": "819.2 KB",
      "largestFile": {
        "fileName": "presentation.pptx",
        "fileSize": 15728640,
        "fileSizeFormatted": "15.0 MB",
        "createdAt": "2025-01-18T14:20:00"
      },
      "smallestFile": {
        "fileName": "note.txt",
        "fileSize": 256,
        "fileSizeFormatted": "256 B",
        "createdAt": "2025-01-19T11:15:00"
      }
    },
    "folderStatistics": {
      "totalFolders": 28,
      "rootLevelFolders": 5,
      "maxFolderDepth": 4,
      "largestFolder": {
        "folderName": "Projects",
        "fullPath": "Documents/Projects",
        "fileCount": 45,
        "totalSize": 62914560,
        "totalSizeFormatted": "60.0 MB",
        "createdAt": "2025-01-10T09:30:00"
      },
      "mostRecentFolder": {
        "folderName": "New Designs",
        "fullPath": "Images/New Designs",
        "fileCount": 8,
        "totalSize": 5242880,
        "totalSizeFormatted": "5.0 MB",
        "createdAt": "2025-01-20T13:45:00"
      }
    },
    "activitySummary": {
      "firstUpload": "2025-01-01T11:30:00",
      "lastUpload": "2025-01-20T15:20:00",
      "totalUploads": 125,
      "uploadsThisWeek": 12,
      "uploadsThisMonth": 47,
      "totalDownloads": 0,
      "downloadsThisWeek": 0,
      "downloadsThisMonth": 0,
              "activityByDay": {
        "Jan 14": 2,
        "Jan 15": 5,
        "Jan 16": 3,
        "Jan 17": 0,
        "Jan 18": 1,
        "Jan 19": 2,
        "Jan 20": 4
      }
    },
    "fileTypeBreakdown": [
      {
        "fileType": "document",
        "category": "document",
        "count": 45,
        "totalSize": 31457280,
        "totalSizeFormatted": "30.0 MB",
        "percentage": 33.33
      },
      {
        "fileType": "image",
        "category": "image",
        "count": 32,
        "totalSize": 25165824,
        "totalSizeFormatted": "24.0 MB",
        "percentage": 26.67
      },
      {
        "fileType": "video",
        "category": "video",
        "count": 8,
        "totalSize": 20971520,
        "totalSizeFormatted": "20.0 MB",
        "percentage": 22.22
      }
    ],
    "recentActivities": [
      {
        "activityType": "UPLOAD",
        "fileName": "new_design.png",
        "fileId": "880e8400-e29b-41d4-a716-446655440000",
        "timestamp": "2025-01-20T15:20:00",
        "details": "Active file"
      },
      {
        "activityType": "UPLOAD",
        "fileName": "meeting_notes.docx",
        "fileId": "990e8400-e29b-41d4-a716-446655440000",
        "timestamp": "2025-01-20T14:45:00",
        "details": "Active file"
      }
    ],
    "securityInfo": {
      "totalScannedFiles": 120,
      "cleanFiles": 118,
      "infectedFiles": 0,
      "failedScans": 0,
      "pendingScans": 2,
      "lastScanDate": "2025-01-20T15:20:00",
      "securityAlerts": []
    }
  }
}

Get Storage Breakdown

GET /analytics/storage-breakdown

Get detailed storage usage breakdown.

Response:

{
  "success": true,
  "message": "Storage breakdown retrieved successfully",
  "data": {
    "totalStorageUsed": 104857600,
    "totalStorageUsedFormatted": "100.0 MB",
    "activeStorageUsed": 94371840,
    "activeStorageUsedFormatted": "90.0 MB",
    "trashStorageUsed": 10485760,
    "trashStorageUsedFormatted": "10.0 MB",
    "storageQuota": 5368709120,
    "storageQuotaFormatted": "5.0 GB",
    "availableStorage": 5273837480,
    "availableStorageFormatted": "4.9 GB",
    "storageUsagePercentage": 1.95
  }
}

Get Activity Summary

GET /analytics/activity-summary?days=30

Get activity summary for a specific time period.

Query Parameters:

days: Number of days to analyze (1-365, default: 30)

Response:

{
  "success": true,
  "message": "Activity summary for 30 days retrieved successfully",
  "data": {
    "firstUpload": "2025-01-01T11:30:00",
    "lastUpload": "2025-01-20T15:20:00",
    "totalUploads": 47,
    "uploadsThisWeek": 12,
    "uploadsThisMonth": 47,
    "totalDownloads": 0,
    "downloadsThisWeek": 0,
    "downloadsThisMonth": 0,
    "activityByDay": {
      "Dec 21": 0,
      "Dec 22": 1,
      "Dec 23": 2,
      "Dec 24": 0,
      "Dec 25": 0,
      "Dec 26": 1,
      "Dec 27": 3,
      "Dec 28": 2,
      "Dec 29": 1,
      "Dec 30": 0,
      "Dec 31": 2,
      "Jan 01": 5,
      "Jan 02": 3,
      "Jan 03": 4,
      "Jan 04": 2,
      "Jan 05": 1,
      "Jan 06": 0,
      "Jan 07": 0,
      "Jan 08": 3,
      "Jan 09": 2,
      "Jan 10": 4,
      "Jan 11": 1,
      "Jan 12": 2,
      "Jan 13": 3,
      "Jan 14": 2,
      "Jan 15": 5,
      "Jan 16": 3,
      "Jan 17": 0,
      "Jan 18": 1,
      "Jan 19": 2,
      "Jan 20": 4
    }
  }
}

Get Security Overview

GET /analytics/security-overview

Get security status and virus scan information.

Response:

{
  "success": true,
  "message": "Security overview retrieved successfully",
  "data": {
    "totalScannedFiles": 120,
    "cleanFiles": 118,
    "infectedFiles": 0,
    "failedScans": 0,
    "pendingScans": 2,
    "lastScanDate": "2025-01-20T15:20:00",
    "securityAlerts": []
  }
}

Get Quick Stats

GET /analytics/quick-stats

Get lightweight dashboard statistics.

Response:

{
  "success": true,
  "message": "Quick stats retrieved successfully",
  "data": {
    "totalStorageUsed": 94371840,
    "totalStorageUsedFormatted": "90.0 MB",
    "storageUsagePercentage": 1.95,
    "availableStorage": 5273837480,
    "availableStorageFormatted": "4.9 GB",
    "totalFiles": 120,
    "cleanFiles": 118,
    "infectedFiles": 0,
    "pendingScans": 2,
    "hasSecurityAlerts": false
  }
}

Error Handling

HTTP Status Codes

Status Code

Description

200

OK - Request successful

201

Created - Resource created successfully

400

Bad Request - Invalid request data

401

Unauthorized - Authentication required

403

Forbidden - Access denied

404

Not Found - Resource not found

422

Unprocessable Entity - Validation failed

500

Internal Server Error - Server error

Error Response Format

All error responses follow a consistent format:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Validation failed",
  "action_time": "2025-01-20T10:30:00",
  "data": {
    "field1": "Error message for field1",
    "field2": "Error message for field2"
  }
}

Common Error Scenarios

Validation Errors (422)

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "data": {
    "email": "Email should be valid",
    "password": "Password must be at least 8 characters long"
  }
}

Authentication Errors (401)

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token expired",
  "data": "Token expired"
}

Authorization Errors (403)

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Access denied: You don't own this file",
  "data": "Access denied: You don't own this file"
}

Resource Not Found (404)

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "File not found",
  "data": "File not found"
}

File Upload Errors (400)

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "File size exceeds maximum limit of 100MB",
  "data": "File size exceeds maximum limit of 100MB"
}

Virus Detection (400)

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "File rejected: Virus detected",
  "data": "File rejected: Virus detected"
}

Rate Limiting

Upload Limits

Single file: Maximum 100MB per file
Batch upload: Maximum 50 files per batch
Concurrent uploads: Maximum 10 concurrent uploads per user
API requests: 1000 requests per hour per user

Storage Limits

Default quota: 5GB per user
File retention: Files in trash are kept for 30 days
API key limits: 100 API keys per user

Security Features

File Security

Virus Scanning: All uploaded files are scanned using ClamAV
File Type Validation: Executable files are blocked
Access Control: Users can only access their own files
Secure Storage: Files are encrypted at rest

Authentication Security

JWT Tokens: Secure token-based authentication
Token Expiration: Access tokens expire after 7 days
Refresh Tokens: Long-lived refresh tokens (1 year)
API Key Management: Scoped permissions and environment isolation

Data Protection

HTTPS Only: All API communication over TLS
Input Validation: Comprehensive request validation
SQL Injection Protection: Parameterized queries
XSS Protection: Input sanitization

File Type Support

Supported File Types

Documents

PDF (.pdf)
Microsoft Word (.doc, .docx)
Microsoft Excel (.xls, .xlsx)
Microsoft PowerPoint (.ppt, .pptx)
Text files (.txt, .md, .rtf)
OpenDocument (.odt, .ods, .odp)

Images

JPEG (.jpg, .jpeg)
PNG (.png)
GIF (.gif)
SVG (.svg)
WebP (.webp)
TIFF (.tiff, .tif)
BMP (.bmp)

Video

MP4 (.mp4)
AVI (.avi)
MOV (.mov)
WMV (.wmv)
FLV (.flv)
WebM (.webm)

Audio

MP3 (.mp3)
WAV (.wav)
AAC (.aac)
OGG (.ogg)
FLAC (.flac)

Archives

ZIP (.zip)
RAR (.rar)
7Z (.7z)
TAR (.tar, .tar.gz)

Other

CSV (.csv)
JSON (.json)
XML (.xml)
Log files (.log)

File Categories

Files are automatically categorized based on their MIME type:

document: PDF, Word, Excel, PowerPoint, text files
image: JPEG, PNG, GIF, SVG, etc.
video: MP4, AVI, MOV, etc.
audio: MP3, WAV, AAC, etc.
spreadsheet: Excel, CSV, ODS
presentation: PowerPoint, ODP
archive: ZIP, RAR, 7Z, etc.
text: Plain text, Markdown, code files
file: Other/unknown file types

API Environments

Production Environment

Base URL: https://api.filebox.com/api/v1
Rate Limits: Standard production limits
Storage: Full quota allocation
Monitoring: Full audit logging

Testing Environment

Base URL: https://api-staging.filebox.com/api/v1
Rate Limits: Relaxed for testing
Storage: Limited quota for testing
Monitoring: Debug logging enabled

SDKs and Libraries

Official SDKs

JavaScript/Node.js: @filebox/javascript-sdk
Python: filebox-python
PHP: filebox/php-sdk
Java: com.filebox:java-sdk

Community Libraries

Ruby: filebox-ruby
Go: github.com/filebox/go-sdk
C#: FileBox.NET

Webhooks (Coming Soon)

FileBox will support webhooks for real-time notifications of file events:

Supported Events

file.uploaded - File successfully uploaded
file.deleted - File moved to trash
file.restored - File restored from trash
file.virus_detected - Virus detected in uploaded file
folder.created - New folder created
storage.quota_exceeded - Storage quota limit reached

Webhook Payload Example

{
  "event": "file.uploaded",
  "timestamp": "2025-01-20T10:30:00Z",
  "data": {
    "fileId": "550e8400-e29b-41d4-a716-446655440000",
    "fileName": "document.pdf",
    "fileSize": 2048576,
    "userId": "user_123",
    "folderPath": "Documents/Work"
  }
}

Changelog

Version 1.0.0 (Current)

Initial API release
File upload and management
Folder organization
Search functionality
Usage analytics
API key management
Virus scanning integration

Upcoming Features

v1.1.0: Webhooks support
v1.2.0: File sharing and collaboration
v1.3.0: Advanced file processing (thumbnails, compression)
v1.4.0: Team management and permissions
v1.5.0: Integration with external storage providers

Support

Getting Help

Documentation: https://docs.filebox.com
API Reference: https://api-docs.filebox.com
Support Email: support@filebox.com
Status Page: https://status.filebox.com

Community

GitHub: https://github.com/filebox/api
Discord: https://discord.gg/filebox
Stack Overflow: Tag questions with filebox-api

Legal

Terms of Service

By using the FileBox API, you agree to our Terms of Service.

Privacy Policy

Your privacy is important to us. Read our Privacy Policy.

API License

The FileBox API is provided under our standard API License Agreement.

Last updated 4 days ago