Carpetas

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.

Alcance

media_library:read

Permiso

Ver el módulo

Tool del MCP

media_library_folders_listEn la superficie completa; en la compacta, mb_execute_operation con id: "media_library.folders.list".

Costo declarado: hasta 201 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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.

Alcance

media_library:read

Permiso

Ver el módulo

Tool del MCP

media_library_folders_getEn la superficie completa; en la compacta, mb_execute_operation con id: "media_library.folders.get".

Costo declarado: hasta 24 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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.

Alcance

media_library:write

Permiso

Editar en el módulo

Tool del MCP

media_library_folders_createEn la superficie completa; en la compacta, mb_execute_operation con id: "media_library.folders.create".

Costo declarado: hasta 64 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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"
}'

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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.

Alcance

media_library:write

Permiso

Editar en el módulo

Tool del MCP

media_library_folders_updateEn la superficie completa; en la compacta, mb_execute_operation con id: "media_library.folders.update".

Costo declarado: hasta 101 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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": {}
}'

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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.

Con una API key, este DELETE se ejecuta directo: el registro queda 30 días en la papelera y la respuesta trae su trash_item_id. Con un token OAuth, y por el MCP, pide dry_run → confirm_token.

Alcance

media_library:write y «Permitir eliminar» (media_library:delete en OAuth)

Permiso

Editar en el módulo

Tool del MCP

media_library_folders_deleteEn la superficie completa; en la compacta, mb_execute_operation con id: "media_library.folders.delete".

Eventos que puede emitir

media_library.item.deleted

Costo declarado: hasta 400 lecturas y 160 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Respuesta

Errores

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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