Lister les médias

GET /api/v1/media Tous les médias de l'organisation, les plus récents d'abord. Contrairement aux autres listes de cette référence, la couche de stockage qui contient les médias ne renvoie jamais de total — cet endpoint pagine avec hasMore au lieu d'une paire page/total.

Autorisation

Rôle dans l'organisation	Cet endpoint
`OWNER`	Autorisé
`ADMIN`	Autorisé
`MEMBER`	Autorisé

Une clé porte le rôle que son créateur détient dans cette organisation — jamais un rôle sur AgentsMail lui-même. Voir Clés d'API.

Paramètres de requête

Paramètre	Type	Description
`folder`	string	Restreint la liste à un sous-dossier. Facultatif, la racine par défaut
`search`	string	Filtre sur le nom du fichier, sans tenir compte de la casse. Facultatif
`limit`	number	Éléments par page, `24` par défaut, plafonné à `100`
`offset`	number	Éléments à sauter, `0` par défaut

Exemple

bash

curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/media?folder=newsletter&limit=10"

Réponse

200 OK — les médias, accompagnés de hasMore.
400 Bad Request — folder ne se compose pas de lettres minuscules, de chiffres et de tirets.
401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.

Champs de la réponse

Champ	Type	Description
`success`	boolean	Indique si l'opération a réussi
`data.items`	array	Les médias
`data.items[].path`	string	L'identifiant du média — passez-le à Supprimer un média pour retirer ce fichier
`data.items[].url`	string	URL publique — un client de messagerie n'est jamais authentifié
`data.items[].name`	string	Nom du fichier
`data.items[].size`	number	Taille du fichier en octets
`data.items[].type`	string	Type MIME
`data.items[].createdAt`	string	Date de création ISO
`data.items[].folder`	string	Sous-dossier, absent à la racine de la médiathèque
`data.hasMore`	boolean	`true` s'il existe une page au-delà de `limit` + `offset`
`data.limit`	number	Le `limit` réellement appliqué
`data.offset`	number	L'`offset` réellement appliqué

Exemple de réponse

json

{
  "success": true,
  "data": {
    "items": [
      {
        "path": "organizations/7c2e…/media/newsletter/logo-1703123456789.jpg",
        "url": "https://…/logo-1703123456789.jpg",
        "name": "logo-1703123456789.jpg",
        "size": 48213,
        "type": "image/jpeg",
        "createdAt": "2026-08-29T10:00:00.000Z",
        "folder": "newsletter"
      }
    ],
    "hasMore": false,
    "limit": 24,
    "offset": 0
  }
}

Remarques

Il n'y a pas de pagination.total. La couche de stockage sur laquelle repose cette médiathèque ne sait pas compter sans tout lister — paginez avec offset et arrêtez-vous quand hasMore vaut false.