Opérations sur les fichiers

Chaque bucket expose les mêmes trois points de terminaison. Le segment {bucket} est un nom de votre tableau buckets[], ou default pour le bucket implicite.

Points de terminaison

Un nom de bucket inconnu répond 404 sur les trois, avant toute autre lecture.

Téléversement

Envoyez le fichier en données de formulaire multipart, sous le nom de champ file.

curl -X POST https://app.example.com/api/buckets/documents/files \
  -H "Cookie: $SESSION" \
  -F "file=@report.pdf"

{
  "success": true,
  "key": "9f3c1e2a-7b44-4d10-9e21-8a6f0c1d2e3b-report.pdf",
  "size": 245760,
  "mimeType": "application/pdf",
  "filename": "report.pdf"
}

Stocker à un chemin explicite

Un champ de formulaire facultatif path stocke le fichier à cette clé exacte, sans préfixe UUID. C'est ainsi qu'on place un fichier sous un préfixe listé dans STORAGE_PUBLIC_PATHS :

curl -X POST https://app.example.com/api/buckets/default/files \
  -F "file=@logo.png" -F "path=public/logo.png"

Le chemin doit être relatif, non vide, et exempt de .., \ et d'octets nuls. Puisque vous choisissez la clé, vous assumez aussi les collisions : un second téléversement sur le même chemin écrase le premier.

Téléchargement

curl https://app.example.com/api/buckets/documents/files/$KEY -O

Les clés d'image acceptent des paramètres de transformation sur cette même URL ; tout autre type renvoie 400 si vous essayez. Chaque réponse porte Content-Disposition, X-Content-Type-Options: nosniff et une Content-Security-Policy bloquante — voir Sécurité des téléversements.

Suppression

curl -X DELETE https://app.example.com/api/buckets/documents/files/$KEY \
  -H "Cookie: $SESSION"

Le succès est un 204 sans corps ; une clé inconnue donne 404. La suppression purge également toutes les transformations d'image mises en cache pour cette clé : une vignette obsolète ne peut jamais survivre à son original.

Supprimer un fichier directement ne nettoie pas l'enregistrement de table qui le référence. Retirer la pièce jointe d'un enregistrement est un chemin distinct — voir Cycle de vie et quotas.

Durcissement de sécurité

Déplacé vers Sécurité des téléversements — validation des noms de fichiers, listes MIME autorisées, et en-têtes portés par chaque fichier servi.

Cycle de vie des fichiers

Déplacé vers Cycle de vie et quotas — ce qu'il advient d'un fichier quand son enregistrement est supprimé.

Gros téléversements et quota

Déplacé vers Cycle de vie et quotas — plafonds de taille, quota de stockage total et point de terminaison d'usage administrateur.

Pages associées

• Présentation des buckets — déclarer les buckets servis par ces points de terminaison.
• Permissions de bucket — qui peut appeler chaque point de terminaison.
• Sécurité des téléversements — ce qui est rejeté et pourquoi.
• Cycle de vie et quotas — rétention, limites, quota.
• URL signées — accès sans session.
• Champs de pièce jointe et stockage — les mêmes fichiers, atteints depuis un enregistrement.