File Server API Documentation

🔧 Current Configuration

Base URL: https://kittencloud.uk

Proxy Path: None

Trust Proxy: Enabled

🔐

Secure

API key authentication, rate limiting, and secure file handling

⚡

Proxy Ready

Optimized for reverse proxy deployment with proper header handling

📊

Analytics

Comprehensive statistics and view tracking

🎯

Discord Ready

Perfect embed support for Discord and social media

POST /api/upload

Description: Upload an image or video file

Authentication: Required (X-API-Key header or api_key query parameter)

Content-Type: multipart/form-data

Parameters:

file - The file to upload (image or video, max 100 MB)

Response:

{
  "success": true,
  "id": "1234567890abcdef",
  "view_url": "/api/view/1234567890abcdef",
  "embed_url": "/api/embed/1234567890abcdef",
  "message": "File uploaded successfully"
}

GET /api/view/{id}

Description: View or download a file directly

Parameters:

download=true (query) - Force download instead of display

Response: Raw file data with appropriate Content-Type

GET /api/embed/{id}

Description: View file with Discord embed support and web interface

Features:

Discord/social media embeds with Open Graph meta tags
Responsive web interface
Download and direct view buttons
View statistics and file information

GET /api/stats

Description: Get comprehensive server statistics

GET /health

Description: Health check endpoint for proxy monitoring

🔒 Security Features

Proxy-Aware Rate Limiting: Uses real client IP from proxy headers
Trust Proxy: Properly handles X-Forwarded-* headers
API Key Authentication: Secure upload endpoint protection
File Type Validation: Only images and videos allowed
Secure Filenames: SHA-256 hash-based naming

📝 Usage Examples

Upload File (cURL)

curl -X POST \
  -H "X-API-Key: your-api-key-here" \
  -F "file=@image.jpg" \
  https://kittencloud.uk/api/upload

Upload File (JavaScript)

const formData = new FormData();
formData.append('file', fileInput.files[0]);

fetch('https://kittencloud.uk/api/upload', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key-here'
  },
  body: formData
}).then(response => response.json())
  .then(data => console.log(data));

⚙️ Environment Variables

PORT: Server port (default: 8080)
API_KEY: Authentication key
BASE_URL: Full base URL if using fixed proxy (e.g., https://yourdomain.com/api)
PROXY_PATH: Path prefix if proxied (e.g., /api)
UPLOAD_DIR: Upload directory (default: ./uploads)
MAX_FILE_SIZE: Max file size in bytes (default: 104857600)
RATE_LIMIT: Requests per minute (default: 100)

🔧 Proxy Configuration Examples

Nginx

location /api/ {
    proxy_pass http://localhost:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    
    # For file uploads
    client_max_body_size 100M;
}

Apache

ProxyPass /api/ http://localhost:8080/
ProxyPassReverse /api/ http://localhost:8080/
ProxyPreserveHost On
ProxyAddHeaders On

🚀 File Server API