---
title: "List media assets"
method: GET
path: "/api/v1/media"
tags: ["Media Library"]
---

# List media assets

`GET /api/v1/media`

Filter, search and paginate the library. Section is a soft filter (omit = All).

## Query parameters

- `kind` 'image' | 'video'
- `section` string, nullable
- `folderId` string, nullable — uuid or 'root'
- `tag` string, nullable
- `usedIn` 'pwa' | 'pwa_template' | 'landing' | 'push_template' | 'push_notification' | 'push_rule' — Consumers that can attach a media asset (usage reverse-links). The ``push_*`` members come from pwapps-push-service via the ``media.usage`` topic — see ``docs/gallery/push-usage-kafka-plan.md``.
- `search` string, nullable — Matches the filename or any of the asset's tags.
- `minWidth` integer, nullable — Hide images narrower than this (picker gate).
- `minHeight` integer, nullable — Hide images shorter than this (picker gate).
- `archived` boolean
- `includeDerived` boolean
- `sort` 'createdAt' | '-createdAt' | 'size' | '-size'
- `page` integer
- `size` integer

## Response `200`

Successful Response

- PagedMediaAsset — Mirrors the fastapi_pagination ``Page`` shape (see PagedPWA).
  - `items` MediaAssetDTO[], required
    - `id` string, uuid, required
    - `kind` 'image' | 'video', required
    - `filename` string, required
    - `url` string, required — Public URL of the original.
    - `contentType` string, nullable — Sniffed content type, not client-declared.
    - `sizeBytes` integer, required
    - `width` integer, nullable
    - `height` integer, nullable
    - `durationMs` integer, nullable — Video duration; null in v1 (no ffmpeg).
    - `lqip` string, nullable — ~20px blurred data-URI for next/image placeholder='blur'.
    - `folderId` string, uuid, nullable — null = library root.
    - `originContext` string, required — Full upload context, e.g. 'pwa.logo' or 'uncategorized'.
    - `section` string, required — Derived from originContext prefix; the picker's default facet.
    - `tags` string[]
    - `isArchived` boolean
    - `sourceAssetId` string, uuid, nullable — Root/source asset for a crop or slice; null for uploads.
    - `sourceOp` object, nullable — Transform provenance, e.g. {'type':'crop','rect':{...}}.
    - `variants` MediaAssetVariantDTO[]
      - `preset` string, required — Derivative name, e.g. 'pwa_logo_192', 'thumb_512'.
      - `url` string, required — Public URL of the variant object.
      - `width` integer, nullable
      - `height` integer, nullable
    - `usages` MediaAssetUsageDTO[]
      - `entityType` string, required — Consumer type: pwa | pwa_template | ...
      - `entityId` string, uuid, required
      - `field` string, required — Field on the consumer: logo | background | screenshot | ...
      - `position` integer, nullable — Ordering within a repeated field (screenshots).
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, nullable
  - `total` integer, required
  - `page` integer, required
  - `size` integer, required
  - `pages` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/pwapps/apis/curie-api.md) · [All operations](https://skmtc.dev/pwapps/apis/curie-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pwapps/curie-api/revisions/b0af9064dfef/schema)