Referencia de la API

Descripción general

La API de Uploadex te permite subir archivos, listarlos y actualizar metadatos de forma programática en nombre del titular de la clave de API. Cada endpoint es un recurso REST: JSON (o multipart para subidas binarias) de entrada, JSON de salida, solo HTTPS.

URL base: https://uploadex.net/api/v1
Autenticación: Tokens Bearer en la cabecera Authorization
Transporte: Solo HTTPS · TLS 1.2 o 1.3
Codificación: JSON UTF-8 · multipart/form-data para subidas
Fechas: ISO 8601 en UTC · 2026-04-21T08:12:04Z

Autenticación

Cada solicitud debe incluir una cabecera Authorization con un token Bearer. Crea y rota claves desde tu panel de desarrollador.

Authorization: Bearer ux_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Las claves empiezan por ux_live_. Se muestran exactamente una vez al crearlas: guárdalas en un gestor de secretos. Las claves pueden limitarse a acciones específicas (files:read, files:write, upload o *) y configurarse para que caduquen en una fecha futura.

El acceso a la API requiere un plan con acceso a la API habilitado. Si la cuenta se cambia a un plan sin acceso a la API, las claves existentes dejan de funcionar hasta que la cuenta vuelva a mejorar su plan. Revoca de inmediato las claves filtradas desde el panel de desarrollador.

Guía rápida

Obtén la información de tu cuenta para confirmar que la clave funciona.

# Get your account info
curl https://uploadex.net/api/v1/account \
  -H "Authorization: Bearer $UX_API_KEY"

Respuesta · 200 OK

{
  "data": {
    "id":               "clxxxxxxxxxxxxxxxxxxxxxx",
    "email":            "[email protected]",
    "name":             "Your Name",
    "plan":             "PRO",
    "balance":          0,
    "totalEarnings":    0,
    "storageUsed":      52428800,
    "storageLimit":     53687091200,
    "storageFormatted": "50 MB / 50 GB",
    "fileCount":        3,
    "createdAt":        "2026-04-01T09:21:00.000Z"
  }
}

Límites de los planes

Los límites de subida y almacenamiento dependen del plan y pueden cambiar cuando la cuenta mejora o reduce su plan. Límites de los planes que incluyen acceso a la API:

Plan	Tamaño máximo de archivo	Almacenamiento
Pro	10 GB	100 GB
Business	50 GB	1 TB
Business Plus	100 GB	5 TB

Límites de tasa

Los límites de tasa protegen el servicio del tráfico descontrolado. Superar un límite devuelve 429 Too Many Requests.

Ámbito	Límite	Ventana	Sujeto
Inicio de subida	30	1 min	por clave de API
Descarga	60	1 min	por IP
Inicio de sesión	10	15 min	por IP
Registro	5	1h	por IP

Errores

Las respuestas de error usan códigos de estado HTTP estándar y un cuerpo JSON coherente.

{ "error": "Invalid or missing API key" }

Estado	Significado
400	El cuerpo de la solicitud estaba mal formado o no superó la validación.
401	Clave de API ausente o no válida.
403	A la clave le falta un ámbito requerido (p. ej. files:write).
404	El recurso no existe o no pertenece al titular de la clave.
413	El archivo supera el límite de tamaño del plan de la cuenta.
429	Límite de tasa superado. Reduce el ritmo y vuelve a intentarlo.
500	Error interno. Consulta la página de estado antes de reintentar.

Paginación

Los endpoints de listado usan paginación por páginas. Pasa page (empezando en 1) y limit (máx. 100) como parámetros de consulta.

GET /api/v1/files?page=1&limit=50

Cuenta

GET/api/v1/account

Devuelve la información de la cuenta, el plan, el uso de almacenamiento y el número de archivos.

Ámbito: no se requiere ningún ámbito más allá de una clave válida.

Subida

POST/api/v1/upload

Inicia una subida multipart. Devuelve URL prefirmadas que el cliente usa para hacer PUT de los fragmentos al almacenamiento de objetos R2.

Campo	Tipo	Descripción
filename	string · required	Nombre del archivo, incluida la extensión (máx. 255 caracteres).
size	integer · required	Tamaño total del archivo en bytes.
contentType	string · required	Tipo MIME (máx. 200 caracteres).

Ámbito: upload. Devuelve 413 si size supera el límite del plan de la cuenta.

Archivos

GET/api/v1/files

Lista los archivos que pertenecen a la clave. Admite page, limit (máx. 100) y status.

GET/api/v1/files/:id

Recupera un único archivo por su ID.

PATCH/api/v1/files/:id

Actualiza displayName, description, tags o visibility.

DELETE/api/v1/files/:id

Elimina el archivo y recupera la cuota de almacenamiento.

{
  "data": {
    "id":            "clxxxxxxxxxxxxxxxxxxxxxx",
    "slug":          "9nK2xA",
    "filename":      "demo.mp4",
    "size":          881975296,
    "sizeFormatted": "841.1 MB",
    "mimeType":      "video/mp4",
    "status":        "READY",
    "scanStatus":    "CLEAN",
    "downloads":     128,
    "views":         412,
    "tags":          ["demo"],
    "visibility":    "PUBLIC",
    "adsEnabled":    true,
    "createdAt":     "2026-04-21T08:12:04.000Z",
    "updatedAt":     "2026-04-21T08:12:04.000Z"
  }
}

Ámbitos: GET requiere files:read; PATCH/DELETE requieren files:write.

API de Uploadex referencia.