The media library

The Media library is a site's shared file store: every image, video and font you have uploaded. You reach it from anywhere a file is picked — in the editor, in a product form, in an article — or press Browse all media for the full screen.

Uploading

Drag files in: "Drop files here to upload." Several at once is fine, and a progress line counts Uploading 3/8….

Four kinds are supported and filterable from the top bar: Images, Videos, Fonts, Other. Fonts take woff2, woff, ttf, otf. The limit is 25 MiB per file.

If a batch runs into trouble part-way, the message says how many landed, which file failed and why — rather than silently skipping the rest.

Storage — the part that surprises everyone

The quota bar reads {used} of {limit} used, with a line worth reading properly:

"Includes trashed files — only permanent deletion frees space."

This is the most confusing thing here: trashing a file frees no storage. You delete 500 MB of images, the bar does not move, and you assume something is broken. Nothing is — they are sitting in the trash.

When you run out, the message gives all three numbers: "Not enough storage: this file is {incoming}, and {used} of {limit} is already used." The refusal happens before anything is stored, so it costs the store no space at all.

The trash, and permanent deletion

Deleting a file moves it to the trash — recoverable. The Trash tab lists them, each with Restore and Delete permanently.

Delete permanently is the one that actually destroys the file, and the dialog is blunt about the consequence:

"“{name}” ({size}) will be removed for good and its storage freed. Pages still using it will show a broken image. This cannot be undone."

Read the middle sentence carefully. Nothing counts who uses which file, so nothing stops you deleting one a live page is still serving. It can only tell you that this might happen and let you decide.

That is also why the public API has no permanent delete: DELETE /api/v1/media only trashes. An API that could hard-delete would be an API that can put a hole in a live storefront from a script, with no screen in a position to warn anyone. The permanent purge stays in the app, next to the dialog quoted above.

Folders

File things into Folders to find them again. A few purpose-built ones exist — Products, Blog, Categories, Blog categories — alongside All media and Unfiled.

New folder adds your own. Deleting a folder does not delete the files in it.

Finding a file

The search box filters by name. There is also a type filter and Sort: newest, oldest, name A→Z, largest, smallest.

Sorting by Largest first is the quickest way to find whatever is eating your quota.

A file's details

View details shows Format, Size, Dimensions, Uploaded, Folder and Link, with Copy link and Open original.

The link is a full URL, and it is the one field here you should not cache forever. The front of the URL is storage configuration composed at read time — which is exactly what lets the CDN move without rewriting any data. Read it again when you need it rather than hard-coding it somewhere else.

On saving a product, it sometimes asks about leftovers

Remove images from a product and save, and if those files are no longer used anywhere, a dialog asks "Delete unused files?" naming each one.

It asks rather than acting. Deleting something you still need is your decision, not the system's default.

Through the API

GET, POST (multipart), PATCH, DELETE on /api/v1/media, plus POST /api/v1/media/{id}/restore and /api/v1/media-folders. The upload is the only request on that surface that is not JSON. See The public API.