Folders

List media library folders

media_library.folders.list

Lists the folders of the organization's media library as a flat list sorted by their position (order), paginated by cursor (limit up to 200). Each folder carries parent_id (null for a top-level folder), so the tree can be rebuilt from the list. Pass parent_id to get only the direct subfolders of one folder, or root_only=true for the top-level ones; those filters run on the page read, so a page can bring fewer than limit while has_more is true: follow next_cursor. File counts per folder are in media_library.folders.get. Needs view access to the Media Library.

Scope

media_library:read

Permission

View the module

MCP tool

media_library_folders_listOn the full surface; on the compact one, mb_execute_operation with id: "media_library.folders.list".

Declared cost: up to 201 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/media-library/folders" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/media-library/folders" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one media library folder

media_library.folders.get

Returns a media library folder with its name, color, position and parent, plus item_count (files directly inside it, not in its subfolders), subfolder_count (direct subfolders) and path (the folders from the top level down to its parent, as {id, name}). Not found (media_folder_not_found) if the id does not exist in this organization. Needs view access to the Media Library.

Scope

media_library:read

Permission

View the module

MCP tool

media_library_folders_getOn the full surface; on the compact one, mb_execute_operation with id: "media_library.folders.get".

Declared cost: up to 24 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/media-library/folders/{folder_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/media-library/folders/{folder_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a media library folder

media_library.folders.create

Creates a folder in the organization's media library: name (up to 100 characters), color (a hex like #22c55e; default gray #6b7280) and parent_id to nest it inside another folder (without it, top level). The new folder goes last among its siblings. Folder names do not need to be unique. Fails with media_folder_not_found if parent_id does not exist. Returns folder_id and the folder. Needs full access to the Media Library.

Scope

media_library:write

Permission

Edit in the module

MCP tool

media_library_folders_createOn the full surface; on the compact one, mb_execute_operation with id: "media_library.folders.create".

Declared cost: up to 64 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/media-library/folders" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/media-library/folders" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME"
}'

Rename, recolor or move a folder

media_library.folders.update

Changes a media library folder: name, color, or parent_id to move it (with all its subfolders and files) inside another folder, or to the top level with parent_id=null; a moved folder goes last among its new siblings. Moving a folder inside itself or one of its own subfolders fails with folder_cycle; an unknown parent fails with media_folder_not_found. Unknown fields are rejected. Returns the folder and changed (false when nothing was different). Needs full access to the Media Library.

Scope

media_library:write

Permission

Edit in the module

MCP tool

media_library_folders_updateOn the full surface; on the compact one, mb_execute_operation with id: "media_library.folders.update".

Declared cost: up to 101 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/media-library/folders/{folder_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X PATCH "https://api.mb-suite.com/v1/media-library/folders/{folder_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Delete a media library folder

media_library.folders.delete

Deletes a media library folder. mode move_contents_up (default) moves its subfolders and files to the parent folder (or the top level) and deletes only the folder; restoring it brings the folder back empty. mode delete_contents deletes the folder with all its subfolders and files (up to 150 in total, otherwise folder_too_large_to_delete: delete files in bulk first), and restoring brings everything back together. Everything deleted stays 30 days in the trash (platform.trash.restore, owners and admins); the files themselves are kept in storage meanwhile and keep counting toward the storage quota. Outside the app it needs a dry run (which counts what moves or is deleted) and a confirm_token, except a REST DELETE with a key allowed to delete. Needs full access to the Media Library.

With an API key, this DELETE runs directly: the record stays 30 days in the trash and the response carries its trash_item_id. With an OAuth token, and through the MCP, it needs dry_run → confirm_token.

Scope

media_library:write and “Allow deletions” (media_library:delete in OAuth)

Permission

Edit in the module

MCP tool

media_library_folders_deleteOn the full surface; on the compact one, mb_execute_operation with id: "media_library.folders.delete".

Events it can emit

media_library.item.deleted

Declared cost: up to 400 reads and 160 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/media-library/folders/{folder_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X DELETE "https://api.mb-suite.com/v1/media-library/folders/{folder_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"