Stockage de fichiers booster

Un panneau Booster peut conserver des fichiers : documents téléversés par ses utilisateurs, factures et exports générés par un workflow, images de produits. Les endpoints de cette page permettent à votre serveur de travailler avec ces fichiers avec une clé API : téléverser un rapport généré, lister ce que les visiteurs ont envoyé, obtenir un lien de téléchargement, faire le ménage.

Les endpoints se trouvent sous /api/v3/booster/storage/private/. Les panneaux eux-mêmes accèdent à leurs fichiers par un autre chemin d'accès, qui n'est pas décrit ici.

Concepts #

Dossiers et chemins #

Les fichiers sont désignés par un chemin : un dossier de premier niveau, des sous-dossiers facultatifs et le nom du fichier, séparés par /, par exemple invoices/2026/INV-0042.pdf.

• Le nom du dossier peut contenir des lettres, des chiffres, _ et -.
• Les noms de sous-dossiers et de fichiers peuvent contenir n'importe quel caractère sauf les caractères de contrôle et / \ : * ? " < > | # % ' ; ils ne peuvent pas valoir . ou .. ni commencer ou se terminer par une espace.
• Un chemin a au moins deux parties (<folder>/<name>), au plus 8 niveaux et 512 caractères.
• Les dossiers et sous-dossiers ne sont pas créés séparément : ils existent tant qu'ils contiennent un fichier. Un chemin est unique au sein d'un panneau.

Paramètres du stockage de fichiers #

Le propriétaire du panneau active le stockage de fichiers et définit les dossiers dans les paramètres des modules du panneau dans l'application. Pour chaque dossier (ou * pour tous les autres), les paramètres indiquent qui peut téléverser, lire, lister, modifier et supprimer des fichiers, quels types de fichiers il accepte, quelle taille un fichier peut avoir, combien de fichiers il peut contenir et si les fichiers sont supprimés après un certain nombre de jours. Un dossier peut fournir des liens publics permanents (pour des images affichées sur une page publique).

Qui peut accéder aux fichiers d'un panneau #

Les requêtes agissent au nom de l'utilisateur propriétaire de la clé API. Cet utilisateur doit être propriétaire du panneau (en être le créateur, ou membre du groupe qui le possède) ou avoir reçu le panneau en partage, directement ou via un groupe. La clé API doit porter la portée correspondante :

La portée d'écriture n'inclut pas la portée de lecture ; une clé qui lit et écrit a besoin des deux. Les endpoints fonctionnent aussi lorsque le stockage de fichiers du panneau est désactivé, de sorte que vous pouvez toujours lire et nettoyer les fichiers stockés.

Pour les requêtes de cette page, les paramètres des dossiers s'appliquent ainsi :

• Une opération réglée sur none pour un dossier est désactivée pour tout le monde, y compris pour cette API (403).
• Tous les autres niveaux autorisent les requêtes API, sur tous les fichiers du dossier.
• Un dossier sans paramètres (et sans entrée *) n'est accessible qu'à l'API et au propriétaire.
• Les types de fichiers acceptés, la limite de taille des fichiers et les limites de nombre de fichiers et de volume de données par dossier s'appliquent aux téléversements via cette API.

Fichiers #

Fichiers et enregistrements de la base de données #

Un fichier peut appartenir à un enregistrement de la base de données du panneau : envoyez la collection et la clé de l'enregistrement avec le téléversement, ou définissez-les plus tard avec update. L'enregistrement doit exister dans la base de données du panneau. Par défaut, un fichier est supprimé lorsque son enregistrement est supprimé ; les paramètres du dossier peuvent le conserver. Stockez l'id (ou le path) du fichier dans la valeur de l'enregistrement lorsque votre panneau doit retrouver le fichier à partir de l'enregistrement.

Liens de téléchargement #

Les liens sont des URL absolues sous /api/v3/booster/storage/file/ et ne nécessitent aucun en-tête : ils fonctionnent donc dans <img src>, <a href> et depuis d'autres serveurs.

• Un lien est signé et valable 60 minutes. Demandez-en un nouveau avec Obtenir des liens de téléchargement au moment où vous en avez besoin, plutôt que de stocker des liens.
• Dans les dossiers avec des liens publics permanents, url n'expire jamais. Il cesse de fonctionner lorsque le dossier ne fournit plus de liens publics ou que le fichier est supprimé.
• Les images, l'audio, la vidéo et les PDF sont affichés dans le navigateur ; les autres types (et chaque download_url) sont téléchargés. Les fichiers HTML, SVG et XML sont toujours téléchargés.
• Les liens d'images acceptent ?w= et ?h= (pixels) pour une copie redimensionnée, par ex. des vignettes.
• Les liens prennent en charge les requêtes Range (déplacement dans l'audio et la vidéo).

Limites #

Les fichiers comptent également dans le quota de stockage du propriétaire du panneau ou, pour les panneaux d'une organisation, dans celui de l'organisation.

En-têtes de requête et erreurs communs #

Les erreurs sont du JSON de la forme {"detail": "..."} (voir Erreurs). Celles-ci peuvent provenir de tous les endpoints :

Téléverser un fichier #

Stocke un fichier. Envoyez-le en multipart/form-data.

Requête #

Réponse #

Le fichier stocké, avec ses liens.

Erreurs #

Exemples #

curl -X POST "https://ayeto.ai/api/v3/booster/storage/private/upload" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "panel-id: 3d2c5a8e-7b41-4f0e-9a6d-2c8b1e4f7a90" \
  -F "file=@INV-0042.pdf;type=application/pdf" \
  -F "path=invoices/2026/" \
  -F 'metadata={"customer": "ACME", "total": 1250}' \
  -F "record_collection=orders" \
  -F "record_key=8f14e45f-ceea-467a-9b1c-4e1f2a6b3c70"

{
  "id": "5b0a1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d",
  "path": "invoices/2026/INV-0042.pdf",
  "folder": "invoices",
  "name": "INV-0042.pdf",
  "size": 48213,
  "content_type": "application/pdf",
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "metadata": {"customer": "ACME", "total": 1250},
  "record": {"collection": "orders", "key": "8f14e45f-ceea-467a-9b1c-4e1f2a6b3c70"},
  "owner": null,
  "created": 1791374100000,
  "updated": 1791374100000,
  "expires_at": null,
  "url": "https://ayeto.ai/api/v3/booster/storage/file/3d2c5a8e-…/5b0a1c2d-…/1791377700i.Xk2…/INV-0042.pdf",
  "download_url": "https://ayeto.ai/api/v3/booster/storage/file/3d2c5a8e-…/5b0a1c2d-…/1791377700a.p9Q…/INV-0042.pdf"
}

Téléverser un fichier en base64 #

Identique à Téléverser un fichier avec un corps JSON, pour les petits fichiers.

Requête #

Réponse et erreurs #

Comme pour Téléverser un fichier, plus 422 data is not valid base64.

Exemple #

curl -X POST "https://ayeto.ai/api/v3/booster/storage/private/upload-b64" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "panel-id: 3d2c5a8e-7b41-4f0e-9a6d-2c8b1e4f7a90" \
  -H "Content-Type: application/json" \
  -d '{"path": "exports/orders-2026-10.csv", "data": "data:text/csv;base64,aWQsdG90YWwKMSwxMjUw"}'

Téléverser directement un gros fichier #

Les gros fichiers (de dizaines à centaines de Mo) peuvent aller directement au service de stockage au lieu de passer par l'API, en trois étapes : annoncer le fichier, l'envoyer en POST à l'URL renvoyée, terminer le téléversement. La disponibilité du téléversement direct dépend de l'installation AYETO ; lorsqu'il n'est pas disponible, upload/init répond 409 direct upload is not available, use the upload route et vous utilisez Téléverser un fichier.

1. upload/init avec path, filename (lorsque le chemin se termine par /), content_type, size (taille exacte en octets) et éventuellement metadata, record, overwrite, rename. Les règles du dossier, le type et les limites sont vérifiés comme pour un téléversement. La réponse est {upload_id, url, fields, expires_at}.
2. POST vers url en multipart/form-data : chaque entrée de fields comme champ du formulaire, puis le fichier comme champ file (il doit être la dernière partie). Le fichier doit avoir exactement la taille et le type annoncés. Cette requête va au service de stockage, sans votre clé API.
3. upload/complete avec {"upload_id": "…"} avant expires_at (une heure). Le contenu téléversé est vérifié à nouveau (taille, type d'après le contenu) et le fichier est renvoyé. Un téléversement jamais terminé est supprimé.

Autres erreurs comme pour Téléverser un fichier.

Lister les fichiers #

Renvoie les fichiers situés directement dans un répertoire ainsi que ses sous-dossiers. Sans folder, renvoie les dossiers de premier niveau du panneau.

Requête #

Réponse #

{"files": [...], "folders": [...]} : les fichiers de la page et les noms des sous-dossiers situés directement dans le répertoire.

Exemple #

curl -X POST "https://ayeto.ai/api/v3/booster/storage/private/list" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "panel-id: 3d2c5a8e-7b41-4f0e-9a6d-2c8b1e4f7a90" \
  -H "Content-Type: application/json" \
  -d '{"folder": "invoices", "prefix": "2026", "params": {"filters": [["metadata.customer", "==", "ACME"]]}}'

Compter les fichiers #

Le nombre de fichiers qu'une liste avec les mêmes folder, prefix, recursive (ici true par défaut) et params.filters renverrait sur l'ensemble des pages. Sans folder, tous les fichiers du panneau.

Obtenir un fichier #

Un fichier avec de nouveaux liens, par id ou par path.

{"path": "invoices/2026/INV-0042.pdf"}

Obtenir des liens de téléchargement #

De nouveaux liens pour 100 fichiers au plus.

Requête #

Réponse #

Un tableau de {id, url, expires_at} ; expires_at (millisecondes) vaut null pour les liens publics permanents.

Mettre à jour un fichier #

Renomme ou déplace un fichier, remplace ses métadonnées ou son enregistrement. Un déplacement vers un autre dossier nécessite le droit de téléversement dans celui-ci et le droit de suppression dans le dossier actuel, et le fichier doit respecter les règles de type et de taille du nouveau dossier. Le contenu ne change jamais ; pour le remplacer, téléversez avec overwrite.

Requête #

Réponse et erreurs #

Le fichier mis à jour. Erreurs comme pour Téléverser un fichier ; 409 lorsque le nouveau chemin est pris.

Supprimer des fichiers #

Renvoie {"accepted": true}. Les liens d'un fichier supprimé cessent immédiatement de fonctionner. delete-many supprime les fichiers dans l'ordre et s'arrête au premier qui échoue.

Utilisation du stockage #

{"files": 214, "size": 73400320, "limit": 1073741824, "folders": {"invoices": 52428800, "products": 20971520}}

limit est la limite du panneau en octets (0 = seul le quota de stockage du propriétaire s'applique).

Événements #

Les fichiers enregistrés, modifiés (déplacés, nouvelles métadonnées ou nouvel enregistrement) et supprimés via cette API sont des événements du panneau comme les autres : ils démarrent les workflows ayant un déclencheur de fichier booster sur le panneau, et les webhooks du panneau abonnés aux événements de fichiers les reçoivent. Les suppressions dues à la durée de conservation ou à la suppression d'un enregistrement sont aussi des événements.