Alcance actual

La API está pensada para integraciones de carga, descarga y gestión básica de archivos temporales. Es útil para complementos, apps de escritorio, scripts o flujos automatizados que necesitan subir un archivo, obtener un enlace y administrar los archivos creados por la cuenta o la API key.

Acceso y API key

Para usar la API necesitas una cuenta y una API key aprobada. Puedes solicitarla desde la página de acceso. Cuando se apruebe, la clave se enviará por correo y quedará asociada a tu cuenta.

Envía la clave en uno de estos encabezados:

X-API-Key: mlft_tu_clave
Authorization: Bearer mlft_tu_clave

Si necesitas revocar una API key, entra al panel de tus archivos y usa la opción para revocar y enviar una nueva clave. La clave anterior dejará de funcionar cuando la nueva se haya enviado correctamente al correo de tu cuenta.

Endpoints disponibles

• POST https://transfer.marco-ml.com/api/upload/: sube un archivo y devuelve un enlace temporal.
• GET https://transfer.marco-ml.com/api/manage/files/: lista los archivos vigentes de la cuenta o API key.
• GET https://transfer.marco-ml.com/api/manage/files/ID/: consulta un archivo específico.
• PATCH https://transfer.marco-ml.com/api/manage/files/ID/: edita nombre personalizado, contraseña o expiración.
• DELETE https://transfer.marco-ml.com/api/manage/files/ID/: elimina un archivo.
• GET https://transfer.marco-ml.com/api/download/?file=ID: descarga el archivo asociado al identificador o nombre personalizado.
• POST https://transfer.marco-ml.com/api/download/?file=ID: descarga un archivo protegido enviando la contraseña.

Las respuestas de listado y detalle incluyen download_count, que indica cuántas veces se ha entregado correctamente el archivo.

Parámetros de subida

• file: archivo a subir. Es obligatorio.
• custom_path: nombre personalizado opcional para el enlace. Solo admite letras, números, guiones y guiones bajos.
• password: contraseña opcional para proteger la descarga.
• expire_hours: horas de vigencia. El máximo actual es de 168 horas, es decir, 7 días.

Respuesta correcta

{
  "success": true,
  "id": "2b3bd1c2-8e1d-4b34-8ef3-9f6c5dd0a111",
  "download_link": "https://transfer.marco-ml.com/api/download/?file=archivo",
  "original_name": "archivo.zip",
  "file_size": 123456,
  "expires_at": "2026-06-11 18:30:00",
  "expires_in_hours": 24
}

Errores comunes

• 401: falta la API key o la clave no es válida.
• 400: falta el archivo, el nombre personalizado no es válido o ya existe.
• 404: el archivo no existe, no pertenece a la cuenta/API key o ya expiró.
• 429: se superó un límite de subidas, transferencia o almacenamiento activo.

Ejemplo con curl

curl -X POST "https://transfer.marco-ml.com/api/upload/" \
  -H "X-API-Key: mlft_tu_clave" \
  -F "[email protected]" \
  -F "expire_hours=24" \
  -F "custom_path=mi_archivo"

Ejemplo con Python

import requests

url = "https://transfer.marco-ml.com/api/upload/"
headers = {"X-API-Key": "mlft_tu_clave"}

with open("archivo.zip", "rb") as archivo:
    respuesta = requests.post(
        url,
        headers=headers,
        files={"file": ("archivo.zip", archivo)},
        data={"expire_hours": "24"},
        timeout=120,
    )

respuesta.raise_for_status()
print(respuesta.json()["download_link"])

Ejemplo con JavaScript

const formData = new FormData();
formData.append("file", fileInput.files[0]);
formData.append("expire_hours", "24");

const response = await fetch("https://transfer.marco-ml.com/api/upload/", {
  method: "POST",
  headers: {
    "X-API-Key": "mlft_tu_clave"
  },
  body: formData
});

const data = await response.json();
console.log(data.download_link);

Listar archivos

curl "https://transfer.marco-ml.com/api/manage/files/" \
  -H "X-API-Key: mlft_tu_clave"

Editar un archivo

Usa el id devuelto al subir o al listar. expire_hours amplía la expiración desde el momento actual, pero nunca supera los 7 días desde la subida original.

curl -X PATCH "https://transfer.marco-ml.com/api/manage/files/2b3bd1c2-8e1d-4b34-8ef3-9f6c5dd0a111/" \
  -H "X-API-Key: mlft_tu_clave" \
  -H "Content-Type: application/json" \
  -d "{\"custom_path\":\"nuevo_nombre\",\"expire_hours\":72}"

Para establecer contraseña, envía password. Para quitarla, envía clear_password con valor true.

{
  "password": "nueva contraseña"
}

Eliminar un archivo

curl -X DELETE "https://transfer.marco-ml.com/api/manage/files/2b3bd1c2-8e1d-4b34-8ef3-9f6c5dd0a111/" \
  -H "X-API-Key: mlft_tu_clave"

Descargar archivos con contraseña

Las respuestas de listado y detalle incluyen has_password. Si vale true, la app debe avisar al usuario, pedir la contraseña en un diálogo propio y enviarla con POST al enlace de descarga.

curl -X POST "https://transfer.marco-ml.com/api/download/?file=archivo_protegido" \
  -H "Content-Type: application/json" \
  -d "{\"password\":\"contraseña del usuario\"}" \
  --output archivo_descargado.zip

Si una app intenta consultar un archivo protegido como JSON sin enviar contraseña, recibirá 403 con requires_password: true. Si la contraseña es incorrecta, recibirá 403 con el error correspondiente.

Si se superan los intentos permitidos de contraseña para ese archivo e IP, la API responderá con 429. La app debe mostrar el mensaje al usuario y esperar antes de reintentar.

Notas para complementos y apps

• Guarda la API key de forma local y privada. No la publiques en repositorios ni archivos compartidos.
• Muestra el error real devuelto por la API cuando exista el campo error.
• Para archivos grandes, usa una petición con progreso y un tiempo de espera amplio.
• El enlace de descarga puede expirar; guarda la fecha expires_at junto con el enlace.

Solicitar acceso