Media
Endpoints for managing media files attached to pages and site-level media.
Endpoints for managing media files attached to pages and site-level media.
List Page Media
/pages/{route}/media
Parameters
| Name | Type | Description |
|---|---|---|
| route required | string | The page route |
{"data": [{"filename": "photo.jpg", "url": "/user/pages/blog/photo.jpg", "type": "image/jpeg", "size": 245000}]}
Response Codes
Upload Page Media
/pages/{route}/media
Parameters
| Name | Type | Description |
|---|---|---|
| route required | string | The page route |
| file required | file | File to upload (multipart/form-data) |
Response Codes
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
/pages/{route}/media/{filename}
Parameters
| Name | Type | Description |
|---|---|---|
| route required | string | The page route |
| filename required | string | The media filename to delete |
Response Codes
List Site Media
/media
Parameters
| Name | Type | Description |
|---|---|---|
| page optional | integer | Page number for pagination (default: 1) |
| per_page optional | integer | Number of results per page (default: 20, max: 100) |
| path optional | string | Subfolder path relative to the media root directory |
| search optional | string | Recursive filename search across all subfolders |
| type optional | string | Filter by media type: image, video, audio, or document |
Response Codes
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
/media
Parameters
| Name | Type | Description |
|---|---|---|
| path optional | string | Subfolder path to upload into (created automatically if it does not exist) |
Response Codes
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
/media/{filename}
Parameters
| Name | Type | Description |
|---|---|---|
| filename required | string | The media filename to delete. May include a subfolder path (e.g. blog/hero.jpg). |
Response Codes
Remove a file and its .meta.yaml sidecar (if present) from the user/media directory. The filename parameter supports subfolder paths.
Create Media Folder
/media/folders
{
"path": "blog/2026"
}
Response Codes
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
/media/folders/{path}
Parameters
| Name | Type | Description |
|---|---|---|
| path required | string | Folder path relative to the media root |
Response Codes
Remove an empty folder from the user/media directory. The folder must contain no files or subdirectories.
Rename Site Media
/media/rename
{
"from": "blog/hero.jpg",
"to": "blog/banner.jpg"
}
Response Codes
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
/media/folders/rename
{
"from": "blog/old-name",
"to": "blog/new-name"
}
Response Codes
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.
Serve Thumbnail
/thumbnails/{file}
Parameters
| Name | Type | Description |
|---|---|---|
| file required | string | Thumbnail filename (basename only). |
Response Codes
Thumbnails are stored in cache://api/thumbnails/. They are generated lazily when a media item is serialized with a requested thumbnail size, so cold paths will return 404 until the parent media is fetched for the first time.