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 mediante multipart/form-data. file es obligatorio; visibility acepta 1 o 0.

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