Plugin for handling media library (dirs/files manipulation) through api in Strapi
npm install strapi-plugin-media-library-handler> Plugin for handling media library (dirs/files manipulation) through api in Strapi.
---
[![npm-url][npm-url-svg]][npm-url]
- Manage folders and files through API.
- Easy integration with Strapi projects.
bash
npm i strapi-plugin-media-library-handler
`Compatibility
Plugin is compatible with Strapi
and above.Media & Folder Management API
* Configuration
* Folders
* Create Folder
* List Folders
* Get Folder
* Update Folder
* Delete Folder
* Bulk Delete
* Bulk Move
* Get Folder Structure
* Media Files
* Upload Media File
* Update Media File
* List Media Files
* Get Media File
* Delete Media File
* Error Handling
Configuration
No additional configuration needed, the plugin is automatically enabled after installation.Generate API Token (with proper permissions for Media section) which would be provided as
Authorization header to each API call.Folders
$3
Create a new folder.
`
POST {STRAPI_BASE_URL}/api/media/folders
Content-Type: application/json
Request Body
json
{
"name": "My New Folder",
"parentId": 123
}
`Response (201)
json
{
"id": 456,
"name": "My New Folder",
"parent": null,
"createdAt": "2025-05-05T12:34:56.789Z",
...
}
`Errors
*
– validation failed.
* 500 Internal Server Error – unexpected error.$3
Retrieve folders, with optional search and sorting.
`
GET {STRAPI_BASE_URL}/api/media/folders?parentId=123&_q=term&sort=name:asc&sort=createdAt:desc
Query Parameters
*
(integer) — optional, filter by parent folder (omit or null for root)
* _q (string) — optional, full-text search string
* sort (string) — optional, repeatable. Format: field:asc|desc.Response (200)
`json
[
{
"id": 123,
"name": "Root Folder",
"children": { "count": 2 },
"files": { "count": 5 },
...
}
]
`$3
Get a specific folder by its ID, including nested parents up to 5 levels.
GET {STRAPI_BASE_URL}/api/media/folders/:id
Path Parameter
*
(integer) — required, positive folder ID.Response (200)
`json
{
"id": 123,
"name": "Nested Folder",
"parent": {
"id": 50,
"name": "Parent 1",
"parent": {
"id": 10,
"name": "Parent 2"
...
}
},
"children": { "count": 0 },
"files": { "count": 3 },
...
}
`Errors
*
– invalid or missing ID.
* 404 Not Found – folder not found.$3
Update an existing folder’s name and/or parent.
`
PUT {STRAPI_BASE_URL}/api/media/folders/:id
Content-Type: application/json
Path Parameter
*
(integer) — required.Request Body
`json
{
"name": "Renamed Folder",
"parentId": 999
}
`Response (200)
json
{
"id": 123,
"name": "Renamed Folder",
"parent": 999,
...
}
`Errors
*
– validation failure.
* 404 Not Found – folder doesn’t exist.$3
Delete a single folder.
`
DELETE {STRAPI_BASE_URL}/api/media/folders/:id
Path Parameter
*
(integer) — required.Response (200)
`json
[
{
"id": 123,
"name": "Deleted Folder",
...
}
]
`$3
Delete multiple files and folders in one call.
POST {STRAPI_BASE_URL}/api/media/bulk-delete
Content-Type: application/json
Request Body
json
{
"fileIds": [1, 2, 3],
"folderIds": [10, 11, 12]
}
`Response (200)
json
{
"deletedFiles": [ { ... } ],
"deletedFolders": [ { ... }]
}
`$3
Move multiple files and folders to a target folder.
POST {STRAPI_BASE_URL}/api/media/bulk-move
Content-Type: application/json
Request Body
json
{
"fileIds": [1, 2, 3],
"folderIds": [10, 11, 12],
"targetFolderId": 99
}
`Response (200)
json
{
"movedFiles": [ { ... } ],
"movedFolders": [ { ... } ]
}
`$3
Retrieve the entire nested folder tree.
GET {STRAPI_BASE_URL}/api/media/folders-structure
Response (200)
json
[
{
"id": 1,
"name": "Root",
"children": [
{ "id": 2, "name": "Child A", "children": [ { ... } ] },
...
]
}
]
`Media Files
$3
Upload a file to a folder.
POST {STRAPI_BASE_URL}/api/media/files
Content-Type: multipart/form-data
Form Data
*
(file) — required.
* folderId (integer) — optional.
* alternativeText (string) — optional.
* caption (string) — optional.
* skipIfExist (string) — optional, will skip if there is already file existing with same filename, caption and alternativeText (no matter the folderId).Response (200)
`json
{
"data": [
{
"id": 321,
"name": "image.png",
"url": "/uploads/image.png",
"folder": 99,
...
}
]
}
`$3
Update file metadata (name, alt text, caption, or folder).
POST {STRAPI_BASE_URL}/api/media/files/:id
Content-Type: application/json
Path Parameter
*
(integer) — required.Request Body
`json
{
"name": "newname.png",
"alternativeText": "An example",
"caption": "Caption text",
"folderId": 99
}
`Response (200)
json
{
"data": {
"id": 321,
"name": "newname.png",
"alternativeText": "An example",
"caption": "Caption text",
"folder": 99,
...
}
}
`$3
Retrieve files, with optional search by name, caption or alternativeText, and sorting.
GET {STRAPI_BASE_URL}/api/media/files?name=some_term&sort=createdAt:desc
Query Parameters
*
(string) — optional, filter by filename
* caption (string) — optional, filter by caption
* alternativeText (string) — optional, filter by alternativeText
* sort (string) — optional, repeatable. Format: field:asc|desc.Response (200)
`json
[
{
"id": 42,
"name": "filename.png",
"alternativeText": "marketing_contributors_other_internal",
"caption": "some random caption",
"folder": {
"id": 159,
"name": "Base dir"
},
"createdAt": "2025-04-20T11:22:33.444Z",
...
},
]
`$3
Get file metadata (name, alt text, caption, folder, etc).
GET {STRAPI_BASE_URL}/api/media/files/:id
Path Parameter
*
(integer) — required.Response (200)
`json
{
"data": {
"id": 321,
"name": "newname.png",
"alternativeText": "An example",
"caption": "Caption text",
"folder": 99,
"formats": {
...
}
...
}
}
`$3
Delete a single media file.
DELETE {STRAPI_BASE_URL}/api/media/files/:id
Path Parameter
*
(integer) — required.Response (200)
`json
[
{
"id": 123,
"name": "Deleted File",
...
}
]
``* 400 Bad Request: validation errors, missing/invalid params.
* 404 Not Found: resource not found.
* 500 Internal Server Error: unexpected server error.
This project is licensed under the MIT.
[npm-url-svg]: https://img.shields.io/npm/v/strapi-plugin-media-library-handler.svg
[npm-url]: https://www.npmjs.com/package/strapi-plugin-media-library-handler