Media

List Page Media

{"data": [{"filename": "photo.jpg", "url": "/user/pages/blog/photo.jpg", "type": "image/jpeg", "size": 245000}]}

Filtering and sorting by metadata

When your media carry metadata via .meta.yaml sidecars, you can filter and sort the listing by those values instead of pulling the whole set. This mirrors the Twig collection query methods but is bound to the metadata schema configured under Plugins → API → Media Metadata (plugins.api.media_metadata.fields).

Filter

Each filter clause is field:operator:value. Repeat it with filter[]= to apply several (they are ANDed):

GET /pages/blog/media?filter=rating:>=:3&filter[]=tags:contains:sunset

Available operators are ==, !=, >, >=, <, <=, in, and contains. You can also omit the operator (filter=copyright:Jane Doe), in which case it is inferred from the field type — contains for a tags field, == otherwise. For the in operator, give a comma-separated set: filter=rating:in:4,5.

Sort

GET /pages/blog/media?sort=rating&order=desc

sort accepts any configured metadata field plus the intrinsic filename, size, and modified keys. order is asc (default) or desc; media missing the sorted field always sort last. (dir is accepted as an alias for order.)

Rules and limits

• Schema-bound. Only fields defined in media_metadata.fields are filterable and sortable; unknown fields are ignored. A tags field accepts only in/contains.
• Validation. An unknown operator, a malformed clause, or an invalid sort field returns 400. Filtering rides the existing api.media.read permission and exposes no metadata values the caller could not already read.
• Cap. At most 10 filter clauses per request.

Upload Page Media

Send the file as a multipart/form-data request rather than JSON. The Content-Type header should be set to multipart/form-data.

Delete Page Media

List Site Media

Returns media files and folders from the user/media directory. Supports browsing subfolders via the path parameter, recursive search via search, and filtering by file type via type. The response includes a folders array in the meta object listing immediate subdirectories at the current path.

Upload Site Media

Upload one or more files to the user/media directory. Use the path query parameter to upload into a subfolder. The request body should use multipart/form-data with a file field. Maximum upload size per file is 64 MB.

Delete Site Media

Remove a file and its .meta.yaml sidecar (if present) from the user/media directory. The filename parameter supports subfolder paths.

Create Media Folder

{
  "path": "blog/2026"
}

Create a new folder in the user/media directory. Parent directories are created automatically. The request body must include a path property with the relative folder path to create.

Delete Media Folder

Remove an empty folder from the user/media directory. The folder must contain no files or subdirectories.

Rename Site Media

{
  "from": "blog/hero.jpg",
  "to": "blog/banner.jpg"
}

Rename a file or move it to a different folder within user/media. Both from and to are relative paths. The destination directory is created automatically if needed. Any .meta.yaml sidecar file is also moved.

Rename Media Folder

{
  "from": "blog/old-name",
  "to": "blog/new-name"
}

Rename a folder within the user/media directory. All contents of the folder are preserved. Both from and to are relative paths from the media root.