Pastas

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.

Escopo

media_library:read

Permissão

Ver o módulo

Tool do MCP

media_library_folders_listNa superfície completa; na compacta, mb_execute_operation com id: "media_library.folders.list".

Custo declarado: até 201 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode 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.

Escopo

media_library:read

Permissão

Ver o módulo

Tool do MCP

media_library_folders_getNa superfície completa; na compacta, mb_execute_operation com id: "media_library.folders.get".

Custo declarado: até 24 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode 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.

Escopo

media_library:write

Permissão

Editar no módulo

Tool do MCP

media_library_folders_createNa superfície completa; na compacta, mb_execute_operation com id: "media_library.folders.create".

Custo declarado: até 64 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode 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.

Escopo

media_library:write

Permissão

Editar no módulo

Tool do MCP

media_library_folders_updateNa superfície completa; na compacta, mb_execute_operation com id: "media_library.folders.update".

Custo declarado: até 101 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode 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.

Com uma API key, este DELETE roda direto: o registro fica 30 dias na lixeira e a resposta traz o seu trash_item_id. Com um token OAuth, e pelo MCP, pede dry_run → confirm_token.

Escopo

media_library:write e «Permitir exclusões» (media_library:delete no OAuth)

Permissão

Editar no módulo

Tool do MCP

media_library_folders_deleteNa superfície completa; na compacta, mb_execute_operation com id: "media_library.folders.delete".

Eventos que pode emitir

media_library.item.deleted

Custo declarado: até 400 leituras e 160 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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