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, a product form, 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, a progress line counts Uploading 3/8…, and the files land in the folder you are standing in.

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

One exception: lecture videos and materials in the Courses app do not go through this library and are not bound by the 25 MiB limit — they live on an external file host, never appear here and never count against storage. See Courses app.

If a batch fails 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:

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

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

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 destroys the file, and before it does, the dialog checks where the file is used — products, variants, categories, articles, blog categories, draft and published pages, global sections, the cart drawer, section templates, themes, form submissions — and lists each place under Still used in N places. Three outcomes follow:

• Nothing uses it → deleted.
• Used by products, articles, categories… → confirm, and the system removes the image from those places first, then deletes the file. If a removal sticks part-way it stops and says so: "The file was NOT deleted."
• Placed on a page (draft or published, a global section, the cart drawer) → refused: "Open the page, remove the image there, then delete the file." Pages are your design; nothing rewrites a layout from the library.

If the check itself fails, deletion is refused too — "deleting it may break a page". "Could not tell" is never allowed to be a cheaper route than "yes, it is in use".

That is also why the public API has no permanent delete: DELETE /api/v1/media only trashes. The purge stays in the app, behind the check above.

Folders

File things into Folders. 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. Largest is the quickest way to find whatever is eating your quota.

A file's details

View details shows Format, Size, Dimensions, Uploaded, Folder, Link (with Copy link and Open original) and Used by — the same list of places the delete dialog reads.

The link is a full URL, and it is the one field here you should not hard-code elsewhere. The front of the URL is storage configuration composed at read time — which is what lets the CDN move without rewriting data. Read it again when you need it.

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.

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.