FileMoon — FileMoon API Documentation

FileMoon REST API

Introduction

The FileMoon API is a JSON-based HTTP API for automating uploads, managing files owned by the authenticated account and importing authorized direct video URLs.

Base URL	`https://filemoon.org/api/v1`
Current version	`v1`
Content-Type	`application/json` / `multipart/form-data`

Security: Use HTTPS for every request. Never expose a private token in public browser code, screenshots, repositories or shared logs.

Getting started

Authentication

Send a FileMoon personal access token in the Authorization header using the Bearer scheme.

HTTP Headers

Authorization: Bearer YOUR_FILEMOON_TOKEN
Accept: application/json

Create a token from User Panel → API & Remote Upload. The plain token is shown once, so store it securely.

Token permissions

files:readRead account, files, file status and remote-upload status.

files:writeUpload, update and delete owned files.

remote:writeCreate, cancel and retry remote-upload jobs.

HTTP 429

Rate limits

Limits are applied per token and IP address. The active limit is returned in response headers and cannot exceed 60 requests per minute.

Response Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
Retry-After: 12
X-Request-ID: 2c7c4d7a-0e4d-4d92-bb53-e32f1e705dda

After HTTP 429, wait for the Retry-After value before sending another request.

Getting started

Account information

Return the authenticated account, file total, storage usage and remote-job counters.

GET /account

Parameters

No request parameters.

Example request

cURL

curl -sS "https://filemoon.org/api/v1/account" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example response

200 JSON

{
  "success": true,
  "data": {
    "id": "rk9zKY45m0lY",
    "username": "example_user",
    "email": "[email protected]",
    "status": true,
    "files": 20,
    "storage_bytes": 1846721934,
    "remote_jobs": {
      "pending": 0,
      "running": 0,
      "completed": 1,
      "failed": 0
    }
  }
}

Files

List files

Return a paginated list of owned files. Use search to filter by name or stored filename.

GET /files

Parameters

Field	Type	Required	Description
`search`	string	Optional	Filter by name or stored filename. Maximum 255 characters.
`page`	integer	Optional	Pagination page. Minimum 1.
`per_page`	integer	Optional	Results per page. Default 25, maximum 100.

Example request

cURL

curl -sS "https://filemoon.org/api/v1/files?search=sample&per_page=25&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example response

200 JSON

{
  "success": true,
  "data": [
    {
      "id": "0JgG7vRZzoYW",
      "name": "sample-video",
      "filename": "sample-video.mp4",
      "mime": "video/mp4",
      "extension": "mp4",
      "size_bytes": 1520849,
      "visibility": "public",
      "password_protected": false,
      "allow_online_watch": true,
      "downloads": 0,
      "stream_views": 0,
      "urls": {
        "page": "https://filemoon.org/0JgG7vRZzoYW/file",
        "watch": "https://filemoon.org/0JgG7vRZzoYW/watch",
        "embed": "https://filemoon.org/0JgG7vRZzoYW/embed"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 1
  }
}

Files

Get file information

Return one owned file using its public FileMoon file ID.

GET /files/{id}

Parameters

Field	Type	Required	Description
`id`	string (path)	Yes	Public FileMoon file ID owned by the authenticated account.

Example request

cURL

curl -sS "https://filemoon.org/api/v1/files/0JgG7vRZzoYW" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Files

Get file and HLS status

Return file information together with its HLS conversion status when a conversion job exists.

GET /files/{id}/status

Parameters

Field	Type	Required	Description
`id`	string (path)	Yes	Public FileMoon file ID owned by the authenticated account.

Example request

cURL

curl -sS "https://filemoon.org/api/v1/files/0JgG7vRZzoYW/status" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example response

200 JSON

{
  "success": true,
  "data": {
    "file": {
      "id": "0JgG7vRZzoYW",
      "name": "sample-video",
      "allow_online_watch": true
    },
    "conversion": {
      "status": "completed",
      "stage": "adaptive",
      "attempts": 1,
      "duration_seconds": 42,
      "error": null,
      "updated_at": "2026-07-18 19:20:00"
    }
  }
}

Files

Upload a local file

Upload a file with multipart/form-data. The file field is required; visibility may be sent as 1 or 0.

POST /files/upload

Parameters

Field	Type	Required	Description
`file`	binary	Yes	Local file attached as multipart/form-data.
`visibility`	boolean	Optional	Use 1 for public or 0 for private.

Example request

cURL

curl -sS -X POST "https://filemoon.org/api/v1/files/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -F "file=@/path/to/video.mp4" \
  -F "visibility=1"

Files

Update a file

Change supported metadata on an owned file. Send only the fields that need to change.

PATCH /files/{id}

Parameters

Field	Type	Required	Description
`id`	string (path)	Yes	Public FileMoon file ID.
`name`	string	Optional	New file name. Maximum 255 characters.
`description`	string\|null	Optional	File description. Maximum 1000 characters.
`visibility`	boolean	Optional	Public or private visibility.
`allow_online_watch`	boolean	Optional	Enable or disable online video watch.
`password`	string\|null	Optional	Set, change or remove the file password.

Example request

cURL

curl -sS -X PATCH "https://filemoon.org/api/v1/files/0JgG7vRZzoYW" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-video-name",
    "description": "Updated through FileMoon API",
    "visibility": true,
    "allow_online_watch": true
  }'

Files

Delete a file

Permanently delete an owned file and related stored data. This action cannot be undone.

DELETE /files/{id}

Parameters

Field	Type	Required	Description
`id`	string (path)	Yes	Public FileMoon file ID.

Example request

cURL

curl -sS -X DELETE "https://filemoon.org/api/v1/files/0JgG7vRZzoYW" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Remote upload

Create remote-upload jobs

Queue one or more direct media URLs. HTTP 202 means the jobs were accepted for background processing.

Remote upload accepts public direct HTTP or HTTPS media URLs. Private networks, localhost, cloud metadata, unsafe redirects, scripts and non-video responses are blocked.

POST /remote-uploads

Parameters

Field	Type	Required	Description
`urls`	array<string>	Yes	One or more public direct HTTP/HTTPS media URLs.
`name`	string\|null	Optional	Custom file name. Maximum 240 characters.
`description`	string\|null	Optional	Description. Maximum 1000 characters.
`folder_id`	integer\|null	Optional	Folder ID owned by the authenticated user.
`visibility`	boolean	Optional	Public or private file.
`allow_online_watch`	boolean	Optional	Allow online video playback.
`password`	string\|null	Optional	Optional file password.
`blocked_countries`	array<string>	Optional	Two-letter country codes. Maximum 50 entries.

Example request

cURL

curl -sS -X POST "https://filemoon.org/api/v1/remote-uploads" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://cdn.example.com/video.mp4"],
    "name": "remote-video",
    "description": "Imported through FileMoon API",
    "visibility": true,
    "allow_online_watch": true,
    "blocked_countries": ["US", "GB"]
  }'

Example response

202 JSON

{
  "success": true,
  "message": "Remote upload job(s) queued.",
  "data": [
    {
      "id": "d96f9d69-1d44-42eb-89e3-5a62b052e77d",
      "host": "cdn.example.com",
      "name": "remote-video",
      "status": "pending",
      "stage": "queued",
      "attempts": 0,
      "bytes_downloaded": 0,
      "bytes_total": null,
      "progress_percent": null,
      "error": null,
      "file_id": null
    }
  ]
}

Job status values

pendingrunningcompletedfailedcancelled

Remote upload

List remote-upload jobs

Return paginated remote jobs belonging to the authenticated account.

GET /remote-uploads

Parameters

Field	Type	Required	Description
`page`	integer	Optional	Pagination page.
`per_page`	integer	Optional	Default 25, maximum 100.

Example request

cURL

curl -sS "https://filemoon.org/api/v1/remote-uploads?per_page=25&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Remote upload

Get remote-upload status

Return progress, current stage, errors and the created FileMoon file ID after completion.

GET /remote-uploads/{id}

Parameters

Field	Type	Required	Description
`id`	UUID (path)	Yes	Remote-upload job ID.

Example request

cURL

curl -sS "https://filemoon.org/api/v1/remote-uploads/d96f9d69-1d44-42eb-89e3-5a62b052e77d" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example response

200 JSON

{
  "success": true,
  "data": {
    "id": "d96f9d69-1d44-42eb-89e3-5a62b052e77d",
    "host": "cdn.example.com",
    "name": "remote-video",
    "status": "completed",
    "stage": "completed",
    "attempts": 1,
    "bytes_downloaded": 1520849,
    "bytes_total": 1520849,
    "progress_percent": 100,
    "error": null,
    "file_id": "0JgG7vRZzoYW"
  }
}

Remote upload

Cancel a remote-upload job

Cancel a pending job or request cancellation of a running job.

POST /remote-uploads/{id}/cancel

Parameters

Field	Type	Required	Description
`id`	UUID (path)	Yes	Remote-upload job ID.

Example request

cURL

curl -sS -X POST "https://filemoon.org/api/v1/remote-uploads/JOB_ID/cancel" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Remote upload

Retry a failed job

Reset a failed or cancelled job and place it back in the secure queue.

POST /remote-uploads/{id}/retry

Parameters

Field	Type	Required	Description
`id`	UUID (path)	Yes	Remote-upload job ID.

Example request

cURL

curl -sS -X POST "https://filemoon.org/api/v1/remote-uploads/JOB_ID/retry" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

HTTP

Errors and status codes

Errors use a consistent JSON structure. Save request_id when contacting support.

401

UNAUTHENTICATED

Missing or invalid Bearer token.

403

TOKEN_DISABLED / TOKEN_EXPIRED

Token disabled, expired, IP blocked or missing permission.

404

NOT_FOUND

Owned file or remote job could not be found.

409

REMOTE_JOB_NOT_CANCELLABLE

The job can no longer be cancelled.

422

VALIDATION_ERROR

Request fields or uploaded file are invalid.

429

RATE_LIMITED

Too many requests. Use Retry-After.

503

API_DISABLED

The administrator temporarily disabled the API.

Example response

Error JSON

{
  "success": false,
  "error": {
    "code": "TOKEN_ABILITY_DENIED",
    "message": "The token does not have the required permission."
  },
  "request_id": "2c7c4d7a-0e4d-4d92-bb53-e32f1e705dda"
}

Reference

Security requirements

Apply these rules when integrating the FileMoon API.

Keep tokens on a trusted server and revoke exposed tokens immediately.

Use the minimum required permissions for each integration.

Restrict a token to trusted IP addresses or CIDR ranges when possible.

Only upload content you own or are authorized to distribute.

cURL · PHP · JavaScript

Client examples

Minimal cURL, PHP and server-side JavaScript examples using Bearer-token authentication.

cURL

curl -sS "https://filemoon.org/api/v1/account" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

PHP 8+

<?php
$token = getenv('FILEMOON_API_TOKEN');

$ch = curl_init('https://filemoon.org/api/v1/account');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Accept: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$response = curl_exec($ch);
if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
if ($status >= 400) {
    throw new RuntimeException($data['error']['message'] ?? 'API request failed');
}
print_r($data);

Node.js / Server-side JS

const token = process.env.FILEMOON_API_TOKEN;

const response = await fetch('https://filemoon.org/api/v1/account', {
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: 'application/json'
  }
});

const data = await response.json();
if (!response.ok) {
  throw new Error(data?.error?.message || 'API request failed');
}
console.log(data);