API Documentation

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header. Get your 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 responses carry X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset so you can pace yourself; go over and you get a 429 with a Retry-After header (seconds to wait before retrying). Treat the key like a password — regenerating it invalidates the old one immediately.

Errors

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

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

Status codes

`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	wait `Retry-After` seconds
`500`	Internal server error

Limits

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

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 -X POST https://u1.filester.me/api/v1/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/file.mp4"

Guest upload

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

Upload into a 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. Each folder includes parent (and its alias parent_id) — the parent folder's identifier, or null for a top-level folder — so you can reconstruct the folder tree. file_count and folder_count (immediate subfolders) let you tell a folder with only subfolders apart from an empty one.

Response

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4e5f6g7h8",
      "name": "My Photos",
      "public": true,
      "file_count": 24,
      "folder_count": 2,
      "created_at": "2026-03-10T08:00:00Z",
      "parent": null,
      "parent_id": null
    },
    {
      "id": "9f8e7d6c5b4a3210",
      "name": "Episodes",
      "public": false,
      "file_count": 12,
      "folder_count": 0,
      "created_at": "2026-03-11T09:30:00Z",
      "parent": "a1b2c3d4e5f6g7h8",
      "parent_id": "a1b2c3d4e5f6g7h8"
    }
  ]
}

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`) for 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/thumbnail#

Upload an image to use as a folder's thumbnail. Send as multipart/form-data. Replaces any existing thumbnail. Allowed types: JPG, PNG, GIF, WebP; max 5 MB.

Form fields

`folder`	Folder identifier. Alias: `identifier`	required
`thumbnail`	The image file. Alias: `file`	required

Response

{
  "success": true,
  "message": "Folder thumbnail updated",
  "data": {
    "identifier": "a1b2c3d4e5f6g7h8",
    "thumbnail_url": "folder_thumbs/9f3c…d2.jpg"
  }
}

Example

curl -X POST https://u1.filester.me/api/v1/folder/thumbnail \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "folder=a1b2c3d4e5f6g7h8" \
  -F "thumbnail=@cover.jpg"

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"

GET/health#

Check API health status. No authentication required.

Response

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