FileMoon — Documentación de la API de FileMoon

FileMoon REST API

Introducción

La API de FileMoon es una API HTTP basada en JSON para automatizar cargas, gestionar archivos propios e importar URL directas de video autorizadas.

URL base	`https://filemoon.org/api/v1`
Versión actual	`v1`
Content-Type	`application/json` / `multipart/form-data`

Security: Usa HTTPS en cada solicitud. Nunca expongas tokens en código público, capturas, repositorios o registros compartidos.

Primeros pasos

Autenticación

Envía un token de acceso FileMoon en el encabezado Authorization usando el esquema Bearer.

HTTP Headers

Authorization: Bearer YOUR_FILEMOON_TOKEN
Accept: application/json

Crea el token desde Panel de Usuario → API & Remote Upload. El token completo solo se muestra una vez.

Permisos del token

files:readLeer cuenta, archivos y estados.

files:writeCargar, actualizar y eliminar archivos propios.

remote:writeCrear, cancelar y reintentar trabajos remotos.

HTTP 429

Límites de solicitudes

Los límites se aplican por token e IP. El límite activo aparece en los encabezados y no supera 60 solicitudes por minuto.

Response Headers

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

Después de HTTP 429, espera el valor de Retry-After.

Primeros pasos

Información de la cuenta

Devuelve cuenta, total de archivos, almacenamiento y contadores remotos.

GET /account

Parámetros

No hay parámetros de solicitud.

Ejemplo de solicitud

cURL

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

Ejemplo de respuesta

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
    }
  }
}

Archivos

Listar archivos

Devuelve una lista paginada. Usa search para filtrar por nombre.

GET /files

Parámetros

Campo	Tipo	Obligatorio	Descripción
`search`	string	Opcional	Filter by name or stored filename. Maximum 255 characters.
`page`	integer	Opcional	Pagination page. Minimum 1.
`per_page`	integer	Opcional	Results per page. Default 25, maximum 100.

Ejemplo de solicitud

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"

Ejemplo de respuesta

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
  }
}

Archivos

Información del archivo

Devuelve un archivo mediante su ID público de FileMoon.

GET /files/{id}

Parámetros

Campo	Tipo	Obligatorio	Descripción
`id`	string (path)	Sí	Public FileMoon file ID owned by the authenticated account.

Ejemplo de solicitud

cURL

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

Archivos

Estado del archivo y HLS

Devuelve archivo y estado de conversión HLS.

GET /files/{id}/status

Parámetros

Campo	Tipo	Obligatorio	Descripción
`id`	string (path)	Sí	Public FileMoon file ID owned by the authenticated account.

Ejemplo de solicitud

cURL

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

Ejemplo de respuesta

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"
    }
  }
}

Archivos

Cargar un archivo local

Carga un archivo mediante multipart/form-data. El campo file es obligatorio y visibility acepta 1 o 0. Para archivos grandes, utiliza la carga por partes de FileMoon con partes de 90 MB en el mismo endpoint POST /api/v1/files/upload. Envía el mismo dzuuid en todas las partes junto con dzchunkindex, dztotalchunkcount, dzchunksize, dztotalfilesize y dzchunkbyteoffset. Los índices comienzan en 0. Las cuentas Free registradas mantienen un límite de 4 GB por archivo y las cuentas Premium mantienen un límite de 15 GB por archivo. No envíes archivos grandes en una sola petición HTTP porque el proxy perimetral puede rechazar la petición antes de que llegue a la API. Importante: el campo multipart file de cada parte debe conservar exactamente el mismo nombre de archivo original. Los nombres locales temporales de las partes pueden ser diferentes, pero el nombre de archivo original enviado mediante multipart debe permanecer igual en todas las partes. No se requiere ningún campo dzlastchunk; FileMoon detecta automáticamente la finalización cuando todas las partes están presentes. El ensamblado final ocurre durante el flujo de carga y no existe un endpoint separado de estado de ensamblado mediante dzuuid.

POST /files/upload

Parámetros

Campo	Tipo	Obligatorio	Descripción
`file`	binary	Sí	Local file attached as multipart/form-data.
`visibility`	boolean	Opcional	Use 1 for public or 0 for private.

Ejemplo de solicitud

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"

Archivos

Actualizar archivo

Cambia metadatos compatibles. Envía solo los campos necesarios.

PATCH /files/{id}

Parámetros

Campo	Tipo	Obligatorio	Descripción
`id`	string (path)	Sí	Public FileMoon file ID.
`name`	string	Opcional	New file name. Maximum 255 characters.
`description`	string\|null	Opcional	File description. Maximum 1000 characters.
`visibility`	boolean	Opcional	Public or private visibility.
`allow_online_watch`	boolean	Opcional	Enable or disable online video watch.
`password`	string\|null	Opcional	Set, change or remove the file password.

Ejemplo de solicitud

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
  }'

Archivos

Eliminar archivo

Elimina permanentemente el archivo y los datos relacionados.

DELETE /files/{id}

Parámetros

Campo	Tipo	Obligatorio	Descripción
`id`	string (path)	Sí	Public FileMoon file ID.

Ejemplo de solicitud

cURL

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

Carga remota

Crear trabajos remotos

Añade una o varias URL a la cola. HTTP 202 confirma el procesamiento en segundo plano.

Acepta URL públicas y directas HTTP/HTTPS. Se bloquean redes privadas, localhost, metadatos de nube, redirecciones inseguras, scripts y respuestas no-vídeo.

POST /remote-uploads

Parámetros

Campo	Tipo	Obligatorio	Descripción
`urls`	array<string>	Sí	One or more public direct HTTP/HTTPS media URLs.
`name`	string\|null	Opcional	Custom file name. Maximum 240 characters.
`description`	string\|null	Opcional	Description. Maximum 1000 characters.
`folder_id`	integer\|null	Opcional	Folder ID owned by the authenticated user.
`visibility`	boolean	Opcional	Public or private file.
`allow_online_watch`	boolean	Opcional	Allow online video playback.
`password`	string\|null	Opcional	Optional file password.
`blocked_countries`	array<string>	Opcional	Two-letter country codes. Maximum 250 entries.

Ejemplo de solicitud

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"]
  }'

Ejemplo de respuesta

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
    }
  ]
}

Valores de estado

pendingrunningcompletedfailedcancelled

Carga remota

Listar trabajos remotos

Devuelve los trabajos remotos de la cuenta con paginación.

GET /remote-uploads

Parámetros

Campo	Tipo	Obligatorio	Descripción
`page`	integer	Opcional	Pagination page.
`per_page`	integer	Opcional	Default 25, maximum 100.

Ejemplo de solicitud

cURL

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

Carga remota

Estado de carga remota

Devuelve progreso, etapa, errores y el ID del archivo creado.

GET /remote-uploads/{id}

Parámetros

Campo	Tipo	Obligatorio	Descripción
`id`	UUID (path)	Sí	Remote-upload job ID.

Ejemplo de solicitud

cURL

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

Ejemplo de respuesta

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"
  }
}

Carga remota

Cancelar trabajo remoto

Cancela un trabajo pendiente o solicita cancelar uno en ejecución.

POST /remote-uploads/{id}/cancel

Parámetros

Campo	Tipo	Obligatorio	Descripción
`id`	UUID (path)	Sí	Remote-upload job ID.

Ejemplo de solicitud

cURL

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

Carga remota

Reintentar trabajo remoto

Reinicia un trabajo fallido o cancelado y lo coloca de nuevo en la cola.

POST /remote-uploads/{id}/retry

Parámetros

Campo	Tipo	Obligatorio	Descripción
`id`	UUID (path)	Sí	Remote-upload job ID.

Ejemplo de solicitud

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

Errores y códigos de estado

Los errores usan una estructura JSON consistente. Guarda request_id para soporte.

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.

Ejemplo de respuesta

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"
}

Referencia

Requisitos de seguridad

Aplica estas reglas al integrar la API.

Guarda los tokens en un servidor confiable y revoca los tokens expuestos.

Usa solo los permisos mínimos necesarios.

Restringe el token a IP o CIDR confiables cuando sea posible.

Carga únicamente contenido propio o autorizado.

cURL · PHP · JavaScript

Ejemplos de clientes

Ejemplos mínimos de cURL, PHP y JavaScript del lado del servidor.

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);