Images and files

An asset is a file in your site: a photo, a logo, a PDF, a short video. You upload it once and use it in any entry.

Upload

In your site, go to Files → Upload. You can upload several at once.

• Images: JPG, PNG, WebP, GIF and SVG. Documents: PDF. Up to 20 MB.
• Video: MP4 and WebM, up to 50 MB. For long videos, it's better to use YouTube or Vimeo and store the link in a text field.
• Over the API you can also upload from a URL, and many at once with a batch.

Each file has:

A file has no draft: as soon as it's uploaded, it can be used. What gets published is the entry that uses it.

SVG

An SVG is code, not just an image: it can carry scripts or load things from another site. Pluma accepts SVGs that are drawing only, and rejects, saying why, the ones that contain:

• <script>, <foreignObject>, <iframe>, <embed> or <object>;
• attributes that run code (onload, onclick…) or javascript:;
• links or CSS that load something from outside (href to another site, @import, url(https://…)). Internal links (#id) and base64-embedded images are fine;
• XML entities (<!ENTITY>).

Nothing is cleaned up silently: if your SVG doesn't pass, export it again as "optimized SVG" (in Figma or Illustrator) or run it through SVGO. On top of that, Pluma serves it with a policy that doesn't let anything run even if something slips through.

Use it in an entry

• asset or assets field: in the entry form you pick the image from the grid.
• Inside a rich text: write ![alt text](asset:ID) in its own paragraph. The ID is on the file's page. It is stored as an image block that points to the asset; see Rich text.

Publishing checks that each file used exists and, if it's an image, has alt text.

A file's URL

fields.file.url in the API looks like https://pluma.so/files/acton-estero/4-k3x9q2m7ab/playground.jpg: your site, the file's id with a short random key, and its name.

• It doesn't change while the file stays the same, and it's served with a cache that never expires. If you replace the file, the URL changes, so no cache shows the old one: read it again from the API.
• The domain is pluma.so (until October 1, 2026 it was pluma.fly.dev, which still serves the same files). If your framework only optimizes images from allowed domains (Astro image.domains, Next images.remotePatterns), allow both. See the Astro recipe.
• The random key makes it impossible to guess: nobody finds an unpublished photo by trying ids.
• In your site build you can use it directly, or download the files and serve them yourself from your usual paths (that's what the Astro recipe does).

With a delivery key you only see the files used by something published in an asset/assets field or inside a rich text. A file id stored inside a json field doesn't count: if an image is used, put it in an asset field.

Metadata

Photos carry hidden data: the camera, the date and often the GPS position where they were taken. File URLs are public, so Pluma removes that data from JPG, PNG and WebP images before storing them.

• The photo looks the same: if the camera stored it sideways with a rotation flag, Pluma rotates the pixels first. Width and height are the ones you see.
• The color profile stays, so colors don't change.
• An image with no metadata is stored exactly as you uploaded it. One with metadata is saved again at high quality.
• GIF, SVG, PDF and video are stored as they are.

If you need a photo's EXIF (the date it was taken, for example), save it in a field of the entry.

Delete

A file used by any entry can't be deleted: Pluma tells you which entries use it. Remove it from those entries first.

Where they are stored

Today, on the disk of Pluma's machine, with a daily backup. When Cloudflare R2 storage is ready (no egress fees), files will be served from there and behind a CDN; the API URLs won't change shape.

Possible errors