Skip to content

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.

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.

Terminal window
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.

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.

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:

lib/media-url.ts
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.

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.

Terminal window
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.

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" }
}
}
  • alt and caption belong to this use of the image, so the same asset can have different alt text on different entries.
  • variants appears 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} for original_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.

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 404 until 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.
components/ArticleCard.tsx
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>
);
}

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.

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:
Terminal window
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 holding content:media:read returns signed URLs and url_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 404 for private assets.
  • Entry reads do not sign URLs. A private image in an entry has a variants map whose URLs return 404. 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.

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.

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.