Minecraft Schematic Storage API Documentation

Complete API reference for the Minecraft Schematic sharing and storage system.

Base URL: http://localhost:3001/api

Supported File Types

Minecraft Schematic Formats

Extension	Description
`.schematic`	MCEdit schematic format (legacy)
`.schem`	WorldEdit schematic format (1.13+)
`.litematic`	Litematica schematic format
`.nbt`	NBT structure file (vanilla Minecraft)
`.bo2`	Terrain Control BO2 format
`.bo3`	Terrain Control BO3 format
`.bp`	Blueprint file format

Archive Formats

Extension	Description
`.zip`	ZIP archive
`.tar`	TAR archive
`.gz`	GZIP compressed file
`.tar.gz`	GZIP compressed TAR archive

Upload Limits

Maximum file size: 2 GB per file
Chunk size: 10 MB (for chunked uploads)

Authentication
Files
Chunked Uploads
Admin
Root API (Backend-to-Backend)
Error Handling
Rate Limiting

Authentication

All authenticated endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <access_token>

Register

Create a new user account.

Endpoint: POST /auth/register

Rate Limit: 5 requests per 15 minutes

Request Body:

Field	Type	Required	Description
`email`	string	Yes	Valid email address
`username`	string	Yes	3-30 characters, alphanumeric and underscores
`password`	string	Yes	Min 8 characters, must include uppercase, lowercase, and number
`firstName`	string	No	User's first name
`lastName`	string	No	User's last name

Example Request:

POST /api/auth/register
Content-Type: application/json

{
  "email": "[email protected]",
  "username": "johndoe",
  "password": "SecurePass123",
  "firstName": "John",
  "lastName": "Doe"
}

Success Response (201):

{
  "success": true,
  "message": "Registration successful",
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "username": "johndoe",
      "firstName": "John",
      "lastName": "Doe",
      "role": "user",
      "storageUsed": 0,
      "storageLimit": 5368709120,
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    "tokens": {
      "accessToken": "eyJhbGciOiJIUzI1NiIs...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
      "expiresIn": "24h"
    }
  }
}

Error Responses:

Status	Error	Description
400	Validation Error	Invalid input data
409	Conflict	Email or username already exists

Login

Authenticate and receive access tokens.

Endpoint: POST /auth/login

Rate Limit: 10 requests per 15 minutes

Request Body:

Field	Type	Required	Description
`email`	string	Yes	Registered email address
`password`	string	Yes	Account password

Example Request:

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecurePass123"
}

Success Response (200):

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "username": "johndoe",
      "firstName": "John",
      "lastName": "Doe",
      "role": "user",
      "storageUsed": 1048576,
      "storageLimit": 5368709120,
      "isActive": true,
      "lastLoginAt": "2024-01-15T10:30:00.000Z"
    },
    "tokens": {
      "accessToken": "eyJhbGciOiJIUzI1NiIs...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
      "expiresIn": "24h"
    }
  }
}

Error Responses:

Status	Error	Description
401	Unauthorized	Invalid credentials
403	Forbidden	Account is deactivated

Refresh Token

Get a new access token using a refresh token.

Endpoint: POST /auth/refresh

Request Body:

Field	Type	Required	Description
`refreshToken`	string	Yes	Valid refresh token

Example Request:

POST /api/auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Success Response (200):

{
  "success": true,
  "message": "Token refreshed successfully",
  "data": {
    "tokens": {
      "accessToken": "eyJhbGciOiJIUzI1NiIs...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
      "expiresIn": "24h"
    }
  }
}

Get Profile

Get the authenticated user's profile.

Endpoint: GET /auth/me

Authentication: Required

Example Request:

GET /api/auth/me
Authorization: Bearer <access_token>

Success Response (200):

{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "username": "johndoe",
      "firstName": "John",
      "lastName": "Doe",
      "role": "user",
      "storageUsed": 1048576,
      "storageLimit": 5368709120,
      "storageUsedFormatted": "1 MB",
      "storageLimitFormatted": "5 GB",
      "storageUsedPercentage": 0.02,
      "isActive": true,
      "lastLoginAt": "2024-01-15T10:30:00.000Z",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

Update Profile

Update the authenticated user's profile information.

Endpoint: PUT /auth/profile

Authentication: Required

Request Body:

Field	Type	Required	Description
`username`	string	No	New username (3-30 characters)
`firstName`	string	No	First name
`lastName`	string	No	Last name

Example Request:

PUT /api/auth/profile
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "username": "newusername",
  "firstName": "Jane",
  "lastName": "Smith"
}

Success Response (200):

{
  "success": true,
  "message": "Profile updated successfully",
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "username": "newusername",
      "firstName": "Jane",
      "lastName": "Smith",
      "role": "user"
    }
  }
}

Change Password

Change the authenticated user's password.

Endpoint: PUT /auth/password

Authentication: Required

Request Body:

Field	Type	Required	Description
`currentPassword`	string	Yes	Current password
`newPassword`	string	Yes	New password (min 8 chars, uppercase, lowercase, number)
`confirmNewPassword`	string	Yes	Must match newPassword

Example Request:

PUT /api/auth/password
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "currentPassword": "OldPass123",
  "newPassword": "NewSecure456",
  "confirmNewPassword": "NewSecure456"
}

Success Response (200):

{
  "success": true,
  "message": "Password changed successfully",
  "data": {
    "tokens": {
      "accessToken": "eyJhbGciOiJIUzI1NiIs...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
      "expiresIn": "24h"
    }
  }
}

Files

Upload File

Upload a single Minecraft schematic file.

Endpoint: POST /files/upload

Authentication: Required

Content-Type: multipart/form-data

Allowed Extensions: .schematic, .schem, .litematic, .nbt, .bo2, .bo3, .bp, .zip, .tar, .gz, .tar.gz

Request Body:

Field	Type	Required	Description
`file`	file	Yes	The schematic file to upload (max 2GB)
`description`	string	No	File description
`tags`	string	No	JSON array of tags
`isPublic`	boolean	No	Make file publicly accessible (default: false)

Example Request:

POST /api/files/upload
Authorization: Bearer <access_token>
Content-Type: multipart/form-data

file: <binary>
description: "My document"
tags: ["work", "important"]
isPublic: false

Success Response (201):

{
  "success": true,
  "message": "File uploaded successfully",
  "data": {
    "file": {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "originalName": "document.pdf",
      "mimeType": "application/pdf",
      "size": 1048576,
      "formattedSize": "1 MB",
      "description": "My document",
      "tags": ["work", "important"],
      "isPublic": false,
      "downloadCount": 0,
      "checksum": "a1b2c3d4e5f6...",
      "url": "http://localhost:3001/api/files/660e8400-e29b-41d4-a716-446655440001",
      "downloadUrl": "http://localhost:3001/api/files/660e8400-e29b-41d4-a716-446655440001/download",
      "uploadedAt": "2024-01-15T10:30:00.000Z"
    }
  }
}

Error Responses:

Status	Error	Description
400	Bad Request	No file provided, invalid file, or unsupported file extension
413	Payload Too Large	File exceeds 2GB size limit
507	Insufficient Storage	User storage quota exceeded

List Files

Get a paginated list of the user's files.

Endpoint: GET /files

Authentication: Required

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`sortBy`	string	created_at	Sort field: `created_at`, `original_name`, `size`, `download_count`
`sortOrder`	string	desc	Sort order: `asc` or `desc`
`search`	string	-	Search in filename and description
`mimeType`	string	-	Filter by MIME type (e.g., `image/`, `application/pdf`)
`isPublic`	boolean	-	Filter by visibility

Example Request:

GET /api/files?page=1&limit=10&sortBy=size&sortOrder=desc&search=document
Authorization: Bearer <access_token>

Success Response (200):

{
  "success": true,
  "data": {
    "files": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "originalName": "document.pdf",
        "mimeType": "application/pdf",
        "size": 1048576,
        "formattedSize": "1 MB",
        "description": "My document",
        "tags": ["work"],
        "isPublic": false,
        "downloadCount": 5,
        "url": "http://localhost:3001/api/files/660e8400-e29b-41d4-a716-446655440001",
        "downloadUrl": "http://localhost:3001/api/files/660e8400-e29b-41d4-a716-446655440001/download",
        "uploadedAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "totalFiles": 25,
      "totalPages": 3,
      "hasNextPage": true,
      "hasPrevPage": false
    }
  }
}

Get File

Get details of a specific file.

Endpoint: GET /files/:fileId

Authentication: Required (unless file is public)

Example Request:

GET /api/files/660e8400-e29b-41d4-a716-446655440001
Authorization: Bearer <access_token>

Success Response (200):

{
  "success": true,
  "data": {
    "file": {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "originalName": "document.pdf",
      "mimeType": "application/pdf",
      "size": 1048576,
      "formattedSize": "1 MB",
      "description": "My document",
      "tags": ["work", "important"],
      "isPublic": false,
      "downloadCount": 5,
      "checksum": "a1b2c3d4e5f6...",
      "url": "http://localhost:3001/api/files/660e8400-e29b-41d4-a716-446655440001",
      "downloadUrl": "http://localhost:3001/api/files/660e8400-e29b-41d4-a716-446655440001/download",
      "uploadedAt": "2024-01-15T10:30:00.000Z",
      "lastAccessedAt": "2024-01-16T08:00:00.000Z"
    }
  }
}

Download File

Download a file.

Endpoint: GET /files/:fileId/download

Authentication: Required (unless file is public)

Query Parameters:

Parameter	Type	Description
`token`	string	Alternative to Authorization header

Example Request:

GET /api/files/660e8400-e29b-41d4-a716-446655440001/download
Authorization: Bearer <access_token>

Or with query token:

GET /api/files/660e8400-e29b-41d4-a716-446655440001/download?token=<access_token>

Success Response:

Returns the file binary with appropriate headers:

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

View File

View a file inline (for images, PDFs, etc.).

Endpoint: GET /files/:fileId/view

Authentication: Required (unless file is public)

Query Parameters:

Parameter	Type	Description
`token`	string	Alternative to Authorization header

Example Request:

GET /api/files/660e8400-e29b-41d4-a716-446655440001/view?token=<access_token>

Success Response:

Returns the file binary with inline disposition:

Content-Type: image/jpeg
Content-Disposition: inline; filename="photo.jpg"

Update File

Update file metadata.

Endpoint: PUT /files/:fileId

Authentication: Required

Request Body:

Field	Type	Required	Description
`description`	string	No	New description
`tags`	array	No	New tags array
`isPublic`	boolean	No	Change visibility

Example Request:

PUT /api/files/660e8400-e29b-41d4-a716-446655440001
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "description": "Updated description",
  "tags": ["work", "archived"],
  "isPublic": true
}

Success Response (200):

{
  "success": true,
  "message": "File updated successfully",
  "data": {
    "file": {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "originalName": "document.pdf",
      "description": "Updated description",
      "tags": ["work", "archived"],
      "isPublic": true
    }
  }
}

Delete File

Delete a file.

Endpoint: DELETE /files/:fileId

Authentication: Required

Example Request:

DELETE /api/files/660e8400-e29b-41d4-a716-446655440001
Authorization: Bearer <access_token>

Success Response (200):

{
  "success": true,
  "message": "File deleted successfully",
  "data": {
    "deletedFile": {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "originalName": "document.pdf",
      "size": 1048576
    },
    "storageFreed": 1048576,
    "storageFreedFormatted": "1 MB"
  }
}

Get File Stats

Get storage statistics for the authenticated user.

Endpoint: GET /files/stats/summary

Authentication: Required

Example Request:

GET /api/files/stats/summary
Authorization: Bearer <access_token>

Success Response (200):

{
  "success": true,
  "data": {
    "summary": {
      "totalFiles": 25,
      "storageUsed": 52428800,
      "storageLimit": 5368709120,
      "storageAvailable": 5316280320,
      "storageUsedPercentage": 0.98,
      "totalDownloads": 150
    },
    "byType": {
      "images": { "count": 10, "size": 20971520 },
      "documents": { "count": 8, "size": 15728640 },
      "videos": { "count": 2, "size": 10485760 },
      "audio": { "count": 3, "size": 3145728 },
      "archives": { "count": 1, "size": 1048576 },
      "other": { "count": 1, "size": 1048576 }
    },
    "recentActivity": {
      "uploadsToday": 3,
      "uploadsThisWeek": 12,
      "downloadsToday": 8,
      "downloadsThisWeek": 45
    }
  }
}

Chunked Uploads

For large files, use chunked uploads to upload in parts.

Initialize Chunked Upload

Start a new chunked upload session.

Endpoint: POST /files/chunked/init

Authentication: Required

Request Body:

Field	Type	Required	Description
`fileName`	string	Yes	Original filename
`fileSize`	integer	Yes	Total file size in bytes
`mimeType`	string	Yes	File MIME type
`totalChunks`	integer	Yes	Number of chunks
`description`	string	No	File description
`tags`	array	No	File tags
`isPublic`	boolean	No	File visibility

Example Request:

POST /api/files/chunked/init
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "fileName": "large-video.mp4",
  "fileSize": 104857600,
  "mimeType": "video/mp4",
  "totalChunks": 10,
  "description": "My large video",
  "isPublic": false
}

Success Response (201):

{
  "success": true,
  "message": "Chunked upload initialized",
  "data": {
    "uploadId": "770e8400-e29b-41d4-a716-446655440002",
    "totalChunks": 10,
    "chunkSize": 10485760,
    "expiresAt": "2024-01-16T10:30:00.000Z"
  }
}

Upload Chunk

Upload a single chunk.

Endpoint: POST /files/chunked/:uploadId/chunk

Authentication: Required

Content-Type: multipart/form-data

Request Body:

Field	Type	Required	Description
`chunk`	file	Yes	Chunk binary data
`chunkNumber`	integer	Yes	Chunk index (0-based)

Example Request:

POST /api/files/chunked/770e8400-e29b-41d4-a716-446655440002/chunk
Authorization: Bearer <access_token>
Content-Type: multipart/form-data

chunk: <binary>
chunkNumber: 0

Success Response (200):

{
  "success": true,
  "message": "Chunk 1 of 10 uploaded successfully",
  "data": {
    "uploadId": "770e8400-e29b-41d4-a716-446655440002",
    "chunkNumber": 0,
    "uploadedChunks": 1,
    "totalChunks": 10,
    "progress": 10
  }
}

Complete Chunked Upload

Finalize the chunked upload and assemble the file.

Endpoint: POST /files/chunked/:uploadId/complete

Authentication: Required

Example Request:

POST /api/files/chunked/770e8400-e29b-41d4-a716-446655440002/complete
Authorization: Bearer <access_token>

Success Response (200):

{
  "success": true,
  "message": "File assembled successfully",
  "data": {
    "file": {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "originalName": "large-video.mp4",
      "mimeType": "video/mp4",
      "size": 104857600,
      "formattedSize": "100 MB",
      "url": "http://localhost:3001/api/files/880e8400-e29b-41d4-a716-446655440003",
      "downloadUrl": "http://localhost:3001/api/files/880e8400-e29b-41d4-a716-446655440003/download"
    }
  }
}

Get Upload Status

Check the status of a chunked upload.

Endpoint: GET /files/chunked/:uploadId/status

Authentication: Required

Example Request:

GET /api/files/chunked/770e8400-e29b-41d4-a716-446655440002/status
Authorization: Bearer <access_token>

Success Response (200):

{
  "success": true,
  "data": {
    "uploadId": "770e8400-e29b-41d4-a716-446655440002",
    "status": "uploading",
    "fileName": "large-video.mp4",
    "fileSize": 104857600,
    "totalChunks": 10,
    "uploadedChunks": 5,
    "chunksReceived": [0, 1, 2, 3, 4],
    "missingChunks": [5, 6, 7, 8, 9],
    "progress": 50,
    "expiresAt": "2024-01-16T10:30:00.000Z"
  }
}

Cancel Chunked Upload

Cancel and clean up a chunked upload.

Endpoint: DELETE /files/chunked/:uploadId

Authentication: Required

Example Request:

DELETE /api/files/chunked/770e8400-e29b-41d4-a716-446655440002
Authorization: Bearer <access_token>

Success Response (200):

{
  "success": true,
  "message": "Chunked upload cancelled and cleaned up"
}

Admin

Admin endpoints require admin or moderator role. Some actions are admin-only.

List Users

Get a paginated list of all users.

Endpoint: GET /admin/users

Authentication: Required (Admin/Moderator)

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`sortBy`	string	created_at	Sort field
`sortOrder`	string	desc	Sort order
`search`	string	-	Search in username/email
`role`	string	-	Filter by role: `user`, `moderator`, `admin`
`isActive`	boolean	-	Filter by active status

Example Request:

GET /api/admin/users?page=1&limit=10&role=user&search=john
Authorization: Bearer <admin_token>

Success Response (200):

{
  "success": true,
  "data": {
    "users": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "email": "[email protected]",
        "username": "johndoe",
        "firstName": "John",
        "lastName": "Doe",
        "role": "user",
        "isActive": true,
        "storageUsed": 52428800,
        "storageLimit": 5368709120,
        "fileCount": 25,
        "lastLoginAt": "2024-01-15T10:30:00.000Z",
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "totalUsers": 150,
      "totalPages": 15
    }
  }
}

Get User

Get detailed information about a specific user.

Endpoint: GET /admin/users/:userId

Authentication: Required (Admin/Moderator)

Example Request:

GET /api/admin/users/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <admin_token>

Success Response (200):

{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "username": "johndoe",
      "firstName": "John",
      "lastName": "Doe",
      "role": "user",
      "isActive": true,
      "storageUsed": 52428800,
      "storageLimit": 5368709120,
      "lastLoginAt": "2024-01-15T10:30:00.000Z",
      "createdAt": "2024-01-01T00:00:00.000Z"
    },
    "stats": {
      "totalFiles": 25,
      "totalSize": 52428800,
      "totalDownloads": 150,
      "publicFiles": 5,
      "privateFiles": 20
    },
    "recentFiles": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "originalName": "document.pdf",
        "size": 1048576,
        "createdAt": "2024-01-15T10:30:00.000Z"
      }
    ]
  }
}

Update User

Update a user's information (Admin only for role changes).

Endpoint: PUT /admin/users/:userId

Authentication: Required (Admin)

Request Body:

Field	Type	Required	Description
`role`	string	No	New role: `user`, `moderator`, `admin` (Admin only)
`storageLimit`	integer	No	New storage limit in bytes (Admin only)
`isActive`	boolean	No	Activate/deactivate user (Admin only)
`firstName`	string	No	First name
`lastName`	string	No	Last name

Example Request:

PUT /api/admin/users/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "role": "moderator",
  "storageLimit": 21474836480,
  "isActive": true
}

Success Response (200):

{
  "success": true,
  "message": "User updated successfully",
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "username": "johndoe",
      "role": "moderator",
      "storageLimit": 21474836480,
      "isActive": true
    }
  }
}

Delete User

Delete a user and all their files.

Endpoint: DELETE /admin/users/:userId

Authentication: Required (Admin)

Example Request:

DELETE /api/admin/users/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <admin_token>

Success Response (200):

{
  "success": true,
  "message": "User and all associated files deleted successfully",
  "data": {
    "deletedUser": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "username": "johndoe",
      "email": "[email protected]"
    },
    "deletedFiles": 25,
    "freedStorage": 52428800
  }
}

Reset User Password

Reset a user's password.

Endpoint: POST /admin/users/:userId/reset-password

Authentication: Required (Admin)

Request Body:

Field	Type	Required	Description
`newPassword`	string	Yes	New password (min 8 characters)

Example Request:

POST /api/admin/users/550e8400-e29b-41d4-a716-446655440000/reset-password
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "newPassword": "NewSecure123!"
}

Success Response (200):

{
  "success": true,
  "message": "Password reset successfully"
}

List All Files

Get a paginated list of all files from all users.

Endpoint: GET /admin/files

Authentication: Required (Admin/Moderator)

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page
`sortBy`	string	created_at	Sort field
`sortOrder`	string	desc	Sort order
`search`	string	-	Search in filename
`userId`	string	-	Filter by user ID
`mimeType`	string	-	Filter by MIME type

Example Request:

GET /api/admin/files?page=1&limit=20&userId=550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <admin_token>

Success Response (200):

{
  "success": true,
  "data": {
    "files": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "original_name": "document.pdf",
        "mime_type": "application/pdf",
        "size": 1048576,
        "is_public": false,
        "download_count": 5,
        "created_at": "2024-01-15T10:30:00.000Z",
        "owner": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "username": "johndoe",
          "email": "[email protected]"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "totalFiles": 500,
      "totalPages": 25
    }
  }
}

Delete Any File

Delete any file (Admin/Moderator).

Endpoint: DELETE /admin/files/:fileId

Authentication: Required (Admin/Moderator)

Example Request:

DELETE /api/admin/files/660e8400-e29b-41d4-a716-446655440001
Authorization: Bearer <admin_token>

Success Response (200):

{
  "success": true,
  "message": "File deleted successfully",
  "data": {
    "deletedFile": {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "originalName": "document.pdf",
      "size": 1048576,
      "owner": "johndoe"
    }
  }
}

Get System Stats

Get system-wide statistics.

Endpoint: GET /admin/stats

Authentication: Required (Admin/Moderator)

Example Request:

GET /api/admin/stats
Authorization: Bearer <admin_token>

Success Response (200):

{
  "success": true,
  "data": {
    "users": {
      "total": 150,
      "active": 145,
      "inactive": 5,
      "byRole": {
        "admin": 2,
        "moderator": 5,
        "user": 143
      },
      "newToday": 3,
      "newThisWeek": 15,
      "newThisMonth": 45
    },
    "files": {
      "total": 5000,
      "totalSize": 53687091200,
      "totalSizeFormatted": "50 GB",
      "public": 500,
      "private": 4500,
      "uploadedToday": 50,
      "uploadedThisWeek": 300
    },
    "storage": {
      "totalUsed": 53687091200,
      "totalAllocated": 805306368000,
      "utilizationPercentage": 6.67
    }
  }
}

Get System Settings

Get current system settings.

Endpoint: GET /admin/settings

Authentication: Required (Admin)

Example Request:

GET /api/admin/settings
Authorization: Bearer <admin_token>

Success Response (200):

{
  "success": true,
  "data": {
    "settings": {
      "defaultStorageLimits": {
        "user": 5368709120,
        "moderator": 21474836480,
        "admin": 107374182400
      },
      "maxFileSize": 104857600,
      "allowedMimeTypes": ["*"],
      "chunkSize": 10485760,
      "uploadExpiration": 86400000
    }
  }
}

Root API (Backend-to-Backend)

The Root API is designed for server-to-server communication. Your website's backend uses these endpoints to manage files and users on behalf of your users.

Root Authentication

Root endpoints use API key authentication instead of JWT tokens.

Header Format:

X-API-Key: your_root_api_key_here

Or alternatively:

Authorization: ApiKey your_root_api_key_here

Configuration:

Set the following in your .env file:

# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ROOT_API_KEY=your_generated_api_key

# Optional: Restrict to specific IPs
ROOT_ALLOWED_IPS=127.0.0.1,192.168.1.100

Root Privileges:

Bypasses rate limiting
Bypasses storage limits
Access all users and files
Create/update/delete users
Upload files on behalf of any user

Check Status

Verify root API key and check permissions.

Endpoint: GET /root/status

Example Request:

GET /api/root/status
X-API-Key: your_root_api_key

Success Response (200):

{
  "success": true,
  "data": {
    "authenticated": true,
    "role": "root",
    "username": "root",
    "permissions": {
      "bypassRateLimit": true,
      "bypassStorageLimit": true,
      "accessAllUsers": true,
      "accessAllFiles": true,
      "manageUsers": true,
      "manageFiles": true
    },
    "serverTime": "2024-01-15T10:30:00.000Z"
  }
}

Create User

Create a new user account (for external registration integration).

Endpoint: POST /root/users

Request Body:

{
  "email": "[email protected]",
  "username": "newuser",
  "password": "SecurePassword123",
  "firstName": "John",
  "lastName": "Doe",
  "role": "user"
}

Success Response (201):

{
  "success": true,
  "message": "User created successfully",
  "data": {
    "user": {
      "id": "uuid",
      "email": "[email protected]",
      "username": "newuser",
      "role": "user",
      "storageUsed": 0,
      "storageLimit": 5368709120
    }
  }
}

List All Users

Get paginated list of all users.

Endpoint: GET /root/users

Query Parameters:

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 50)
`search`	string	Search by username or email
`role`	string	Filter by role

Get User Details

Get detailed information about a specific user.

Endpoint: GET /root/users/:userId

Success Response (200):

{
  "success": true,
  "data": {
    "user": {
      "id": "uuid",
      "email": "[email protected]",
      "username": "johndoe",
      "role": "user",
      "storageUsed": 1073741824,
      "storageLimit": 5368709120,
      "isActive": true
    },
    "stats": {
      "fileCount": 15,
      "storageUsedPercent": "20.00"
    }
  }
}

Update User (Root)

Update any user's details.

Endpoint: PATCH /root/users/:userId

Request Body:

{
  "email": "[email protected]",
  "storage_limit": 10737418240,
  "role": "moderator",
  "is_active": true
}

Delete User (Root)

Delete a user and all their files.

Endpoint: DELETE /root/users/:userId

Success Response (200):

{
  "success": true,
  "message": "User and all files deleted successfully",
  "data": {
    "deletedFiles": 15
  }
}

Get User Files

Get all files belonging to a specific user.

Endpoint: GET /root/users/:userId/files

Query Parameters:

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 50)
`sortBy`	string	Sort field (default: created_at)
`sortOrder`	string	asc or desc (default: desc)

Upload File for User

Upload a file on behalf of a specific user.

Endpoint: POST /root/users/:userId/files/upload

Content-Type: multipart/form-data

Request Body:

Field	Type	Required	Description
`file`	file	Yes	The file to upload
`description`	string	No	File description
`tags`	string	No	JSON array of tags
`isPublic`	boolean	No	Make file public

Example (cURL):

curl -X POST http://localhost:3001/api/root/users/{userId}/files/upload \
  -H "X-API-Key: your_root_api_key" \
  -F "file=@/path/to/schematic.schem" \
  -F "description=Castle build" \
  -F "isPublic=true"

Success Response (201):

{
  "success": true,
  "message": "File uploaded successfully",
  "data": {
    "file": {
      "id": "uuid",
      "originalName": "castle.schem",
      "size": 1048576,
      "mimeType": "application/octet-stream"
    },
    "uploadedFor": {
      "id": "user-uuid",
      "username": "johndoe"
    }
  }
}

Get Any File

Get details of any file by ID.

Endpoint: GET /root/files/:fileId

Delete Any File (Root)

Delete any file in the system.

Endpoint: DELETE /root/files/:fileId

System Statistics

Get system-wide statistics.

Endpoint: GET /root/stats

Success Response (200):

{
  "success": true,
  "data": {
    "users": {
      "total": 150,
      "byRole": {
        "user": 145,
        "moderator": 3,
        "admin": 1,
        "root": 1
      }
    },
    "files": {
      "total": 1250,
      "totalStorage": 53687091200,
      "totalStorageFormatted": "50 GB"
    },
    "recentFiles": [...]
  }
}

Root API Code Examples

Node.js Backend Integration:

const ROOT_API_KEY = process.env.ROOT_API_KEY;
const API_URL = 'http://localhost:3001/api';

// Create user when they register on your site
async function createStorageUser(email, username, password) {
  const response = await fetch(`${API_URL}/root/users`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': ROOT_API_KEY
    },
    body: JSON.stringify({ email, username, password })
  });
  return response.json();
}

// Upload file for a user
async function uploadFileForUser(userId, fileBuffer, filename) {
  const formData = new FormData();
  formData.append('file', fileBuffer, filename);
  
  const response = await fetch(`${API_URL}/root/users/${userId}/files/upload`, {
    method: 'POST',
    headers: { 'X-API-Key': ROOT_API_KEY },
    body: formData
  });
  return response.json();
}

// Get user's files
async function getUserFiles(userId) {
  const response = await fetch(`${API_URL}/root/users/${userId}/files`, {
    headers: { 'X-API-Key': ROOT_API_KEY }
  });
  return response.json();
}

Python Backend Integration:

import requests
import os

ROOT_API_KEY = os.environ.get('ROOT_API_KEY')
API_URL = 'http://localhost:3001/api'

headers = {'X-API-Key': ROOT_API_KEY}

# Create user
def create_storage_user(email, username, password):
    response = requests.post(
        f'{API_URL}/root/users',
        headers={**headers, 'Content-Type': 'application/json'},
        json={'email': email, 'username': username, 'password': password}
    )
    return response.json()

# Upload file for user
def upload_file_for_user(user_id, file_path):
    with open(file_path, 'rb') as f:
        response = requests.post(
            f'{API_URL}/root/users/{user_id}/files/upload',
            headers=headers,
            files={'file': f}
        )
    return response.json()

# Get user files
def get_user_files(user_id):
    response = requests.get(
        f'{API_URL}/root/users/{user_id}/files',
        headers=headers
    )
    return response.json()

Error Handling

All errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": {}
  }
}

Common Error Codes

HTTP Status	Code	Description
400	`VALIDATION_ERROR`	Invalid request data
400	`BAD_REQUEST`	Malformed request
401	`UNAUTHORIZED`	Missing or invalid authentication
401	`TOKEN_EXPIRED`	Access token has expired
403	`FORBIDDEN`	Insufficient permissions
403	`ACCOUNT_DISABLED`	User account is deactivated
404	`NOT_FOUND`	Resource not found
409	`CONFLICT`	Resource already exists
413	`PAYLOAD_TOO_LARGE`	File exceeds size limit
429	`TOO_MANY_REQUESTS`	Rate limit exceeded
500	`INTERNAL_ERROR`	Server error
507	`INSUFFICIENT_STORAGE`	Storage quota exceeded

Validation Error Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "errors": [
        {
          "field": "email",
          "message": "Invalid email format"
        },
        {
          "field": "password",
          "message": "Password must be at least 8 characters"
        }
      ]
    }
  }
}

Rate Limiting

API endpoints are rate-limited to prevent abuse.

Default Limits

Endpoint Type	Limit	Window
Authentication	10 requests	15 minutes
Registration	5 requests	15 minutes
General API	100 requests	15 minutes
File Upload	30 requests	15 minutes

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312200

Rate Limit Exceeded Response (429)

{
  "success": false,
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Too many requests, please try again later",
    "details": {
      "retryAfter": 900
    }
  }
}

User Roles

Role	Permissions
`user`	Manage own files only
`moderator`	View all users/files, delete any file
`admin`	Full access: manage users, change roles, system settings

Default Storage Limits

Role	Default Limit
`user`	5 GB
`moderator`	20 GB
`admin`	100 GB

Code Examples

JavaScript/Node.js

const API_URL = 'http://localhost:3001/api';

// Login
async function login(email, password) {
  const response = await fetch(`${API_URL}/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password })
  });
  return response.json();
}

// Upload file
async function uploadFile(token, file) {
  const formData = new FormData();
  formData.append('file', file);
  
  const response = await fetch(`${API_URL}/files/upload`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` },
    body: formData
  });
  return response.json();
}

// List files
async function listFiles(token, page = 1) {
  const response = await fetch(`${API_URL}/files?page=${page}`, {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return response.json();
}

cURL

# Register
curl -X POST http://localhost:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","username":"johndoe","password":"SecurePass123"}'

# Login
curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"SecurePass123"}'

# Upload file
curl -X POST http://localhost:3001/api/files/upload \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/file.pdf" \
  -F "description=My document"

# List files
curl http://localhost:3001/api/files \
  -H "Authorization: Bearer <token>"

# Download file
curl -O http://localhost:3001/api/files/<fileId>/download?token=<token>

Python

import requests

API_URL = 'http://localhost:3001/api'

# Login
def login(email, password):
    response = requests.post(f'{API_URL}/auth/login', json={
        'email': email,
        'password': password
    })
    return response.json()

# Upload file
def upload_file(token, file_path):
    with open(file_path, 'rb') as f:
        response = requests.post(
            f'{API_URL}/files/upload',
            headers={'Authorization': f'Bearer {token}'},
            files={'file': f}
        )
    return response.json()

# List files
def list_files(token, page=1):
    response = requests.get(
        f'{API_URL}/files',
        headers={'Authorization': f'Bearer {token}'},
        params={'page': page}
    )
    return response.json()

WebSocket Events (Future)

Coming soon: Real-time notifications for file uploads and system events.

Changelog

v1.1.0

Added Root API for backend-to-backend communication
Root account with API key authentication
Upload files on behalf of users
Create/manage users via Root API
IP whitelist support for root access
Rate limit bypass for root requests
Storage limit bypass for root operations

v1.0.0

Initial release
User authentication (register, login, refresh token)
File management (upload, download, delete, update)
Chunked uploads for large files (up to 2GB)
Admin panel with user management
Role-based access control (user, moderator, admin, root)
Rate limiting and security features
Minecraft schematic file support (.schematic, .schem, .litematic, .nbt, .bo2, .bo3, .bp)

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

Minecraft Schematic Storage API Documentation

Supported File Types

Minecraft Schematic Formats

Archive Formats

Upload Limits

Table of Contents

Authentication

Register

Login

Refresh Token

Get Profile

Update Profile

Change Password

Files

Upload File

List Files

Get File

Download File

View File

Update File

Delete File

Get File Stats

Chunked Uploads

Initialize Chunked Upload

Upload Chunk

Complete Chunked Upload

Get Upload Status

Cancel Chunked Upload

Admin

List Users

Get User

Update User

Delete User

Reset User Password

List All Files

Delete Any File

Get System Stats

Get System Settings

Root API (Backend-to-Backend)

Root Authentication

Check Status

Create User

List All Users

Get User Details

Update User (Root)

Delete User (Root)

Get User Files

Upload File for User

Get Any File

Delete Any File (Root)

System Statistics

Root API Code Examples

Error Handling

Common Error Codes

Validation Error Example

Rate Limiting

Default Limits

Rate Limit Headers

Rate Limit Exceeded Response (429)

User Roles

Default Storage Limits

Code Examples

JavaScript/Node.js

cURL

Python

WebSocket Events (Future)

Changelog

v1.1.0

v1.0.0