Upload API

Upload est une ressource temporaire créée en téléversant un fichier. C'est la première étape avant de créer un Media : lorsque vous téléversez un fichier, la réponse renvoie un Upload, et vous utilisez les informations de cet Upload pour créer un Media. La création d'un Media se fait via CMA (Weegloo User) ou ACMA (Service User) et sort du périmètre de cette page.

Upload est une ressource temporaire. Elle expire 24 heures après sa création (expiresAt), et si elle n'est pas convertie en Media dans ce délai, elle disparaît. Upload n'a aucune notion de publication ni de version (pas de propriétés version, status ou publish). Elle n'a pas non plus de champs de contenu : elle ne possède que les propriétés système sys. L'URL de base est https://upload.weegloo.com/v1, et toutes les requêtes nécessitent un jeton Bearer qui authentifie l'Upload.

Structure de la ressource

Voici la réponse d'un Upload correspondant à une photo de produit de boutique de vêtements (l'image d'un gobelet) téléversée dans un Space. Il n'y a que sys, qui contient des clés telles que owner, expiresAt et size.

{
  "sys": {
    "id": "4bgMfu7cFGYDRQn4jdqFI8tkOWKZIm",
    "type": "Upload",
    "owner": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T04:48:44.057Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T04:48:44.057Z",
    "expiresAt": "2026-06-19T04:48:44.057Z",
    "size": 50847
  }
}

Clés principales :

• sys.id : l'identifiant unique de l'Upload. Vous transmettez cette valeur lors de la création d'un Media. Elle figure également dans le {uploadId} des chemins de consultation unitaire et de suppression.
• sys.owner : une référence indiquant l'entité à laquelle appartient cet Upload. Son targetType est Space ou Organization (voir Contexte Space et Organization ci-dessous).
• sys.expiresAt : l'instant d'expiration. Il est fixé à 24 heures après createdAt, et passé cet instant l'Upload disparaît.
• sys.size : la taille du fichier téléversé (en octets). L'exemple ci-dessus est de 50847 octets.

Propriétés système (sys)

Chaque Upload place ses propriétés système dans l'objet sys. owner, createdBy et updatedBy prennent la forme Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Les 9 propriétés ci-dessus sont toujours incluses dans la réponse. Les propriétés version, status et publish présentes dans le sys d'un Content ou d'un Content Type n'existent pas pour un Upload. En effet, Upload n'est pas une ressource que l'on publie ou que l'on versionne, mais un matériau à usage unique servant à créer un Media. Contrairement au space d'autres ressources qui pointe vers un seul type, owner pointe vers un Space ou un Organization selon son targetType.

Contexte Space et Organization

Un Upload peut être créé dans deux contextes, et selon le contexte le chemin et le sys.owner diffèrent.

Un Upload dans le contexte Space est le matériau servant à créer les Media de ce Space. Un Upload dans le contexte Organization sert à téléverser un fichier utilisé directement par l'organisation, comme une icône d'organisation. Dans les deux cas, la structure de ressource renvoyée en réponse est identique ; seule la valeur targetType de sys.owner change.

Modes de téléversement : multipart et binary

La requête POST qui téléverse un fichier admet deux modes. Quel que soit le mode, ce qui est renvoyé en réponse est la même ressource Upload.

Le mode multipart envoie le corps de la requête en multipart/form-data. Le fichier est placé dans un champ de formulaire nommé file. Il convient aux situations d'envoi sous forme de données de formulaire, par exemple un téléversement direct depuis un champ de sélection de fichier dans le navigateur.

Le mode binary place les octets bruts du fichier directement dans le corps de la requête. Le type de média du corps (Content-Type) n'est pas contraint (on utilise généralement application/octet-stream), et dans le contexte Space l'en-tête Content-Length doit indiquer la longueur en octets du corps. Il convient par exemple au code côté serveur qui transmet uniquement les octets du fichier sans structure de formulaire.

API

L'URL de base de tous les endpoints ci-dessous est https://upload.weegloo.com/v1, et l'en-tête Authorization doit contenir un jeton Bearer qui authentifie l'Upload. Sont d'abord traités les 4 endpoints du contexte Space, puis les 4 du contexte Organization.

Documents connexes

• Media : le format de requête pour créer un Media à partir d'un Upload téléversé.
• Media (concept) : comment manipuler les actifs de fichier dans le studio de contenu.