Listar medios

GET /api/v1/media Todos los medios de la organización, del más reciente al más antiguo. A diferencia de otros listados de esta referencia, la capa de almacenamiento que guarda los medios nunca devuelve un recuento total: este endpoint pagina con hasMore en lugar de un par página/total.

Autorización

Rol en la organización	Este endpoint
`OWNER`	Permitido
`ADMIN`	Permitido
`MEMBER`	Permitido

Una clave lleva el rol que su creador tiene en esta organización, nunca un rol en AgentsMail en sí. Consulta Claves de API.

Parámetros de consulta

Parámetro	Tipo	Descripción
`folder`	string	Restringe el listado a una subcarpeta. Opcional, por defecto la raíz
`search`	string	Filtra por el nombre del archivo, sin distinguir mayúsculas. Opcional
`limit`	number	Elementos por página, `24` por defecto, con un máximo de `100`
`offset`	number	Elementos que se omiten, `0` por defecto

Ejemplo

bash

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

Respuesta

200 OK: los medios, con hasMore junto a ellos.
400 Bad Request: folder no está formado por letras minúsculas, dígitos y guiones.
401 Unauthorized: clave ausente o no válida, o su propietario dejó la organización.

Campos de la respuesta

Campo	Tipo	Descripción
`success`	boolean	Indica si la operación tuvo éxito
`data.items`	array	Los medios
`data.items[].path`	string	El identificador del medio: pásalo a Eliminar un medio para borrar este archivo
`data.items[].url`	string	URL pública: un cliente de correo nunca está autenticado
`data.items[].name`	string	Nombre del archivo
`data.items[].size`	number	Tamaño del archivo en bytes
`data.items[].type`	string	Tipo MIME
`data.items[].createdAt`	string	Fecha de creación ISO
`data.items[].folder`	string	Subcarpeta, ausente en la raíz de la biblioteca de medios
`data.hasMore`	boolean	`true` si existe otra página más allá de `limit` + `offset`
`data.limit`	number	El `limit` aplicado realmente
`data.offset`	number	El `offset` aplicado realmente

Ejemplo de respuesta

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
  }
}

Notas

No hay pagination.total. La capa de almacenamiento sobre la que se construye esta biblioteca no puede contar sin listarlo todo: pagina con offset y detente cuando hasMore sea false.