Items

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.

Scope

knowledge_base:read

Permission

View the module

MCP tool

knowledge_base_items_listOn the full surface; on the compact one, mb_execute_operation with id: "knowledge_base.items.list".

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

Parameters

Response

Errors

Example

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

Scope

knowledge_base:read

Permission

View the module

MCP tool

knowledge_base_items_getOn the full surface; on the compact one, mb_execute_operation with id: "knowledge_base.items.get".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/knowledge-base/items/{item_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/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.

Scope

knowledge_base:write

Permission

Edit in the module

MCP tool

knowledge_base_items_createOn the full surface; on the compact one, mb_execute_operation with id: "knowledge_base.items.create".

Events it can emit

knowledge_base.article.created

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

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/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.

Scope

knowledge_base:write

Permission

Edit in the module

MCP tool

knowledge_base_items_updateOn the full surface; on the compact one, mb_execute_operation with id: "knowledge_base.items.update".

Events it can emit

knowledge_base.article.updatedknowledge_base.article.visibility_changed

Declared cost: up to 35 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/knowledge-base/items/{item_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/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.

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

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

Permission

Edit in the module

MCP tool

knowledge_base_items_deleteOn the full surface; on the compact one, mb_execute_operation with id: "knowledge_base.items.delete".

Events it can emit

knowledge_base.article.deleted

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

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/knowledge-base/items/{item_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/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.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

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

Permission

Edit in the module

MCP tool

knowledge_base_items_bulk_deleteOn the full surface; on the compact one, mb_execute_operation with id: "knowledge_base.items.bulk.delete".

Events it can emit

knowledge_base.article.deleted

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

Parameters

Response

Errors

Example

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

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/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.

Scope

knowledge_base:write

Permission

Edit in the module

MCP tool

knowledge_base_items_pinOn the full surface; on the compact one, mb_execute_operation with id: "knowledge_base.items.pin".

Events it can emit

knowledge_base.article.updated

Declared cost: up to 2 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/knowledge-base/items/{item_id}/pin" \
  -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 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.

Scope

knowledge_base:write

Permission

Edit in the module

MCP tool

knowledge_base_items_unpinOn the full surface; on the compact one, mb_execute_operation with id: "knowledge_base.items.unpin".

Events it can emit

knowledge_base.article.updated

Declared cost: up to 2 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/knowledge-base/items/{item_id}/unpin" \
  -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 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.

Scope

knowledge_base:write

Permission

Edit in the module

MCP tool

knowledge_base_items_favoriteOn the full surface; on the compact one, mb_execute_operation with id: "knowledge_base.items.favorite".

Declared cost: up to 2 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/knowledge-base/items/{item_id}/favorite" \
  -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 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.

Scope

knowledge_base:write

Permission

Edit in the module

MCP tool

knowledge_base_items_unfavoriteOn the full surface; on the compact one, mb_execute_operation with id: "knowledge_base.items.unfavorite".

Declared cost: up to 2 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/knowledge-base/items/{item_id}/unfavorite" \
  -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 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.

Scope

knowledge_base:write

Permission

Edit in the module

MCP tool

knowledge_base_items_reorderOn the full surface; on the compact one, mb_execute_operation with id: "knowledge_base.items.reorder".

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

Parameters

Response

Errors

Example

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

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/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.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

knowledge_base:write

Permission

Edit in the module

MCP tool

knowledge_base_items_bulk_update_tagsOn the full surface; on the compact one, mb_execute_operation with id: "knowledge_base.items.bulk.update_tags".

Events it can emit

knowledge_base.article.updated

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

Parameters

Response

Errors

Example

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

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