API REST

Envoyez des fichiers, créez des collections et gérez les partages via HTTP. Toutes les réponses sont au format JSON ; aucune clé API n’est requise pour les envois anonymes.

Introduction

L’API storage.to alimente notre CLI, application desktop, uploader web, et tout client tiers que vous souhaitez créer.

Le processus d’envoi se fait en trois étapes :

1. Initialiser - dites-nous que vous souhaitez envoyer un fichier. Nous renvoyons une ou plusieurs URL pré-signées pointant vers Cloudflare R2.
2. Envoyer vers R2 - PUT vos octets directement vers l(es) URL(s) pré-signée(s). Les octets ne passent pas par nos serveurs.
3. Confirmer - dites-nous que l’envoi est terminé. Nous créons un enregistrement File et vous fournissons une URL partageable.

URL de base

https://storage.to/api

Tous les endpoints ci-dessous sont relatifs à cette base. Exemple : POST /upload/init signifie POST https://storage.to/api/upload/init.

Authentification

Les envois anonymes fonctionnent sans authentification, mais avec des limites strictes. Les appels sans clé sont limités à 50 fichiers par 24 heures glissantes par appareil ou IP, plus les quotas de bande passante ci-dessous, et les fichiers expirent après 3 jours.

S'authentifier avec un compte gratuit débloque :

• Pas de plafond quotidien de fichiers
• Pas de quota de bande passante d'envoi
• Envois associés à votre compte (visibles à /dashboard)
• Fonctionnalités premium (fichiers permanents, stockage plus important)
• Modifications basées sur la propriété (supprimer, définir un mot de passe, modifier l’expiration) sans avoir besoin que le visitor-token corresponde

Limites en un coup d'œil

Il n'y a pas de quotas mensuels : toutes les limites sont des fenêtres glissantes de 24 heures ou des limites par minute. L'offre gratuite n'a pas d'espace de stockage fixe : chaque fichier expire de lui-même, rien ne s'accumule donc contre un quota.

Pour vous authentifier, générez un jeton API personnel depuis votre compte et envoyez-le comme jeton porteur (bearer) à chaque requête :

Authorization: Bearer <token>

Générer un jeton API

Vous devez être connecté. Le jeton complet n’est affiché qu’une seule fois lors de sa création : copiez-le dans un endroit sûr. Vous pouvez révoquer un jeton à tout moment depuis la même page.

Jeton visiteur

Les clients anonymes ont besoin d’un moyen de prouver qu’ils sont bien propriétaires de leurs propres envois, sans compte. Nous utilisons un visitor token - une chaîne aléatoire que le client génère une fois et réutilise. Envoyez-la avec chaque requête :

X-Visitor-Token: <random-string>

Sur le web, le jeton est stocké automatiquement dans le cookie visitor_token. La CLI le stocke à ~/.config/storageto/token (voir Docs CLI).

Pour les endpoints de mutation (suppression, définition du mot de passe, changement de l’expiration), la propriété est confirmée si soit le token du visiteur correspond à ou si la requête provient de la même IP que celle qui a créé le fichier. Les deux peuvent être perdus (cookies effacés, changements de réseau). À l’avenir, la preuve préférée est token du propriétaire.

Jeton propriétaire

Chaque endpoint qui crée une ressource (/upload/init multipart, /upload/confirm, /file/reserve, /collection) renvoie un owner_token dans sa réponse. Le token est une preuve signée de propriété liée à cette ressource précise, indépendante de votre IP ou de votre token de visiteur.

Conservez le token avec l’ID de la ressource et envoyez-le pour toute mutation comme :

Authorization: Owner <token>

Ou, si vous utilisez déjà Authorization: Bearer pour une session authentifiée, envoyez-le comme :

X-Owner-Token: <token>

Le serveur accepte le token du propriétaire comme preuve de propriété valide, en plus du mécanisme de secours historique visitor token + IP. Les clients qui possèdent le token continuent de fonctionner après avoir changé de réseau ou effacé les cookies, et les clients qui ne l’ont pas fonctionnent exactement comme avant.

Les tokens durent aussi longtemps que la ressource, sont sûrs à conserver et n’expirent pas indépendamment. Un token perdu signifie perdre le contrôle de cette ressource (fichier/collection/envoi) — traitez-les comme des mots de passe locaux.

Erreurs

Les erreurs suivent une structure cohérente :

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

Codes HTTP courants :

Limites de débit

Toutes les limites de débit sont par IP. Une réponse 429 inclut les en-têtes standards Retry-After, X-RateLimit-Limit et X-RateLimit-Remaining.

Quota de téléversement : Les clients anonymes ont deux plafonds en parallèle — 100 Go / 24 h par visitor token et 500 Go / 24 h par IP (le plafond IP capte le trafic sans token et les réseaux partagés). Dès qu’un plafond est dépassé, vous obtenez un 429 avec des détails. C’est un quota téléversement uniquement — les téléchargements sont illimités et non limités (servis directement via des URL signées R2).

Téléverser

Le flux de téléversement en trois étapes pour n’importe quel fichier, y compris les fichiers de plus de 5 Go (multipart automatiquement). Si vous avez seulement besoin d’un téléversement rapide de type capture d’écran, regardez plutôt ShareX.

Collections

Une collection regroupe plusieurs fichiers sous une seule URL de partage (/c/{id}). Jusqu’à 10 000 fichiers et 25 Go au total.

Fichiers

Tous les paramètres au niveau du fichier (mot de passe, expiration, max-downloads) reflètent les endpoints de la collection. Réservé au propriétaire.

Téléversement ShareX

Point d’envoi « one-shot » — envoyez un fichier multipart, recevez une URL partageable en retour. Pas de danse init/confirm. Idéal pour les outils de capture d’écran. Guide complet de configuration à /docs/sharex.

Authentification bureau

Pour les clients authentifiés (par ex. l’application desktop) disposant d’un token Sanctum.

Divers