filester.me BETA v0.10

Uploads & API are back online!.

API Documentation

Integrate with Filester using our REST API. Upload files, manage folders, and access your content programmatically.

Base URL: https://u1.filester.me

Contents

Authentication API key & headers
Upload POST Upload File GET Upload Status
Files GET List Files GET Get File POST Move File POST Move Files (bulk) POST Delete File
Folders GET List Folders POST Create / Subfolder GET Folder Files POST Move Folder POST Move Folders (bulk) POST Delete Folder
Account GET Account Info
Health GET Health Check
Errors Codes & meanings Rate Limits Request quotas

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header.

Get your API key from your Account Settings page. Guest uploads (no authentication) are also supported for the upload endpoint.

Authorization: Bearer YOUR_API_KEY
Rate limit: 1,000 requests per hour per API key

Upload

POST /api/v1/upload

Upload a file. Supports guest uploads (no auth required) or authenticated uploads with an API key.

Headers

Content-Type multipart/form-data required
Authorization Bearer YOUR_API_KEY optional
X-Folder-ID Folder identifier to upload into optional

Form Fields

file The file to upload required

Response

{ "success": true, "message": "File uploaded successfully", "slug": "aBcDeFg", "url": "https://filester.me/d/aBcDeFg", "file_id": 12345, "thumbnail_url": "/t/UUID" }

Example (cURL)

curl -X POST https://u1.filester.me/api/v1/upload \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@/path/to/file.mp4"

Example (Guest Upload)

curl -X POST https://u1.filester.me/api/v1/upload \ -F "file=@/path/to/file.jpg"

Example (Upload to Folder)

curl -X POST https://u1.filester.me/api/v1/upload \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "X-Folder-ID: a1b2c3d4e5f6g7h8" \ -F "file=@/path/to/file.zip"
GET /api/v1/upload/status?slug={slug}

Check the status of an uploaded file.

Response

{ "slug": "aBcDeFg", "status": "completed", "upload_date": "2026-03-15T10:30:00Z", "thumbnail_url": "/t/UUID" }

Files

GET /api/v1/files

List your uploaded files with pagination and search.

Query Parameters

page Page number (default: 1) optional
per_page Items per page, 1-100 (default: 20) optional
folder Folder identifier, or "root" for root files only optional
search Search by filename optional

Response

{ "success": true, "data": [ { "id": 12345, "uuid": "550e8400-e29b-41d4-a716-446655440000", "name": "video.mp4", "size": 104857600, "type": "video/mp4", "url": "https://filester.me/d/aBcDeFg", "folder_id": "a1b2c3d4", "created_at": "2026-03-15T10:30:00Z", "downloads": 42 } ], "pagination": { "page": 1, "per_page": 20, "total": 150, "pages": 8 } }

Example

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://u1.filester.me/api/v1/files?page=1&per_page=10"
GET /api/v1/file/{id}

Get details of a specific file. The id can be a slug, UUID, or numeric ID.

Response

{ "success": true, "data": { "id": 12345, "uuid": "550e8400-e29b-41d4-a716-446655440000", "slug": "aBcDeFg", "name": "photo.jpg", "size": 2048000, "type": "image/jpeg", "url": "https://filester.me/d/aBcDeFg", "has_thumbnail": true, "created_at": "2026-03-15T10:30:00Z", "downloads": 5, "views": 23 } }
POST /api/v1/file/move

Move a file into a different folder (or back to the root).

Request Body

file File identifier — slug, UUID, or numeric ID required
folder Destination folder identifier. Use "root" (or omit) to move it to the top level. optional

Response

{ "success": true, "message": "File moved successfully", "data": { "file": "aBcDeFg", "folder": "a1b2c3d4e5f6g7h8" } }

Example

curl -X POST https://u1.filester.me/api/v1/file/move \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"file": "aBcDeFg", "folder": "a1b2c3d4e5f6g7h8"}'
POST /api/v1/files/move

Move many files into one destination folder (or root) in a single request. One failure does not abort the rest — each file's result is returned.

Request Body

files Array of file identifiers (slug, UUID, or numeric ID). Max 200. required
folder Destination folder identifier. Use "root" (or omit) to move them to the top level. optional

Response

{ "success": true, "message": "Moved 2 of 2 files", "data": { "folder": "a1b2c3d4e5f6g7h8", "moved": 2, "failed": 0, "results": [ { "file": "aBcDeFg", "success": true }, { "file": "xYzAbCd", "success": true } ] } }

Example

curl -X POST https://u1.filester.me/api/v1/files/move \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"files": ["aBcDeFg", "xYzAbCd"], "folder": "a1b2c3d4e5f6g7h8"}'
POST /file/delete

Delete one or more files.

Request Body

{ "identifiers": ["aBcDeFg", "xYzAbCd"] }

Response

{ "success": true, "message": "Files deleted successfully", "total_processed": 2, "successful_deletes": 2, "failed_deletes": 0, "files_deleted": 2 }

Folders

GET /api/v1/folders

List all your folders.

Response

{ "success": true, "data": [ { "id": "a1b2c3d4e5f6g7h8", "name": "My Photos", "public": true, "file_count": 24, "created_at": "2026-03-10T08:00:00Z" } ] }
POST /api/v1/folder

Create a new folder. To create a subfolder, pass the parent folder's identifier in parent; the response returns the new folder's identifier, which you can reuse as a parent to nest further.

Request Body

name Folder name (max 100 characters) required
parent Parent folder identifier to create a subfolder inside. Omit (or use "root") to create at the top level. Alias: parent_id. optional
public 1 for public, 0 for private (default: 1) optional
password Password to protect the folder optional

Response

{ "success": true, "message": "Folder created successfully", "data": { "identifier": "9f8e7d6c5b4a3210", "name": "Episodes", "parent": "a1b2c3d4e5f6g7h8", "hasPassword": false } }

Example (top-level folder)

curl -X POST https://u1.filester.me/api/v1/folder \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "My Photos", "public": 1}'

Example (subfolder)

curl -X POST https://u1.filester.me/api/v1/folder \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Episodes", "parent": "a1b2c3d4e5f6g7h8"}'
GET /api/v1/folder/{identifier}/files

List all files in a specific folder.

Response

{ "success": true, "data": [ { "id": 12345, "name": "photo1.jpg", "size": 2048000, "type": "image/jpeg", "url": "https://filester.me/d/aBcDeFg", "created_at": "2026-03-15T10:30:00Z" } ] }
POST /api/v1/folder/move

Move a folder (and everything inside it) under a different parent, or back to the root.

Request Body

folder Identifier of the folder to move required
parent Destination parent folder identifier. Use "root" (or omit) to move it to the top level. optional

Rejected if the destination is the folder itself or one of its subfolders, if a folder with the same name already exists at the destination, or if the move would exceed the maximum nesting depth.

Response

{ "success": true, "message": "Folder moved successfully", "data": { "folder": "9f8e7d6c5b4a3210", "parent": "root", "folders_updated": 3 } }

Example

curl -X POST https://u1.filester.me/api/v1/folder/move \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"folder": "9f8e7d6c5b4a3210", "parent": "a1b2c3d4e5f6g7h8"}'
POST /api/v1/folders/move

Move many folders (each with its whole subtree) under one destination parent, or back to the root, in a single request. Each folder is validated independently; one failure does not abort the rest.

Request Body

folders Array of folder identifiers to move. Max 200. required
parent Destination parent folder identifier. Use "root" (or omit) to move them to the top level. optional

Per folder, the move is rejected (and reported in its result) if the destination is that folder itself or one of its subfolders, if a folder with the same name already exists at the destination, or if it would exceed the maximum nesting depth.

Response

{ "success": false, "message": "Moved 1 of 2 folders", "data": { "parent": "root", "moved": 1, "failed": 1, "results": [ { "folder": "9f8e7d6c5b4a3210", "success": true, "folders_updated": 2 }, { "folder": "bad0000000000000", "success": false, "error": "FOLDER_NOT_FOUND" } ] } }

Example

curl -X POST https://u1.filester.me/api/v1/folders/move \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"folders": ["9f8e7d6c5b4a3210", "1122334455667788"], "parent": "root"}'
POST /folder/delete

Delete one or more folders and all files within them.

Request Body

{ "identifiers": ["a1b2c3d4e5f6g7h8"] }

Response

{ "success": true, "message": "Folders deleted", "total_processed": 1, "successful_deletes": 1, "failed_deletes": 0, "files_deleted": 24 }

Account

GET /api/v1/account

Get your account information and usage statistics.

Response

{ "success": true, "data": { "id": 42, "username": "johndoe", "storage_used": 5368709120, "storage_limit": 10737418240, "files_count": 150, "folders_count": 12, "api_requests_today": 47 } }

Example

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://u1.filester.me/api/v1/account"

Health

GET /health

Check API health status. No authentication required.

Response

{ "status": "healthy", "timestamp": 1711526400, "service": "storage-api" }

Errors

All errors follow a consistent format. HTTP status codes are used appropriately.

{ "success": false, "message": "Description of what went wrong" }

Status Codes

Code Meaning
200 Success
201 Created (folder creation)
400 Bad request - missing or invalid parameters
401 Unauthorized - invalid or missing API key
403 Forbidden - insufficient permissions
404 Not found - resource doesn't exist
429 Rate limited - too many requests
500 Internal server error

Limits

Resource Limit
File size (API upload) 10 GB
File size (Web upload) 10 GB
Storage per account 10 GB
API requests 1,000 / hour
Folder name length 100 characters
Folder nesting depth Unlimited nested folders
File inactivity Deleted after 45 days without views or downloads
Need help? Reach out via our contact page.