📖 API Documentation

Complete guide for programmatic access to the File Manager API. This API allows you to integrate file management into your applications, scripts, and automation workflows.

📑 Table of Contents

Authentication
- Session-Based Authentication
- API Token Authentication
Authentication Endpoints
File & Folder Operations
User Management
Admin Endpoints
Search & Storage
Complete Examples
Error Responses
Best Practices

🔐 Authentication

All API endpoints (except public file access) require authentication. The API supports two authentication methods:

Method 1: Session-Based Authentication

Use this method for web-based interactions or when you need temporary access.

Step 1: Login to Get Session Cookie

curl -c cookies.txt -X POST http://localhost:3000/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

Response:

{
  "success": true,
  "message": "Login successful"
}

Step 2: Use Session Cookie for API Calls

curl -b cookies.txt "http://localhost:3000/api/files"

Method 2: API Token Authentication (Recommended)

Use this method for scripts, automation, CI/CD pipelines, or long-running processes.

Generate Your API Token

Via Web Interface:

Login to the admin panel
Click "⚙️ Settings"
Scroll to API Token section
Click "🔑 Generate New Token"
Enter your password
Save the token securely!

Via API:

curl -b cookies.txt -X POST http://localhost:3000/api/user/generate-token \
  -H "Content-Type: application/json" \
  -d '{"password":"your_password"}'

Response:

{
  "success": true,
  "message": "API token generated successfully",
  "apiKey": "yknngagbkwqyga86qxeus5qd"
}

Use API Token

Option A: Bearer Token (Recommended)

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  http://localhost:3000/api/files

Option B: URL Parameter

curl "http://localhost:3000/api/files?apiKey=YOUR_API_TOKEN"

✅ Advantages of API Tokens:

No need to handle sessions or cookies
Perfect for automation scripts
No expiration (until manually deleted)
Can be revoked anytime without changing password
Each user has their own token

🔑 Authentication Endpoints

POST /api/login

Authenticate user and create session

Request Body:

{
  "username": "admin",
  "password": "your_password"
}

Response:

{
  "success": true,
  "message": "Login successful"
}

POST /api/logout

End current session

Response:

{
  "success": true,
  "message": "Logged out successfully"
}

GET /api/auth/status

Check authentication status

Response:

{
  "authenticated": true,
  "username": "admin"
}

📁 File & Folder Operations

GET /api/files?path={folder_path}

List files and folders in a directory

Example:

# List root directory
curl -b cookies.txt "http://localhost:3000/api/files"

# List specific folder
curl -b cookies.txt "http://localhost:3000/api/files?path=products"

# With API token
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:3000/api/files?path=products"

Response:

{
  "currentPath": "products",
  "items": [
    {
      "name": "tshirt.jpg",
      "path": "products/tshirt.jpg",
      "isDirectory": false,
      "size": 245678,
      "modified": "2024-10-09T10:30:00.000Z",
      "created": "2024-10-08T14:20:00.000Z"
    }
  ]
}

POST /api/upload

Upload one or more files

Example - Single file:

curl -b cookies.txt -X POST http://localhost:3000/api/upload \
  -F "basePath=products" \
  -F "files=@/path/to/image.jpg"

Example - Multiple files:

curl -b cookies.txt -X POST http://localhost:3000/api/upload \
  -F "basePath=products" \
  -F "files=@image1.jpg" \
  -F "files=@image2.jpg" \
  -F "files=@image3.jpg"

With API token:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  -X POST http://localhost:3000/api/upload \
  -F "basePath=products" \
  -F "files=@image.jpg"

POST /api/folder

Create a new folder

Request Body:

{
  "path": "products",
  "name": "new-folder"
}

Example:

curl -b cookies.txt -X POST http://localhost:3000/api/folder \
  -H "Content-Type: application/json" \
  -d '{"path":"","name":"documents"}'

DELETE /api/delete

Delete a file or folder (recursive)

Request Body:

{
  "path": "products/old-image.jpg"
}

Example:

curl -b cookies.txt -X DELETE http://localhost:3000/api/delete \
  -H "Content-Type: application/json" \
  -d '{"path":"products/old-image.jpg"}'

POST /api/rename

Rename a file or folder

Request Body:

{
  "path": "products/old-name.jpg",
  "newName": "new-name.jpg"
}

GET /api/download?path={file_path}

Download a file

Example:

curl -b cookies.txt "http://localhost:3000/api/download?path=products/image.jpg" \
  -o downloaded-image.jpg

👤 User Management Endpoints

GET /api/user/me

Get current user information

Response:

{
  "success": true,
  "user": {
    "username": "john",
    "role": "user",
    "hasApiKey": true,
    "apiKey": "yknngagbkwqyga86qxeus5qd",
    "createdAt": "2025-01-15T10:00:00.000Z"
  }
}

POST /api/user/change-password

Change your password

Request Body:

{
  "oldPassword": "current_password",
  "newPassword": "new_password_min_8_chars"
}

POST /api/user/generate-token

Generate a new API token

Request Body:

{
  "password": "your_password"
}

Response:

{
  "success": true,
  "message": "API token generated successfully",
  "apiKey": "yknngagbkwqyga86qxeus5qd"
}

⚠️ Important: Save this API token securely. Treat it like a password!

DELETE /api/user/delete-token

Delete your API token

Request Body:

{
  "password": "your_password"
}

👮 Admin Endpoints

These endpoints require admin role.

GET /api/admin/users

List all users (admin only)

Response:

{
  "success": true,
  "users": [
    {
      "username": "admin",
      "role": "admin",
      "hasApiKey": true,
      "createdAt": "2025-01-01T00:00:00.000Z"
    },
    {
      "username": "john",
      "role": "user",
      "hasApiKey": false,
      "createdAt": "2025-01-15T10:00:00.000Z"
    }
  ]
}

POST /api/admin/users

Create a new user (admin only)

Request Body:

{
  "username": "newuser",
  "role": "user"
}

Response:

{
  "success": true,
  "message": "User created successfully",
  "user": {
    "username": "newuser",
    "password": "randomly_generated_password_123",
    "role": "user"
  }
}

⚠️ Important: The password is only shown once. Save it securely!

DELETE /api/admin/users/{username}

Delete a user (admin only)

Example:

curl -b cookies.txt -X DELETE http://localhost:3000/api/admin/users/olduser

# Or with API token
curl -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -X DELETE http://localhost:3000/api/admin/users/olduser

Note: Admins cannot delete their own account.

🔍 Search & Storage

GET /api/search?q={query}

Search for files and folders

Example:

curl -b cookies.txt "http://localhost:3000/api/search?q=tshirt"

GET /api/storage

Get storage statistics

Response:

{
  "totalSize": 15728640,
  "fileCount": 42,
  "folderCount": 8
}

💡 Complete Examples

Example 1: Upload Product Images (Bash)

#!/bin/bash

# Step 1: Login
curl -c cookies.txt -X POST http://localhost:3000/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# Step 2: Create products folder
curl -b cookies.txt -X POST http://localhost:3000/api/folder \
  -H "Content-Type: application/json" \
  -d '{"path":"","name":"products"}'

# Step 3: Upload images
curl -b cookies.txt -X POST http://localhost:3000/api/upload \
  -F "basePath=products" \
  -F "files=@./tshirt-red.jpg" \
  -F "files=@./tshirt-blue.jpg" \
  -F "files=@./tshirt-green.jpg"

echo "Files are now accessible at:"
echo "http://localhost:3000/products/tshirt-red.jpg"

Example 2: Using API Tokens (Python)

import requests

BASE_URL = "http://localhost:3000"
API_TOKEN = "yknngagbkwqyga86qxeus5qd"

# Set up headers with API token
headers = {
    "Authorization": f"Bearer {API_TOKEN}"
}

# List files
response = requests.get(f"{BASE_URL}/api/files", headers=headers)
files = response.json()

print(f"Found {len(files['items'])} items:")
for item in files['items']:
    icon = "📁" if item['isDirectory'] else "📄"
    print(f"  {icon} {item['name']}")

# Upload file
with open('example.txt', 'rb') as f:
    files_data = {'files': f}
    data = {'basePath': ''}
    response = requests.post(
        f"{BASE_URL}/api/upload",
        files=files_data,
        data=data,
        headers=headers
    )
    print(f"\n✓ Upload: {response.json()['message']}")

Example 3: Node.js with API Token

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const BASE_URL = 'http://localhost:3000';
const API_TOKEN = 'yknngagbkwqyga86qxeus5qd';

const api = axios.create({
  baseURL: BASE_URL,
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`
  }
});

async function main() {
  try {
    // List files
    const files = await api.get('/api/files');
    console.log(`Found ${files.data.items.length} items`);

    // Create folder
    await api.post('/api/folder', {
      path: '',
      name: 'test-folder',
    });
    console.log('✓ Created folder: test-folder');

    // Upload file
    const formData = new FormData();
    formData.append('basePath', 'test-folder');
    formData.append('files', fs.createReadStream('./test.txt'));

    await api.post('/api/upload', formData, {
      headers: formData.getHeaders(),
    });
    console.log('✓ Uploaded file');
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

main();

⚠️ Error Responses

Status Code	Error Type	Example Response
401	Unauthorized	`{"error": "Authentication required"}`
403	Forbidden	`{"error": "Access denied"}`
404	Not Found	`{"error": "File or folder not found"}`
400	Bad Request	`{"error": "Invalid input"}`
500	Server Error	`{"error": "Internal server error"}`

✨ Best Practices

Security

Use HTTPS in production - Never send credentials over HTTP
Store API tokens securely - Use environment variables, never hardcode
Rotate tokens regularly - Generate new tokens periodically
Revoke unused tokens - Delete tokens that are no longer needed
Use separate tokens - Different tokens for different applications

Performance

Reuse connections - Keep sessions alive for multiple requests
Handle timeouts - Set appropriate timeouts for large file uploads
Batch operations - Upload multiple files in one request when possible
Check file sizes - Validate before uploading (max 100MB per file)

Error Handling

Check status codes - Always verify response status
Implement retries - Retry failed requests with exponential backoff
Log errors - Keep detailed logs for debugging
Validate inputs - Check file paths and names before operations

💡 Need Help?

If you encounter any issues or have questions, please refer to the troubleshooting section in the main documentation or contact support.

Made with ❤️ for easy file management
Powered by Simple File Manager | Licensed under MIT License
← Back to File Manager

📁 Simple File Manager

📖 API Documentation

📑 Table of Contents

🔐 Authentication

Method 1: Session-Based Authentication

Step 1: Login to Get Session Cookie

Step 2: Use Session Cookie for API Calls

Method 2: API Token Authentication (Recommended)

Generate Your API Token

Use API Token

🔑 Authentication Endpoints

📁 File & Folder Operations

👤 User Management Endpoints

👮 Admin Endpoints

🔍 Search & Storage

💡 Complete Examples

Example 1: Upload Product Images (Bash)

Example 2: Using API Tokens (Python)

Example 3: Node.js with API Token

⚠️ Error Responses

✨ Best Practices

Security

Performance

Error Handling