parsshop-back/docs/media-library-api.md

Media Library API

Base URL: /api

All media endpoints are admin-only and require:

• Bearer token
• Admin role
• media.manage permission

Library Sections

• image
• gallery
• audio
• video
• model3d
• document

Media Asset Model

• id
• section
• folder
• originalName
• objectName
• url
• bucket
• mimeType
• extension
• size
• title
• alt
• caption
• metadata
• isPublic
• createdAt
• updatedAt

Endpoints

GET /api/admin/media/overview

Returns grouped counts by section and folder.

GET /api/admin/media

Query params:

• section
• folder
• search
• page
• limit

Use this endpoint to power a WordPress-like media browser.

POST /api/admin/media/upload

Content type: multipart/form-data

Fields:

• files one or many files
• section optional
• folder optional, default root
• title optional
• alt optional
• caption optional
• metadata optional JSON string
• isPublic optional

Behavior:

• if section is sent, file is stored in that section
• if section is omitted, backend infers it from mime type / extension
• files are stored in object storage under media/<section>/<folder>/...

GET /api/admin/media/:id

Returns one media asset.

PATCH /api/admin/media/:id

Updates metadata:

• section
• folder
• title
• alt
• caption
• metadata
• isPublic

DELETE /api/admin/media/:id

Deletes DB record and object-storage file.

Category Image

Category now supports:

• imageUrl

POST /api/categories

Admin-only for create.

Content type: multipart/form-data

Fields:

• name
• slug
• type
• parentId
• existingImageUrl
• image file

PATCH /api/categories/:id

Admin-only for update.

Content type: multipart/form-data

Fields:

• name
• slug
• type
• parentId
• existingImageUrl
• image file

Rules:

• if image is uploaded, it replaces the old image
• if existingImageUrl is sent, category uses that media URL
• if existingImageUrl is sent as empty value, category image is cleared

Integration Pattern

Recommended admin flow:

1. Open media library with GET /api/admin/media
2. User either selects an existing asset or uploads a new one with POST /api/admin/media/upload
3. Frontend takes selected asset url
4. That url is sent into product/category create-update payload as existing media URL

This keeps product and category APIs simple while still supporting a professional reusable media library.