Media

List Page Media

{"data": [{"filename": "photo.jpg", "url": "/user/pages/01.blog/photo.jpg", "type": "image/jpeg", "size": 245000, "alt": "Sunset over the bay", "dimensions": {"width": 1920, "height": 1080}, "thumbnail_url": "/api/v1/thumbnails/3f2a9c1e4b5d6a7f8e9d0c1b2a394857.jpg", "modified": "2026-09-01T10:15:00+00:00"}]}

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, an invalid sort field, or more than 10 filter clauses returns 422. 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

{"data": [{"filename": "photo.jpg", "url": "/user/pages/01.blog/photo.jpg", "type": "image/jpeg", "size": 245000, "dimensions": {"width": 1920, "height": 1080}, "thumbnail_url": "/api/v1/thumbnails/3f2a9c1e4b5d6a7f8e9d0c1b2a394857.jpg", "modified": "2026-09-01T10:15:00+00:00"}]}

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

The response lists all of the page's media after the upload, not only the new files, and the Location header points at the page's media collection. Each file is capped at 64 MB. A file must have an extension, and no dot-separated part of its name may be on security.uploads_dangerous_extensions (so shell.php.jpg is refused). SVG content is sanitized when it arrives.

The optional random_name, avoid_overwriting, accept and filesize form fields apply a blueprint file field's upload settings on top of those checks.

Delete Page Media

Removes the file and its .meta.yaml sidecar, if present. Retina variants of the file ([email protected], [email protected], and so on) and their sidecars are removed too, so an image stored only as a retina variant can still be deleted by its base name.

List Site Media

{"data": [{"filename": "hero.jpg", "path": "blog", "url": "/user/media/blog/hero.jpg", "type": "image/jpeg", "size": 184320, "dimensions": {"width": 1600, "height": 900}, "thumbnail_url": "/api/v1/thumbnails/3f2a9c1e4b5d6a7f8e9d0c1b2a394857.jpg", "modified": "2026-09-01T10:15:00+00:00"}], "meta": {"pagination": {"page": 1, "per_page": 20, "total": 1, "total_pages": 1}, "path": "blog", "folders": [{"name": "2026", "path": "blog/2026", "children_count": 0, "file_count": 4}], "ordered": false}, "links": {"self": "/api/v1/media?page=1&per_page=20"}}

Returns media files and folders from the user/media directory. Supports browsing subfolders via the path parameter, recursive search via search, filtering by file type via type, and filtering and sorting by .meta.yaml metadata via filter, sort and order (see List Page Media for the filter syntax). The response includes a folders array in the meta object listing immediate subdirectories at the current path, and meta.ordered says whether the folder has a saved manual order.

Files follow the folder's saved manual order (see Set Media Order) when one exists, otherwise natural filename order. .meta.yaml sidecars and the media_order.yaml order file are never listed, in a folder listing or in search results.

A folder that does not exist returns an empty list, with meta.pagination echoing the requested page and per_page and no meta.ordered. In search mode, meta.path is empty, meta.folders is empty, meta.search holds the search term, and meta.ordered is absent.

Upload Site Media

{"data": [{"filename": "hero.jpg", "path": "blog", "url": "/user/media/blog/hero.jpg", "type": "image/jpeg", "size": 184320, "dimensions": {"width": 1600, "height": 900}, "thumbnail_url": "/api/v1/thumbnails/3f2a9c1e4b5d6a7f8e9d0c1b2a394857.jpg", "modified": "2026-09-01T10:15:00+00:00"}]}

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.

The response lists only the files saved by this request. A file must have an extension, and no dot-separated part of its name may be on security.uploads_dangerous_extensions. SVG content is sanitized when it arrives. Without avoid_overwriting, a file with the same name is replaced. A 422 stops the request at that file, and files saved before it are kept.

Delete Site Media

Remove a file and its .meta.yaml sidecar (if present) from the user/media directory, and drop it from the folder's manual order. The filename parameter supports subfolder paths.

Create Media Folder

{
  "path": "blog/2026"
}

{"data": {"name": "2026", "path": "blog/2026", "children_count": 0, "file_count": 0}}

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. No path segment may start with a period or be ... The Location header points at the new folder's listing (/media?path=...).

Delete Media Folder

Remove an empty folder from the user/media directory. The folder must contain no files or subdirectories, and that includes hidden files, .meta.yaml sidecars and a media_order.yaml order file.

Rename Site Media

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

{"data": {"filename": "banner.jpg", "path": "blog", "url": "/user/media/blog/banner.jpg", "type": "image/jpeg", "size": 184320, "dimensions": {"width": 1600, "height": 900}, "thumbnail_url": "/api/v1/thumbnails/3f2a9c1e4b5d6a7f8e9d0c1b2a394857.jpg", "modified": "2026-09-01T10:15:00+00:00"}}

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, and the folders' manual orders are kept in step. The response is the file at its new location.

The new name is cleaned before it is used: whitespace becomes a dash, characters other than letters, digits, ., _ and - are dropped, and the source file's extension is always kept (any extension given in to is replaced). So {"from": "hero.jpg", "to": "My Banner.png"} produces My-Banner.jpg. If the cleaned name is the same as the source, nothing changes and the file is returned as it is. A cleaned name with no letters or digits left returns 422.

Rename Media Folder

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

{"data": {"name": "new-name", "path": "blog/new-name", "children_count": 2, "file_count": 14}}

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.

The response carries the renamed folder's real children_count (subfolders) and file_count (media files, not counting sidecars or the order file), the same counts the folder listing reports, so a client can update the entry without fetching the listing again.

Serve Thumbnail

Thumbnails are stored in cache://api/thumbnails/. They are generated when an image is serialized in a media response, never by this endpoint, so a thumbnail that is not cached yet (for example after a cache clear) returns 404 until the media listing that contains it is fetched again.

Get Page Media Metadata

{"data": {"filename": "photo.jpg", "has_meta": true, "fields": [{"key": "alt", "label": "Alt Text", "type": "text", "value": "Sunset over the bay"}, {"key": "title", "label": "Title", "type": "text", "value": ""}, {"key": "caption", "label": "Caption", "type": "textarea", "value": ""}, {"key": "description", "label": "Description", "type": "textarea", "value": ""}, {"key": "tags", "label": "Tags", "type": "tags", "value": ["beach", "summer"]}], "extra": {"width": 1920, "height": 1080}}}

Returns one entry in fields for each editable field configured under Plugins → API → Media Metadata (plugins.api.media_metadata.fields), with its current value. When nothing is configured, the defaults are alt, title, caption, description and tags. A text or textarea field's value is a string (empty when unset), and a tags field's value is a list of strings.

Any other keys stored in the sidecar (EXIF data, dimensions, upload info) are returned as read-only data in extra. has_meta says whether a sidecar file exists at all.

Update Page Media Metadata

{
  "fields": {
    "alt": "Sunset over the bay",
    "tags": ["beach", "summer"]
  }
}

{"data": {"filename": "photo.jpg", "has_meta": true, "fields": [{"key": "alt", "label": "Alt Text", "type": "text", "value": "Sunset over the bay"}, {"key": "title", "label": "Title", "type": "text", "value": ""}, {"key": "caption", "label": "Caption", "type": "textarea", "value": ""}, {"key": "description", "label": "Description", "type": "textarea", "value": ""}, {"key": "tags", "label": "Tags", "type": "tags", "value": ["beach", "summer"]}], "extra": {"width": 1920, "height": 1080}}}

Send the values in a fields object, or as a bare map of field keys to values. Only configured fields present in the request are changed, and an empty value (an empty string, or an empty list for a tags field) removes that field. Keys that aren't configured are ignored, and every other key already in the sidecar is kept. The response is the updated metadata, in the same format as Get Page Media Metadata.

Values render into <img> attributes on the site, so they are cleaned on save: HTML tags and control characters are stripped, single-line fields have their whitespace collapsed, and each value is cut to plugins.api.media_metadata.max_length characters (2000 by default). A tags value may be a list of strings or one comma-separated string; duplicates and blanks are dropped and at most 50 tags are kept. Reserved keys that Grav manages itself (width, height, mime, size, filesize, modified, upload, type) can never be written here.

If every key is removed, the sidecar file is deleted.

Delete Page Media Metadata

Removes every configured metadata field from the file's .meta.yaml sidecar. Other keys, such as EXIF data or dimensions, are kept, and the sidecar file is deleted only when nothing else is left in it. The media file itself is not touched.

Serve Raw Site Media

Media listings normally give each file a direct static URL. When the site media folder sits somewhere the web server refuses to serve, such as a multi-site user/env/<host>/media folder (Grav's shipped .htaccess and nginx configs deny user/env, user/config and user/accounts), the listing's url points here instead.

Only images, video, audio, fonts and PDFs are served. Any other file type returns 404, so this route can't be used to read source or configuration files. The response is sent inline with Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; sandbox and X-Content-Type-Options: nosniff, so an uploaded SVG can't run script when it is opened directly, and with Cache-Control: private, max-age=600.

Because a browser <img> element can't send an auth header, this route accepts the site's own session cookie, and also a JWT passed as a ?token= query parameter.

Get Site Media Metadata

{"data": {"filename": "hero.jpg", "has_meta": true, "fields": [{"key": "alt", "label": "Alt Text", "type": "text", "value": "Sunset over the bay"}, {"key": "title", "label": "Title", "type": "text", "value": ""}, {"key": "caption", "label": "Caption", "type": "textarea", "value": ""}, {"key": "description", "label": "Description", "type": "textarea", "value": ""}, {"key": "tags", "label": "Tags", "type": "tags", "value": ["beach", "summer"]}], "extra": {"width": 1920, "height": 1080}}}

The file is addressed by the path query parameter rather than in the URL, because site media paths contain slashes. The response is the same as for Get Page Media Metadata: one entry per configured field in fields, other sidecar keys in extra, and has_meta saying whether a sidecar exists. filename is the file's base name.

Update Site Media Metadata

{
  "fields": {
    "alt": "Sunset over the bay",
    "tags": ["beach", "summer"]
  }
}

{"data": {"filename": "hero.jpg", "has_meta": true, "fields": [{"key": "alt", "label": "Alt Text", "type": "text", "value": "Sunset over the bay"}, {"key": "title", "label": "Title", "type": "text", "value": ""}, {"key": "caption", "label": "Caption", "type": "textarea", "value": ""}, {"key": "description", "label": "Description", "type": "textarea", "value": ""}, {"key": "tags", "label": "Tags", "type": "tags", "value": ["beach", "summer"]}], "extra": {"width": 1920, "height": 1080}}}

Works the same way as Update Page Media Metadata: only configured fields present in the request change, an empty value removes a field, other sidecar keys are kept, and values are cleaned on save. The response is the updated metadata. To apply the same values to many files in one request, use Batch Update Site Media Metadata.

Delete Site Media Metadata

Removes every configured metadata field from the file's .meta.yaml sidecar. Other keys are kept, and the sidecar file is deleted only when nothing else is left in it. The media file itself is not touched.

Batch Update Site Media Metadata

{
  "files": ["photos/beach.jpg", "photos/dunes.jpg"],
  "fields": {
    "tags": ["beach", "summer"]
  }
}

{"data": {"results": [{"path": "photos/beach.jpg", "status": "success"}, {"path": "photos/missing.jpg", "status": "error", "message": "Media file not found."}], "total": 2, "successful": 1, "failed": 1}}

files lists paths relative to the media root, and fields maps metadata field keys to values. Only the configured fields present in fields are written to each file, so a batch that sets just tags leaves each file's own alt and title alone. An empty value (an empty string, or an empty list for a tags field) removes that field. Values are cleaned the same way as in Update Site Media Metadata.

Each file is handled on its own: a bad path or a missing file is reported in results with status: error and a message, and the rest of the batch still runs. The number of files is capped by plugins.api.batch.max_items (50 by default).

Set Media Order

{
  "path": "photos",
  "order": ["dunes.jpg", "beach.jpg", "sunset.jpg"]
}

path is the folder relative to the media root; leave it out for the root folder. order lists filenames in the order you want. Entries are reduced to base filenames, and blanks are dropped. An empty order removes the saved order.

The order is stored in a media_order.yaml file inside the folder, and List Site Media applies it when listing that folder. Files that aren't in the saved order (new uploads, for example) follow the ordered ones. The order file itself never appears in listings or search results, and it is kept up to date when a file is deleted, renamed or moved.

Blueprint File Upload

{"data": [{"name": "logo.png", "path": "user/themes/quark/images/logo/logo.png", "size": 20480, "type": "image/png", "url": "https://example.com/user/themes/quark/images/logo/logo.png"}]}

This mirrors classic admin's taskFilesUpload and is what Admin2 uses for blueprint file fields that set a destination. Send it as multipart/form-data. Absolute paths and .. segments in destination are rejected.

The response lists each saved file. path is the logical path under user/, built from destination and scope rather than the resolved disk path, so it still works through symlinked theme or plugin folders. Pass it to Delete Blueprint File to remove the file.

File rules:

• Each file is capped at 64 MB, and the field's own filesize can only lower that.
• No dot-separated part of the name may be on security.uploads_dangerous_extensions, so shell.php.jpg is refused.
• Config and data files (yaml, yml, json, twig, env, neon, lock) are refused wherever they would land. Page content (md, markdown) and stylesheets (css, scss, sass, less) are refused too, unless the field named in field allows them with allow_extensions in the blueprint that owns scope and the upload goes to that field's own destination.
• Uploads into user/accounts/ may only be images (jpg, jpeg, png, gif, webp, svg, avif, bmp, ico), since Grav reads that folder as its account store.
• Uploads that resolve into user/config/ or user/env/*/config/ are refused with 403.
• SVG files are sanitized after saving.

A self@: destination with a users/<username> scope for your own account needs only api.media.write. For another account it also needs api.users.write (or super user).