REST API

Sube archivos, crea colecciones y gestiona compartidos mediante HTTP. Todas las respuestas son JSON; no se requiere una clave de API para subidas anónimas.

Introducción

La API de storage.to impulsa nuestro CLI, app de escritorio, cargador web y cualquier cliente de terceros que quieras crear.

El flujo de subida tiene tres pasos:

1. Iniciar - dinos que quieres subir un archivo. Te devolvemos una o más URL prefirmadas que apuntan a Cloudflare R2.
2. Subir a R2 - PUT tus bytes directamente a las URL(s) prefirmadas. Los bytes no pasan por nuestros servidores.
3. Confirmar - avísanos cuando la subida haya terminado. Creamos un registro de File y te damos una URL compartible.

URL base

https://storage.to/api

Todos los endpoints de abajo son relativos a esta base. Ejemplo: POST /upload/init significa POST https://storage.to/api/upload/init.

Autenticación

Las subidas anónimas funcionan sin autenticación, pero con límites estrictos. Las llamadas sin clave están limitadas a 50 archivos por cada 24 horas por dispositivo o IP, más las cuotas de ancho de banda de abajo, y los archivos caducan a los 3 días.

Autenticarse con una cuenta gratuita desbloquea:

• Sin límite diario de archivos
• Sin cuota de ancho de banda de subida
• Subidas vinculadas a tu cuenta (visibles en /dashboard)
• Funciones premium (archivos permanentes, más almacenamiento)
• Mutaciones basadas en la propiedad (eliminar, establecer contraseña, cambiar caducidad) sin necesidad de que coincida el visitor-token

Límites de un vistazo

No hay cuotas mensuales: todos los límites son ventanas móviles de 24 horas o límites por minuto. El plan gratuito no tiene un espacio de almacenamiento fijo: cada archivo caduca por sí solo, así que nada se acumula contra una cuota.

Para autenticarte, genera un token de API personal desde tu cuenta y envíalo como token bearer en cada solicitud:

Authorization: Bearer <token>

Generar token de API

Necesitas haber iniciado sesión. El token completo solo se muestra una vez al crearlo, así que cópialo en un lugar seguro. Puedes revocar un token en cualquier momento desde la misma página.

Token de visitante

Los clientes anónimos necesitan una forma de demostrar la propiedad de sus propias subidas sin tener una cuenta. Usamos un visitor token: una cadena aleatoria que el cliente genera una vez y reutiliza. Envíala con cada solicitud:

X-Visitor-Token: <random-string>

En la web, el token se guarda automáticamente en la cookie visitor_token. La CLI lo guarda en ~/.config/storageto/token (ver Documentación de la CLI).

Para los endpoints de mutación (borrar, establecer contraseña, cambiar la caducidad), la propiedad se confirma si o el token del visitante coincide o la solicitud proviene de la misma IP que creó el archivo. Ambas cosas pueden perderse (cookies borradas, cambios de red). El token del propietario es la prueba preferida a partir de ahora.

Token de propietario

Cada endpoint que crea recursos (/upload/init multipart, /upload/confirm, /file/reserve, /collection) devuelve un owner_token en su respuesta. El token es una prueba firmada de propiedad vinculada a ese recurso específico, independiente de tu IP o del token del visitante.

Guarda el token junto con el ID del recurso y envíalo en cualquier mutación como:

Authorization: Owner <token>

O, si ya estás usando Authorization: Bearer para una sesión autenticada, envíalo como:

X-Owner-Token: <token>

El servidor acepta el token del propietario como prueba válida de propiedad junto con el respaldo heredado visitor token + IP: los clientes que tienen el token siguen funcionando al cambiar de red o borrar cookies, y los clientes que no lo tienen siguen funcionando exactamente como antes.

Los tokens viven mientras viva el recurso, son seguros para persistir y no caducan de forma independiente. Perder un token significa perder el control de ese recurso (archivo/colección/subida): trátalos como contraseñas locales.

Errores

Los errores siguen una estructura consistente:

{
  "success": false,
  "error": "Human-readable message"
}

Códigos de estado HTTP comunes:

Límites de velocidad

Todos los límites de velocidad son por IP. Una respuesta 429 incluye los encabezados estándar Retry-After, X-RateLimit-Limit y X-RateLimit-Remaining.

Cuota de subida: Los clientes anónimos tienen dos límites en paralelo: 100 GB / 24 h por visitor token y 500 GB / 24 h por IP (el límite de IP detecta el tráfico sin token y redes compartidas). Cuando se supera cualquiera, recibirás un 429 con detalles. Esto es solo una cuota de subida: las descargas son ilimitadas y sin limitación (se sirven directamente desde URLs firmadas de R2).

Subir

El flujo de subida en tres pasos para cualquier archivo, incluidos los de más de 5 GB (multipart automáticamente). Si solo necesitas una subida rápida tipo captura de pantalla, mira ShareX.

Colecciones

Una colección agrupa varios archivos bajo una única URL de compartición (/c/{id}). Hasta 10.000 archivos y 25 GB en total.

Archivos

Todas las configuraciones a nivel de archivo (contraseña, caducidad, max-downloads) reflejan los endpoints de la colección. Solo el propietario.

Subida con ShareX

Endpoint de subida de un solo paso: envía un archivo multipart y recibe una URL compartible. Sin el baile de init/confirm. Ideal para herramientas de capturas de pantalla. Guía completa de configuración en /docs/sharex.

Autenticación de escritorio

Para clientes autenticados (por ejemplo, la app de escritorio) que tengan un token de Sanctum.

Varios