Media

The Ágora CMS media manager gives you access to all files uploaded to the workspace: images, PDFs, videos and documents. The URLs are public, absolute and permanent — you can use them directly in your frontend with no additional processing. This endpoint is useful for building galleries, downloadable document listings or any section that consumes files managed from the panel.

GET /media — File listing

Returns the media files for the workspace with pagination. Files are ordered by upload date descending (newest first). Note that this endpoint does not accept the lang parameter because media files are not translated — the same file is used across all languages.

This endpoint does not accept the lang parameter because media files are not translated.

curl "https://your-panel.com/api/v1/media?web_id=abc-123&page=1&limit=20" \
  -H "X-API-Key: your-api-key"

const response = await fetch(
  'https://your-panel.com/api/v1/media?web_id=abc-123&page=1&limit=20',
  { headers: { 'X-API-Key': 'your-api-key' } }
)
const { data, meta } = await response.json()

{
  "data": [
    {
      "id": "media-001",
      "filename": "my-image.jpg",
      "url": "https://your-panel.com/uploads/workspace-id/abc-123/my-image.jpg",
      "mime_type": "image/jpeg",
      "size": 245120,
      "alt_text": "Image description for accessibility",
      "created_at": "2026-01-10T09:00:00Z"
    }
  ],
  "meta": { "total": 48, "page": 1, "limit": 20, "pages": 3 }
}

Response fields

The url field is an absolute URL ready to use directly as the src attribute of an <img> tag or the href of a download link. You don't need to build or transform the URL — use it as-is.

To filter by file type on the client, use the mime_type field. For example, to show only images filter by mime_type.startsWith('image/'), and for PDFs check mime_type === 'application/pdf'. If you need server-side type filtering, contact support — this feature may be added as a query parameter in a future version.

Use cases

Paginated image gallery. Call the endpoint with limit=12 or limit=24 and filter client-side for results where mime_type starts with image/. Implement a "Load more" button that increments the page and concatenates the new results to the existing array.

// Paginated gallery — fetch example
let page = 1
let allImages = []

async function loadImages() {
  const res = await fetch(
    `/api/v1/media?web_id=${WEB_ID}&page=${page}&limit=24`,
    { headers: { 'X-API-Key': API_KEY } }
  )
  const { data, meta } = await res.json()
  const images = data.filter(f => f.mime_type.startsWith('image/'))
  allImages = [...allImages, ...images]
  page++
  return meta.page < meta.pages // returns true if there are more pages
}

Downloadable document listing. Filter by mime_type === 'application/pdf' to show a "Documents" section with download links. Display the filename as the link text and the size formatted in KB or MB.

Image carousel with lazy loading. Fetch the images for a page and render the <img> tags with the loading="lazy" attribute. Use the alt_text field in the alt attribute — if it is null, use an empty string for decorative images or the filename as a fallback.

Tips and best practices

• Use the url field directly as the value of the src attribute in <img> tags. The URL is absolute and needs no additional prefix.
• Always add loading="lazy" to images that are not in the initial viewport (above the fold). This significantly improves load performance in galleries with many items.
• For large images or high-traffic galleries, consider placing an image proxy or CDN in front of the panel domain. Services like Cloudflare Images, imgproxy or Cloudinary can resize and optimise images on the fly from the original Ágora CMS URL.
• Always render alt_text in the alt attribute. If it is null, use alt="" for decorative images — never omit the attribute entirely.
• The size field is in bytes. To display it to users convert it: Math.round(size / 1024) for KB or (size / 1048576).toFixed(1) for MB.

Common errors

See also

• Posts — posts include the featured_image_url field pointing to a file in the media manager
• Content Types — CPT entries can also have image fields that use media manager URLs