M
MegaVault
DashboardGitHub
Documentation

API Reference

Complete reference for MegaVault's REST API endpoints, authentication, and integration guides.

Table of Contents

API Overview

MegaVault provides a comprehensive REST API for file management, user authentication, and system integration. The API is designed for both web and mobile applications.

REST Architecture

Standard HTTP methods

  • ✅ RESTful design principles
  • ✅ Standard HTTP status codes
  • ✅ JSON request/response format
  • ✅ Consistent URL patterns

Authentication

Secure access control

  • ✅ JWT token-based auth
  • ✅ Session management
  • ✅ API key support
  • ✅ Role-based permissions

Developer Experience

Easy integration

  • ✅ Comprehensive documentation
  • ✅ Code examples
  • ✅ SDKs and libraries
  • ✅ Interactive testing
💡

API Base URL

All API endpoints are relative to the base URL:https://your-domain.com/api

Authentication

MegaVault uses JWT tokens for API authentication. Include the token in the Authorization header.

Authentication Header
Authorization: Bearer YOUR_JWT_TOKEN

Getting an Access Token

Login Request
POST /api/auth/signin
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}
Login Response
{
  "success": true,
  "user": {
    "id": "user_123",
    "email": "user@example.com",
    "name": "John Doe"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": "24h"
}

Endpoint Categories

The MegaVault API is organized into logical categories for different functionalities.

Authentication Endpoints

  • POST /api/auth/signin - User login
  • POST /api/auth/signup - User registration
  • POST /api/auth/signout - User logout
  • GET /api/auth/session - Get session
View Documentation →

File Management

  • GET /api/files - List files
  • POST /api/files/upload - Upload file
  • GET /api/files/:id - Get file info
  • DELETE /api/files/:id - Delete file
View Documentation →

User Management

  • GET /api/users/profile - Get profile
  • PUT /api/users/profile - Update profile
  • GET /api/users/usage - Get usage stats
  • PUT /api/users/settings - Update settings
View Documentation →

Mobile Endpoints

  • POST /api/mobile/auth - Mobile auth
  • POST /api/mobile/upload - Mobile upload
  • GET /api/mobile/sync - Data sync
  • POST /api/mobile/push - Push notifications
View Documentation →

Request Format

All API requests should follow these formatting guidelines for consistency.

Headers

Required Headers
Content-Type: application/json
Authorization: Bearer YOUR_JWT_TOKEN
User-Agent: YourApp/1.0

Query Parameters

Pagination Example
GET /api/files?page=1&limit=20&sort=createdAt&order=desc

Request Body

JSON Request Body
{
  "name": "document.pdf",
  "folder": "/documents",
  "tags": ["important", "work"],
  "metadata": {
    "description": "Project specification document"
  }
}

Response Format

All API responses follow a consistent format with proper HTTP status codes.

Success Response

Success Response
{
  "success": true,
  "data": {
    "id": "file_123",
    "name": "document.pdf",
    "size": 1024,
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 50
  }
}

Error Response

Error Response
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid file format",
    "details": {
      "field": "file",
      "allowedTypes": ["pdf", "jpg", "png"]
    }
  }
}

HTTP Status Codes

Status CodeMeaningUsage
200OKRequest successful
201CreatedResource created successfully
400Bad RequestInvalid request format or parameters
401UnauthorizedAuthentication required or invalid
403ForbiddenInsufficient permissions
404Not FoundResource does not exist
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side error occurred

Rate Limiting

API endpoints are rate-limited to ensure fair usage and system stability.

Endpoint CategoryRate LimitWindow
Authentication5 requests1 minute
File Operations100 requests1 hour
File Upload10 uploads1 hour
General API1000 requests1 hour

Rate Limit Headers

Rate Limit Response Headers
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Error Handling

Proper error handling is essential for robust API integration.

Common Error Codes

Client Errors (4xx)

  • VALIDATION_ERROR: Invalid input data
  • AUTHENTICATION_FAILED: Invalid credentials
  • INSUFFICIENT_PERMISSIONS: Access denied
  • RESOURCE_NOT_FOUND: Requested resource missing

Server Errors (5xx)

  • INTERNAL_ERROR: Unexpected server error
  • DATABASE_ERROR: Database connection issue
  • STORAGE_ERROR: File storage problem
  • SERVICE_UNAVAILABLE: Temporary service issue

Error Handling Best Practices

  • Check Status Codes: Always check HTTP status codes
  • Parse Error Messages: Extract meaningful error details
  • Implement Retry Logic: Retry on 5xx errors with backoff
  • Handle Rate Limits: Respect rate limit headers
  • Log Errors: Log errors for debugging and monitoring
💡

SDK Availability

Official SDKs are available for popular languages to simplify API integration and handle common scenarios like authentication and error handling.

API Endpoints

Authentication →

User authentication and session management

File Management →

Upload, download, and manage files

User Management →

User profiles and account settings

Mobile Endpoints →

Mobile-specific API endpoints

Error Handling →

Error codes and troubleshooting

Rate Limiting →

API rate limiting and best practices