List media

GET /api/v1/media Every media of the organization, most recent first. Unlike other listings in this reference, the storage layer that holds media never returns a total count — this endpoint pages with hasMore instead of a page/total pair.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Allowed

A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

Query parameters

Parameter	Type	Description
`folder`	string	Restricts the listing to one sub-folder. Optional, defaults to the root
`search`	string	Filters on the file name, case-insensitive. Optional
`limit`	number	Items per page, default `24`, capped at `100`
`offset`	number	Items to skip, default `0`

Example

bash

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

Response

200 OK — the media, with hasMore next to them.
400 Bad Request — folder is not lowercase letters, digits and dashes.
401 Unauthorized — missing or invalid key, or its owner left the organization.

Response fields

Field	Type	Description
`success`	boolean	Indicates if the operation was successful
`data.items`	array	The media
`data.items[].path`	string	The media's identifier — pass it to Delete a media to remove this file
`data.items[].url`	string	Public URL — an email client is never authenticated
`data.items[].name`	string	File name
`data.items[].size`	number	File size in bytes
`data.items[].type`	string	MIME type
`data.items[].createdAt`	string	ISO creation date
`data.items[].folder`	string	Sub-folder, absent at the root of the media library
`data.hasMore`	boolean	`true` if a further page exists beyond `limit` + `offset`
`data.limit`	number	The `limit` actually applied
`data.offset`	number	The `offset` actually applied

Example response

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

Notes

There is no pagination.total. The storage layer this library is built on cannot count without listing everything — paginate with offset and stop when hasMore is false.