---
title: "List the media library"
method: GET
path: "/media"
tags: ["Media"]
---

# List the media library

`GET /media`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/media`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.hypamoon.com/oauth/authorize`, token URL `https://api.hypamoon.com/oauth/token`, scopes: `sites:read`)

Every photo and file the user uploaded to the project's media library (in the portal under Media, or with an upload link from POST /media/links), newest first, with the folders. Per file: path under /media/, size, width and height, the 640 version for srcset, alt text, and the sites that use it. A file on no site has url null: it is private until you put it on a site with POST /sites or PUT /sites/{id} and media. Never contains the bytes. folder narrows to a folder (with its subfolders), path to one file, site_id to the files on one site.

## Query parameters

- `folder` string
- `path` string
- `site_id` string, uuid
- `limit` integer
- `cursor` string
- `tag` string
- `kind` 'image' | 'video' | 'audio' | 'pdf' | 'font' | 'archive' | 'document' | 'data' | 'other'
- `q` string
- `include_deleted` boolean

## Response `200`

The files and the folders.

- MediaList
  - `data` MediaFile[], required
    - `id` string, uuid, required: The id of the file in the library.
    - `path` string, required: Where the file goes on a site when you add it with deploy_site media, like /media/portfolio/project-12/03.webp.
    - `folder` string, required: The folder under /media/, empty for /media/ itself.
    - `name` string, required: The file name in the library.
    - `original_name` string, nullable, required: The name on the user's computer, when it differs.
    - `content_type` string, required
    - `bytes` integer, required
    - `width` integer, nullable, required
    - `height` integer, nullable, required
    - `alt` string, nullable, required: The alt text, set with update_media.
    - `url` string, nullable, required: Where the file is served, on the first site that has it at this path. null: it is on no site yet; it is private until you add it with deploy_site media.
    - `variants` object, required: For photos: 640, the small version for srcset and thumbnails.
    - `srcset` string, nullable, required: A ready srcset for an img tag once the file is on a site: small webp versions at 160, 320, 640 and 1280 wide (from /_hypamoon/img on that site) plus the file itself. Always add sizes with the width it is shown at, like sizes="52px" for a thumbnail.
    - `thumbnail_url` string, nullable, required: A small webp, 160 wide, for thumbnails up to about 80 px (search suggestions, lists, a cart). null while the file is on no site, or for a file that is not a photo.
    - `original_kept` boolean, required: The full-size original is kept privately. It never goes on a site; the user downloads it in the portal.
    - `sites` object[], required: The sites that use this file right now, with the path and url there.
      - `site_id` string, uuid, required
      - `name` string, required
      - `path` string, required
      - `url` string, required
    - `source` 'upload' | 'portaal' | 'site' | 'import', required: upload: an upload link; portaal: the portal; site: it was already on a site; import: an import.
    - `access` 'team' | 'public' | 'paid', required: Who can open the file. team: only the project's members and this chat (the default for every file).
    - `title` string, nullable, required: A display name, set with update_media.
    - `description` string, nullable, required: A free description, set with update_media.
    - `tags` string[], required: Tags to filter on, set with update_media.
    - `kind` 'image' | 'video' | 'audio' | 'pdf' | 'font' | 'archive' | 'document' | 'data' | 'other', required: image, video, audio, pdf, font, archive, document, data or other, from the file type.
    - `deleted_at` string, nullable, required: When it went to the trash; null when it is not in the trash. A file stays in the trash for 30 days.
    - `purge_at` string, nullable, required: When the trash deletes it for good. Restore it before then with update_media restore: true.
    - `deleted_from` string, nullable, required: The path it had before it went to the trash; restore puts it back there.
    - `created_at` string, required
    - `updated_at` string, required
  - `folders` object[], required: Every folder in the library with its number of files (empty is /media/ itself).
    - `folder` string, required
    - `files` integer, required
  - `next_cursor` string, nullable, required: Pass it as cursor for the next page; null when there is no more.

## Other responses

- `401`: Unauthorized: unauthorized, missing_api_key, invalid_api_key, api_key_revoked, project_deleted.
- `403`: Forbidden: project_not_enabled, key_mode_mismatch, missing_scope, verification_required.
- `422`: Unprocessable Content: validation_failed.
- `429`: Too Many Requests: rate_limited.
- `500`: Internal Server Error: internal_error.
- `503`: Service Unavailable: service_unavailable.

---

[API](https://skmtc.dev/hypamoon/apis/hypamoon-api.md) · [All operations](https://skmtc.dev/hypamoon/apis/hypamoon-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hypamoon/apis/hypamoon-api/revisions/9f0b90004c06?raw)