Lists the images, videos and documents (PDF, PowerPoint and Word, for LinkedIn document posts) of the organization's media library, newest first, paginated by cursor (limit up to 200). Filters: folder_id (files directly inside that folder, not in its subfolders), root_only=true (the files that are not in any folder), type (image, video or document), source (upload, ai_generated or edited), tag (exact) and search (text in the name or a tag, case-insensitive). Filters run on the pages read, so a page can bring fewer than limit while has_more is true: follow next_cursor. Each file comes with its storage_path (what crm.whatsapp.send_media and media_library.items.canvas_edit take; it keeps the folder where the file was uploaded, even after moving it), who uploaded it (uploaded_by and uploaded_by_name; null for old files that stored a marker) and canvas_element_count; the signed download links (download_url, valid for an hour, and thumbnail_download_url) only with include_download_url true, or with media_library.items.get. The editor's recipe is only in get. Needs view access to the Media Library.
Escopo
media_library:read
Permissão
Ver o módulo
Tool do MCP
media_library_items_listNa superfície completa; na compacta, mb_execute_operation com id: "media_library.items.list".
Custo declarado: até 601 leituras e 0 escritas por chamada (contam na cota diária).
Parâmetros
limitintegerqueryopcional
Rows per page (1 to 200; default 50).
Padrão: 50
cursorstringqueryopcional
The next_cursor of the previous page, to continue the list; omit it for the first page.
folder_idstringqueryopcional
Only the files right inside this folder (from media_library.folders.list).
root_onlybooleanqueryopcional
Only the files that are in no folder.
typeenumqueryopcional
image, video or document (PDF, PowerPoint or Word).
Valores: image, video, document
sourceenumqueryopcional
upload, ai_generated or edited (made with the canvas editor).
Valores: upload, ai_generated, edited
tagstringqueryopcional
Only the files with this exact tag.
searchstringqueryopcional
Text in the name or in a tag (case does not matter).
include_download_urlbooleanqueryopcional
Also the signed download URLs of each file (download_url, thumbnail_download_url); default false: get one file with media_library.items.get to download it.
Returns a file of the media library: name (original_name), type (image, video or document), size in bytes, width and height (images; a document's first page, in PDF points; duration for videos), page_count and document_flags for a document, folder, tags, source (upload, ai_generated or edited), who uploaded it (uploaded_by and uploaded_by_name; null for old files that stored a marker) and when, storage_path, and download_url (a signed link valid for an hour; null when the file is not stored in this organization's library). An image edited with the canvas editor also brings canvas_elements (the editable recipe), canvas_base and edited_from_id. Not found (media_item_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_items_getNa superfície completa; na compacta, mb_execute_operation com id: "media_library.items.get".
Custo declarado: até 2 leituras e 0 escritas por chamada (contam na cota diária).
Parâmetros
item_idstringrotaobrigatório
The file's id (from media_library.items.list, or the item_id that media_library.items.create returns).
Resposta
idstring
original_namestring
typeenum
Valores: image, video, document
uploaded_atnumber
filenamestring | null
sizenumber | null
folder_idstring | null
tagsarray<string> | null
sourcestring | null
storage_pathstring | null
thumbnail_storage_pathstring | null
widthnumber | null
heightnumber | null
durationnumber | null
page_countnumber | null
A document's pages (a PDF's; PowerPoint and Word files do not bring them).
document_flagsarray<string> | null
What was seen when the PDF was checked: encrypted (password-protected), layers, mixed_page_sizes (pages of different sizes) or unreadable.
uploaded_bystring | null
The uid of who uploaded it (null when unknown: old files stored a marker instead).
uploaded_by_namestring | null
The name of who uploaded it.
edited_from_idstring | null
canvas_element_countnumber | null
canvas_elementsarray<object> | null
canvas_baseobject | null
download_urlstring | null
A signed URL to download the file without a session (it expires at download_url_expires_at). In a list only with include_download_url true.
Upload an image, video or document to the media library
media_library.items.create
EscritaIdempotenteDesde 2026-11-01
Uploads (adds) an image, a video or a document to the media library, in one of two ways. In one call: send the file itself as content_base64 with content_type and name (up to 768000 bytes = 750 KB decoded, because the request body is capped at 1 MB). Or in two steps, for files of up to 1 GB (a document, up to 100 MB): call media_library.uploads.create, PUT the bytes to its upload_url with the headers it returns, then call this with its storage_path. Takes JPEG, PNG, WebP or GIF images, MP4, MOV or WebM videos, and PDF, PowerPoint (PPT, PPTX) or Word (DOC, DOCX) documents of up to 100 MB, LinkedIn's limit for document posts (type document; to use it in a social_planner post with format document, its master_media url is /api/v1/storage/resolve?key=<its storage_path, URL-encoded>). A file uploaded with media_library.uploads.create (and its thumbnail) already counted toward the storage quota when its URL was issued; a file sent inline checks that the organization's storage has room (otherwise 409 limit_reached, details.resource storage) and counts toward the quota from here on. Optional: folder_id, name (default: the uploaded file name), tags, width/height (read from the file for images up to 10 MB when missing; for a document, send its first page in PDF points), duration for a video, page_count for a document (send it: the server does not open documents; LinkedIn takes up to 300 pages and checks them when it processes the file), and thumbnail_storage_path for a video or a document (its first page, uploaded with purpose video_thumbnail or document_thumbnail). With public_url: true (images only) it also returns public_url, a signed link that works without a session for 30 days, or for public_url_expires_in_days (1 to 3650) when you send it, and public_url_expires_at (it always expires): for the body of an email or a web page; it stops working earlier when the file is deleted from storage (deleting through the API keeps the file 30 days in the trash first). Idempotent by file: the same storage_path, or the same content and name in the same folder, returns the file already there with created: false (public_url: true on it issues a new link, with the same expiry rule, for a file already in the library). The storage_path of a library file also works in crm.whatsapp.send_media (a PDF or a Word file as media_type document). Errors: storage_path_invalid, storage_object_not_found, unsupported_media_type (also public_url on a video or a document), file_too_large (a document over 100 MB, any other file over 1 GB), thumbnail_only_for_videos (a thumbnail on an image), thumbnail_path_invalid (also a thumbnail that another file already uses), media_folder_not_found, invalid_input (a folder_id that is a reserved storage folder name: thumbnails, booking_avatar). Needs full access to the Media Library.
Instruções para agentes
If the upload URL expired before the PUT, ask for a new one with media_library.uploads.create; do not retry the registration with a path that was never uploaded. A public_url is public: share it only where the image is meant to be seen.
Escopo
media_library:write
Permissão
Editar no módulo
Tool do MCP
media_library_items_createNa superfície completa; na compacta, mb_execute_operation com id: "media_library.items.create".
Custo declarado: até 9 leituras e 1 escritas por chamada (contam na cota diária).
Parâmetros
storage_pathstringcorpoopcional
The storage_path media_library.uploads.create returned (the file already uploaded to its URL), or that of a file already in the library.
content_base64stringcorpoopcional
The file itself in base64, up to 750 KB decoded: one step, without the signed upload URL (needs content_type and name).
content_typeenumcorpoopcional
The type of the inline file (required with content_base64): image/jpeg, image/png, image/webp, image/gif, video/mp4, video/quicktime, video/webm, application/pdf, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document.
The visible name; default: the uploaded file's name. Required with content_base64.
tagsarray<string>corpoopcional
Free-text tags (up to 50, 64 characters each).
widthintegercorpoopcional
Width in pixels; for images up to 10 MB it is read from the file when missing. For a document, its first page in PDF points (the server does not open documents).
heightintegercorpoopcional
Height in pixels; for images up to 10 MB it is read from the file when missing. For a document, its first page in PDF points (the server does not open documents).
durationnumbercorpoopcional
A video's length, in seconds.
page_countintegercorpoopcional
A document's pages (the server does not open documents: send them). LinkedIn takes documents of up to 300 pages and checks them when it processes the file.
thumbnail_storage_pathstringcorpoopcional
A video's thumbnail, or a document's first page: the storage_path of an upload made with purpose video_thumbnail or document_thumbnail.
public_urlbooleancorpoopcional
Also return a public URL (no session) of the image, for an email body or a page. Images only; it expires in 30 days unless public_url_expires_in_days says otherwise.
public_url_expires_in_daysintegercorpoopcional
How many days that public URL lasts (1 to 3650; default 30). It always expires.
curl-X POST "https://api.mb-suite.com/v1/media-library/items" \
-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 POST "https://api.mb-suite.com/v1/media-library/items" \
-H"Authorization: Bearer $MB_TEST_KEY"
PATCH/v1/media-library/items/{item_id}
Rename, tag or move a file
media_library.items.update
EscritaIdempotenteDesde 2026-11-01
Changes a media library file: name (the visible name; control characters and slashes are removed), tags (replaces the whole list) and folder_id to move it to another folder (null takes it out of every folder). The file itself does not change. Unknown fields are rejected; an unknown folder fails with media_folder_not_found. Returns the updated file. To move many files at once use media_library.items.bulk.move. Needs full access to the Media Library.
Escopo
media_library:write
Permissão
Editar no módulo
Tool do MCP
media_library_items_updateNa superfície completa; na compacta, mb_execute_operation com id: "media_library.items.update".
Custo declarado: até 2 leituras e 1 escritas por chamada (contam na cota diária).
Parâmetros
item_idstringrotaobrigatório
The file's id (from media_library.items.list, or the item_id that media_library.items.create returns).
EscritaEm massa · até 200IdempotenteDesde 2026-11-01
Moves up to 200 media library files to one folder (folder_id; null takes them out of every folder), like dragging a selection in the app. Files already there count as unchanged; ids that do not exist are skipped and returned in not_found. Outside the app it requires a dry run (which lists what moves) and a confirm_token. Needs full access to the Media Library.
Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.
Escopo
media_library:write
Permissão
Editar no módulo
Tool do MCP
media_library_items_bulk_moveNa superfície completa; na compacta, mb_execute_operation com id: "media_library.items.bulk.move".
Custo declarado: até 202 leituras e 200 escritas por chamada (contam na cota diária).
Parâmetros
item_idsarray<string>corpoobrigatório
The files' ids (1 to 200), from media_library.items.list.
Deletes a file from the media library. It goes to the 30-day trash, where an owner or admin can restore it (platform.trash.restore); the stored file is kept meanwhile (and keeps counting toward the storage quota) so the restore brings it back intact, and it is deleted from storage when the trash item is purged or expires. Posts, ads or emails that already used the image keep their own copy. Outside the app it needs a dry run 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:writee «Permitir exclusões» (media_library:delete no OAuth)
Permissão
Editar no módulo
Tool do MCP
media_library_items_deleteNa superfície completa; na compacta, mb_execute_operation com id: "media_library.items.delete".
Deletes up to 200 media library files; each one goes to the 30-day trash and can be restored on its own (the stored files are kept meanwhile). Ids that do not exist are skipped and returned in not_found. Outside the app it requires a dry run (which lists what will be deleted) and a confirm_token. Needs full access to the Media Library.
Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.
Escopo
media_library:writee «Permitir exclusões» (media_library:delete no OAuth)
Permissão
Editar no módulo
Tool do MCP
media_library_items_bulk_deleteNa superfície completa; na compacta, mb_execute_operation com id: "media_library.items.bulk.delete".
Composes elements on top of a library image with the canvas editor (no AI, no credits). Editing an original never touches it: it creates a new image in the same folder (source edited, edited_from_id, named new_name or "<name> (edited)") that keeps the recipe, so it can be edited again; editing that derived image updates it in place with a new file (mode created or updated in the result). elements (1 to 20) are positioned in fractions of the image (x_frac, y_frac, width_frac). Through the API the practical ones are type logo (asset logo, logo_dark or logo_icon: the organization's brand logos) and type image (image.storage_path of a file in this organization's library, image.natural_ratio = width / height); text, cta and shape need a raster rendered by the app's editor (raster.storage_path), so they are only practical from the app. Errors: not_an_image, canvas_base_too_large (base over 25 MB), canvas_base_missing or canvas_base_deleted, canvas_elements_invalid, canvas_composition_failed, limit_reached (details.resource storage: the storage is full), role_required (viewers and portal clients), rate_limited (20 per minute per person). Needs full access to the Media Library.
Instruções para agentes
Tell the person whether a new image was created (mode created, with its name) or an edited image was updated, and that the original is untouched.
Escopo
media_library:write
Permissão
Editar no módulo
Tool do MCP
media_library_items_canvas_editNa superfície completa; na compacta, mb_execute_operation com id: "media_library.items.canvas_edit".
Custo declarado: até 8 leituras e 2 escritas por chamada (contam na cota diária).
Parâmetros
item_idstringrotaobrigatório
The file's id (from media_library.items.list, or the item_id that media_library.items.create returns).
elementsarray<object>corpoobrigatório
The elements to compose on the image (1 to 20), as the canvas editor saves them: id, type (logo, image, text, cta or shape), x_frac, y_frac and width_frac (fractions of the image, 0 to 1), and per type: asset for a logo; image.storage_path (a file of this library) and image.natural_ratio (width / height) for an image; text, cta and shape also need raster.storage_path (a raster rendered by the app's editor).
new_namestringcorpoopcional
The name of the new derived image (only when editing an original); default: the original's name plus ' (edited)' in the caller's language (' (editada)' in Spanish and Portuguese).
