Media Library
The Media Library holds every file your content uses: images, video, audio, PDFs, and other documents. Entries point at assets through image and file fields, and the Page Builder’s media blocks use the same library. The library is shared by all sites on an instance, and every asset is served from a stable URL on your instance, whichever storage backend holds it.
Upload files
Section titled “Upload files”In the console, open Media Library and select Upload, or drop files onto the library. Each upload shows its progress, then becomes a tile once stored. If you are browsing a folder, uploads go into it.
With the API, send a multipart/form-data request to POST /api/v1/media. It needs a signed-in user or a private API key with content:media:create.
curl -X POST "https://your-instance.plenarycms.io/api/v1/media" \ -H "X-API-KEY: $PLENARY_API_KEY" \ -F "upload_file=@./cover.jpg" \ -F "folder_id=0d864fac-0ac5-4e1b-bcaa-10d3a99ef9b0"| Form field | Required | Meaning |
|---|---|---|
upload_file |
yes | The file. |
folder_id |
no | Media folder to file it in. Omit for the library root. |
visibility |
no | public (default) or private. See Private assets. |
The response is the new asset:
{ "media_id": "17992148-aa28-4ebc-b582-643b58513f5f", "media_type": "image", "mime_type": "image/webp", "file_name": "mstoneback.webp", "file_size": 6628, "caption": "", "description": "", "created_at": "2026-07-27T14:05:38Z", "folder_id": "0d864fac-0ac5-4e1b-bcaa-10d3a99ef9b0", "path": "/staff", "visibility": "public", "original_url": "/media/17992148-aa28-4ebc-b582-643b58513f5f/original.webp", "thumb_status": "ready", "thumb_url": "/media/17992148-aa28-4ebc-b582-643b58513f5f/ui-thumb.webp"}The file type is detected from the file’s contents, not its name, and sets media_type:
media_type |
Files |
|---|---|
image |
JPEG, PNG, GIF, WebP, AVIF, TIFF, BMP, SVG |
video |
MP4, WebM, Ogg video, and other video/* |
audio |
audio/* |
document |
PDF, Word, Excel, PowerPoint, OpenDocument |
archive |
ZIP, tar, gzip, bzip2, 7z, RAR |
text |
text/* |
binary |
Anything else |
Images and videos get a small ui-thumb preview for the console, generated in the background. thumb_url appears once it is ready. Video thumbnails are a poster frame from the video.
Asset details
Section titled “Asset details”GET /api/v1/media/{media_id} returns the asset with its dimensions and every generated variant:
{ "media_id": "17992148-aa28-4ebc-b582-643b58513f5f", "media_type": "image", "original_url": "/media/17992148-aa28-4ebc-b582-643b58513f5f/original.webp", "visibility": "public", "width": 256, "height": 342, "aspect_ratio": 0.748538, "variants": { "622a5ace95c45761": { "status": "ready", "url": "/media/17992148-aa28-4ebc-b582-643b58513f5f/622a5ace95c45761.webp", "width": 300, "height": 300, "format": "webp", "quality": 0.9, "crop": true } }}A public API key can call this endpoint for public assets, which is how a site looks up an original’s URL. Listing the library (GET /api/v1/media) needs content:media:read. It accepts media_type, search (file name and caption), path_prefix (a folder and everything beneath it), sort (created_at, file_name, file_size, media_type, caption), limit (1 to 100, default 20), page (zero-based), and count. It returns a JSON array of assets. With count=true, the response also carries an X-Total-Count header with the number of assets matching the filters, across all pages.
To change an asset’s caption or description, use PUT /api/v1/media/{media_id} with { "caption": "…", "description": "…" }. The file itself cannot be replaced; upload a new asset instead.
Media URLs
Section titled “Media URLs”Every file is served at /media/{media_id}/{filename} on your instance: the original as original.<ext>, and each variant under its own name. URLs in API responses are paths. Prefix them with your instance’s origin:
export function mediaUrl(path: string): string { return new URL(path, process.env.PLENARY_BASE_URL).toString();}These URLs do not depend on where the file is stored, and moving an asset between folders does not change them. Public media is served without authentication. With S3 storage, the instance answers with a 302 redirect to the bucket or CDN.
Folders
Section titled “Folders”Each site has its own folder tree, alongside its own assets. In the console, use the folder panel to create, rename, and nest folders, and drag assets into them or select assets and move them.
Through the API:
| Method | Path | Permission | Body |
|---|---|---|---|
GET |
/api/v1/media/folders |
content:media:read |
|
POST |
/api/v1/media/folders |
content:media:update |
name, slug, optional parent_id, sort_order, site_key |
PUT |
/api/v1/media/folders/{id} |
content:media:update |
name, slug, parent_id, optional sort_order |
DELETE |
/api/v1/media/folders/{id} |
content:media:update (plus content:media:delete with ?purge_files=true) |
|
POST |
/api/v1/media/move |
content:media:update |
media_ids (array), folder_id |
name and slug are required on both POST and PUT. A slug is lowercase letters and digits in hyphen-separated groups (press-kit, 2026), unique among its siblings; a missing one is 422 media_folder_slug_required, a malformed one 422 media_folder_slug_invalid_format, and a sibling clash 409 media_folder_slug_taken. parent_id is the parent folder’s id, or null (or absent) for the top level. A new folder goes on the site that site_key names, else ?site_key=, else a site-bound API key’s own site.
PUT replaces the folder’s name, slug, and parent all at once, so send the current parent_id to rename a folder in place: leaving it out moves the folder to the top level. sort_order is kept when omitted.
curl -X POST "https://your-instance.plenarycms.io/api/v1/media/folders" \ -H "X-API-KEY: $PLENARY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "site_key": "default", "name": "Press kit", "slug": "press-kit" }'{ "id": "0b9d6f43-5d0e-4a51-9a3c-2f1f6a7e9c11", "site_key": "default", "parent_id": null, "name": "Press kit", "slug": "press-kit", "path": "/press-kit", "sort_order": 0, "created_at": "2026-10-24T09:18:00.260Z", "updated_at": "2026-10-24T09:18:00.260Z"}GET returns { "folders": [...], "media_count": n }, with a media_count on each folder counting the assets in it and everything beneath it.
Deleting a folder moves its subfolders and assets up to its parent. With ?purge_files=true (in the console, Also delete the files in this folder) the folder’s whole subtree and every asset in it are permanently deleted.
Use media in entries
Section titled “Use media in entries”An image or file field stores a pointer to an asset, not a copy:
"cover": { "media_id": "17992148-aa28-4ebc-b582-643b58513f5f", "alt": "Dn. Mary Stoneback", "caption": "Dn. Mary Stoneback", "focal_point": { "x": 0.4885, "y": 0.3572 }, "variants": { "thumbnail": { "url": "/media/17992148-aa28-4ebc-b582-643b58513f5f/622a5ace95c45761.webp" } }}altandcaptionbelong to this use of the image, so the same asset can have different alt text on different entries.variantsappears on reads when the field declares variants. Each key is a variant name from the field’s settings.- The entry does not carry the original’s URL. Use a variant, or fetch
GET /api/v1/media/{media_id}fororiginal_url.
Use file fields for video, audio, and documents. Render a video with its original_url and, if you want a poster, its thumb_url.
Image variants
Section titled “Image variants”Variants are resized, cropped, and re-encoded copies of an image, defined on the image field so every entry gets the same sizes. Add them in the field’s Settings tab under Image variants, or in the field’s settings.variants:
"settings": { "focal_point": true, "variants": [ { "key": "card", "width": 800, "height": 450, "crop": true }, { "key": "hero", "width": 1600, "format": "jpeg", "quality": 0.8 } ]}| Key | Meaning |
|---|---|
key |
Name used in the entry’s variants map. |
width, height |
Target size in pixels. At least one is required. |
crop |
With both sizes: fill the box exactly and crop the overflow. Without it, the image is scaled to fit inside the box. |
format |
webp (default), jpeg, or png. |
quality |
0 to 1. |
How variants are produced:
- Saving an entry queues the variants for its image. They are generated in the background, usually within seconds.
- A variant URL is returned straight away and returns
404until the file exists. Fall back to the original if you render immediately after a save. - Variants are shared: the same image with the same spec is generated once, even across entries and Page Builder image blocks.
- Images are never scaled up.
type ImageValue = { media_id: string; alt?: string; variants?: Record<string, { url: string }>;};
export function ArticleCard({ title, cover }: { title: string; cover?: ImageValue }) { const src = cover?.variants?.card?.url; return ( <article> {src ? ( <img src={new URL(src, process.env.NEXT_PUBLIC_PLENARY_BASE_URL).toString()} alt={cover?.alt ?? ""} /> ) : null} <h2>{title}</h2> </article> );}Focal point
Section titled “Focal point”With Focal point on for an image field, editors click the part of the image that must stay in frame, such as a face. The point is stored on the entry’s value as focal_point: { x, y }, fractions of the width and height from the top-left corner.
Cropping variants (crop: true with both width and height) center their crop on the focal point instead of the middle of the image. Changing the focal point produces new crops under new URLs, so cached old crops never show the wrong framing. Variants that only resize are unaffected.
Private assets
Section titled “Private assets”An asset can be private: its files are kept in a separate storage location that is never served directly, and can only be read through a signed URL that expires after one hour.
- Make assets private with Make private in the library, by uploading with
visibility=private, or with the API:
curl -X POST "https://your-instance.plenarycms.io/api/v1/media/visibility" \ -H "X-API-KEY: $PLENARY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "media_ids": ["17992148-aa28-4ebc-b582-643b58513f5f"], "visibility": "private" }'- An unsigned request for a private file returns
404, the same as a file that does not exist. GET /api/v1/media/{media_id}with a key holdingcontent:media:readreturns signed URLs andurl_expires_at. One signature covers the original and all variants. Request a fresh one when it expires; do not store signed URLs.- Public API keys get
404for private assets. - Entry reads do not sign URLs. A private image in an entry has a
variantsmap whose URLs return404. Your server should authorize the visitor, then fetch a signed URL from the media API.
Plenary decides that an asset is not public. Your application decides which visitor may see it.
Making an asset private moves its files, so links already published stop working.
Storage backends
Section titled “Storage backends”Self-hosted instances choose where files are stored under Admin Settings → Global Settings → File Storage:
| Backend | Configuration |
|---|---|
local |
Files on the server’s disk, under storage.local_data_dir from plenary.yaml. The default. |
s3 |
Access key and secret, region, bucket, key prefix, and the public base URL the bucket or CDN serves from. |
- Switching backends changes where new uploads go. Existing files stay where they are and keep their URLs. Copying existing files between backends is not built in.
- With S3, the public files must be readable from the bucket or a CDN in front of it. Private files are stored under
{prefix}private/, and your bucket policy must not allow public reads of that prefix.
On Plenary Cloud, storage is managed for you.
Delete media
Section titled “Delete media”Deleting an asset permanently removes its original and variants. In the console, select Delete; through the API, DELETE /api/v1/media/{media_id} (needs content:media:delete).
Entries that use the asset are not changed: their fields keep the media_id, and its URLs return 404. The entry editor marks those fields Media not found so editors can pick a replacement. Check for references before deleting assets your live site uses.
Related
Section titled “Related”- Field Types:
imageandfilevalue shapes and settings. - Page Builder: media blocks and their one-off variants.
- Settings: storage and other instance settings.
- Permissions:
content:media:*capabilities.