Itens

List Knowledge Base articles

knowledge_base.items.list

Lists the articles of the organization's Knowledge Base that the caller can see, as summaries (title, excerpt of the first 280 characters, links, attachment metadata, tag ids, visibility, author, pinned, counts, is_favorite) — use knowledge_base.items.get for the full content. A restricted article (private, custom or agency) comes with excerpt null: its text is only read with get. Sort: created_desc (default), updated_desc, title_asc or most_viewed. Filters: search (title, text or author, ignoring case and accents), tag_id, pinned, favorites (the caller's), created_by_id and visibility. Visibility: public (everyone with access to the organization), private (only its creator), custom (its creator plus visible_to_user_ids) or agency (only people of the agency workspace with access to this Account; it exists only in Accounts). Private and restricted articles of other people never appear. Visibility and filters run on what each page reads (up to 500 articles per call), so a page can bring fewer than limit while has_more is true: follow next_cursor. Requires view access to the Knowledge Base.

Escopo

knowledge_base:read

Permissão

Ver o módulo

Tool do MCP

knowledge_base_items_listNa superfície completa; na compacta, mb_execute_operation com id: "knowledge_base.items.list".

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

Parâmetros

Resposta

Erros

Exemplo

curl "https://api.mb-suite.com/v1/knowledge-base/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 "https://api.mb-suite.com/v1/knowledge-base/items" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get a Knowledge Base article

knowledge_base.items.get

Returns one article with its full content: sanitized HTML in content and plain text in content_plain_text, links, attachments (metadata and the in-app link; files are downloaded from the app), tag ids, visibility and visible_to_user_ids, author, pinned state, view and comment counts, manual order and whether it is one of the caller's favorites. Not found (kb_item_not_found) if the id does not exist or the article is private or restricted and the caller cannot see it. Reading does not count a view. Requires view access.

Escopo

knowledge_base:read

Permissão

Ver o módulo

Tool do MCP

knowledge_base_items_getNa superfície completa; na compacta, mb_execute_operation com id: "knowledge_base.items.get".

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

Parâmetros

Resposta

Erros

Exemplo

curl "https://api.mb-suite.com/v1/knowledge-base/items/{item_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/knowledge-base/items/{item_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a Knowledge Base article

knowledge_base.items.create

Creates an article authored by the caller: title (up to 500 characters), content as HTML (sanitized: formatting, lists, links and images survive, scripts do not) or plain text (blank lines become paragraphs), up to 100,000 characters; links (each url must start with http:// or https://, otherwise invalid_input on links[n].url; the link's domain is filled in from the url when missing); tag_ids (ids from knowledge_base.tags.list; unknown ids are dropped); attachments (only files already uploaded to this organization's Knowledge Base storage, which the app does: an API client cannot upload files); visibility (default public) and, with custom, visible_to_user_ids (people without access to the organization are dropped). Visibility: public (everyone with access to the organization), private (only its creator), custom (its creator plus visible_to_user_ids) or agency (only people of the agency workspace with access to this Account; it exists only in Accounts). Passwords and keys do not belong in an article: if the text looks like it holds one, the article is saved anyway and warnings says content_looks_like_credential. Returns the new article. Requires full access to the Knowledge Base.

Escopo

knowledge_base:write

Permissão

Editar no módulo

Tool do MCP

knowledge_base_items_createNa superfície completa; na compacta, mb_execute_operation com id: "knowledge_base.items.create".

Eventos que pode emitir

knowledge_base.article.created

Custo declarado: até 34 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/knowledge-base/items" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "TITLE"
}'

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/knowledge-base/items" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "TITLE"
}'

Update a Knowledge Base article

knowledge_base.items.update

Changes one or more fields of an article the caller can see, sent inside updates: title, content (HTML or plain text; content_plain_text only together with content, otherwise it is derived), links, tag_ids and attachments (each replaces the whole list: keep an existing attachment by sending its id), visibility and visible_to_user_ids. Anyone with full access can edit the content; only the article's creator or an owner/admin can change its visibility (403 kb_visibility_change_denied); sending the visibility it already has is not a change. Unknown fields are rejected. Idempotent: sending what the article already has changes nothing (changed: false). If the new text looks like it holds a password or a key, warnings says content_looks_like_credential. Returns the article.

Escopo

knowledge_base:write

Permissão

Editar no módulo

Tool do MCP

knowledge_base_items_updateNa superfície completa; na compacta, mb_execute_operation com id: "knowledge_base.items.update".

Eventos que pode emitir

knowledge_base.article.updatedknowledge_base.article.visibility_changed

Custo declarado: até 35 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/knowledge-base/items/{item_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/knowledge-base/items/{item_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Delete a Knowledge Base article

knowledge_base.items.delete

Deletes an article together with its comments. Only its creator or an owner/admin can delete it (403 kb_delete_denied). It stays 30 days in the trash with its comments, where an owner or admin can restore it (platform.trash.restore); its attached files are kept for the restore. A private or restricted article appears in the trash without its title. Outside the app it needs a dry run (which counts the comments) and a confirm_token, except a REST DELETE with a key allowed to delete.

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

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

Permissão

Editar no módulo

Tool do MCP

knowledge_base_items_deleteNa superfície completa; na compacta, mb_execute_operation com id: "knowledge_base.items.delete".

Eventos que pode emitir

knowledge_base.article.deleted

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

Parâmetros

Resposta

Erros

Exemplo

curl -X DELETE "https://api.mb-suite.com/v1/knowledge-base/items/{item_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/knowledge-base/items/{item_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete many Knowledge Base articles

knowledge_base.items.bulk.delete

Deletes up to 50 articles with their comments; each one goes to the 30-day trash and can be restored on its own. Ids that do not exist or that the caller cannot see come back in not_found; articles the caller can see but did not create (and the caller is not an owner/admin) are skipped and come back in denied. Returns how many were deleted and their ids. Outside the app it requires a dry run (which lists what will be deleted and what will be skipped) and a confirm_token.

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

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

Permissão

Editar no módulo

Tool do MCP

knowledge_base_items_bulk_deleteNa superfície completa; na compacta, mb_execute_operation com id: "knowledge_base.items.bulk.delete".

Eventos que pode emitir

knowledge_base.article.deleted

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/knowledge-base/items/bulk/delete" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "item_ids": [
    "ITEM_ID"
  ],
  "dry_run": true
}'

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/knowledge-base/items/bulk/delete" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "item_ids": [
    "ITEM_ID"
  ],
  "dry_run": true
}'

Pin a Knowledge Base article

knowledge_base.items.pin

Pins an article at the top of the Knowledge Base for everyone who can see it (pinning is shared, unlike favorites). Idempotent: pinning an article that is already pinned changes nothing (changed: false). Returns the article. Requires full access.

Escopo

knowledge_base:write

Permissão

Editar no módulo

Tool do MCP

knowledge_base_items_pinNa superfície completa; na compacta, mb_execute_operation com id: "knowledge_base.items.pin".

Eventos que pode emitir

knowledge_base.article.updated

Custo declarado: até 2 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/knowledge-base/items/{item_id}/pin" \
  -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/knowledge-base/items/{item_id}/pin" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Unpin a Knowledge Base article

knowledge_base.items.unpin

Removes an article from the pinned strip, for everyone. Idempotent: unpinning an article that is not pinned changes nothing (changed: false). Returns the article. Requires full access.

Escopo

knowledge_base:write

Permissão

Editar no módulo

Tool do MCP

knowledge_base_items_unpinNa superfície completa; na compacta, mb_execute_operation com id: "knowledge_base.items.unpin".

Eventos que pode emitir

knowledge_base.article.updated

Custo declarado: até 2 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/knowledge-base/items/{item_id}/unpin" \
  -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/knowledge-base/items/{item_id}/unpin" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Add an article to the caller's favorites

knowledge_base.items.favorite

Marks an article as a favorite of the caller only (each person has their own favorites; filter them with favorites=true in knowledge_base.items.list). It does not change the article for anyone else nor its update date. Idempotent (changed: false when it already was). Returns the article. Requires full access.

Escopo

knowledge_base:write

Permissão

Editar no módulo

Tool do MCP

knowledge_base_items_favoriteNa superfície completa; na compacta, mb_execute_operation com id: "knowledge_base.items.favorite".

Custo declarado: até 2 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/knowledge-base/items/{item_id}/favorite" \
  -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/knowledge-base/items/{item_id}/favorite" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Remove an article from the caller's favorites

knowledge_base.items.unfavorite

Removes an article from the caller's favorites (nobody else's). Idempotent (changed: false when it was not a favorite). Returns the article. Requires full access.

Escopo

knowledge_base:write

Permissão

Editar no módulo

Tool do MCP

knowledge_base_items_unfavoriteNa superfície completa; na compacta, mb_execute_operation com id: "knowledge_base.items.unfavorite".

Custo declarado: até 2 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/knowledge-base/items/{item_id}/unfavorite" \
  -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/knowledge-base/items/{item_id}/unfavorite" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Set the manual order of articles

knowledge_base.items.reorder

Sets the shared manual order of the Knowledge Base (the "Manual" sort of the app): ordered_ids in the new order, up to 500; each article's order becomes its index. All or nothing: an id that does not exist or that the caller cannot see stops the whole reorder (404 kb_item_not_found with the missing ids), and a repeated id is 400. Articles not sent keep their position value. Returns how many were ordered. Requires full access.

Escopo

knowledge_base:write

Permissão

Editar no módulo

Tool do MCP

knowledge_base_items_reorderNa superfície completa; na compacta, mb_execute_operation com id: "knowledge_base.items.reorder".

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/knowledge-base/items/reorder" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "ordered_ids": [
    "ORDERED_ID"
  ]
}'

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/knowledge-base/items/reorder" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "ordered_ids": [
    "ORDERED_ID"
  ]
}'

Add or remove tags on many articles

knowledge_base.items.bulk.update_tags

Adds add_tag_ids and removes remove_tag_ids on up to 50 articles at once, like the selection bar of the app (the other tags of each article stay). Unknown tag ids to add are dropped; a tag in both lists is 400. Ids that do not exist or that the caller cannot see come back in not_found. Returns how many articles were updated. Outside the app it requires a dry run and a confirm_token.

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

knowledge_base:write

Permissão

Editar no módulo

Tool do MCP

knowledge_base_items_bulk_update_tagsNa superfície completa; na compacta, mb_execute_operation com id: "knowledge_base.items.bulk.update_tags".

Eventos que pode emitir

knowledge_base.article.updated

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/knowledge-base/items/bulk/tags" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "item_ids": [
    "ITEM_ID"
  ],
  "dry_run": true
}'

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/knowledge-base/items/bulk/tags" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "item_ids": [
    "ITEM_ID"
  ],
  "dry_run": true
}'