Media API

Media files live in content/media/ and are served publicly at /media/<name>. The endpoints need the media permission for the action named (read, create, update, delete).

GET /api/media

Requires Bearer token + media read permission.

Every file in the library, newest first.

// Response 200
[ { "name": "hero.jpg", "url": "/media/hero.jpg", "size": 204800, "createdAt": "2026-09-27T10:30:00.000Z" } ]

POST /api/media

Requires Bearer token + media create permission. Content-Type: multipart/form-data.

Upload one or more files. Names are made safe and may be at most 200 characters. Images (JPEG, PNG, GIF, WebP, SVG, ICO, BMP, TIFF), PDF, text, CSV, Word and Excel documents, video and audio are accepted; anything else is refused with 400. The size limit is uploads.maxFileSize in config/server.json (10 MB by default). One file answers with an object, several with an array.

// Response 201 (one file)
{ "name": "photo.jpg", "url": "/media/photo.jpg" }
// Error 400
{ "error": "File type 'application/zip' is not allowed. Allowed types: images, documents, audio, video." }

PATCH /api/media/:name

Requires Bearer token + media update permission.

Rename a file. Pages that link to the old name are not changed. Answers 409 if the new name is taken.

// Request body
{ "newName": "new-photo.jpg" }
// Response 200
{ "name": "new-photo.jpg", "url": "/media/new-photo.jpg" }

DELETE /api/media/:name

Requires Bearer token + media delete permission.

Delete a file.

// Response 200
{ "success": true }
// Error 404
{ "error": "File not found" }

GET /api/media/:name/info

Requires Bearer token + media read permission.

An image's size and format. Only for images that can be edited (JPEG, PNG, WebP, GIF, TIFF); others answer 400.

// Response 200
{ "width": 1920, "height": 1080, "format": "jpeg" }

POST /api/media/:name/transform

Requires Bearer token + media update permission.

Edit an image - the Media screen's image editor - and save it over the original or as a new file.

Field	Type	Description
operations	object	Any of rotate, flip, flop, crop, resize, preset, adjustments, watermark, border, format
saveAs	string	Optional. New file name; left out, the original is overwritten

// Request body
{ "operations": { "resize": { "width": 800, "height": 600 }, "format": "webp" }, "saveAs": "hero-800.webp" }
// Response 200
{ "name": "hero-800.webp", "url": "/media/hero-800.webp", "width": 800, "height": 600 }