Documents

List the brand voice documents

social_brand_voice.documents.list

Lists the documents uploaded to Brand Voice (brand guides, style manuals, example copy; at most 5 per organization), newest first, paginated by cursor: file name, MIME type, size, processing status (processing, ready or error with error_message), the AI indexing status (embedding_status, chunk_count; read but not indexed for lack of AI credits is status ready with embedding_status error and embedding_error ai_credits_exhausted, ai_personal_limit or payment_required), who uploaded it and when. MB Suite extracts their text and indexes it so Content Studio and the inbox write in the brand's voice. status is applied reading on until the page is full (up to 400 read per call). The extracted text comes with social_brand_voice.documents.get. Files are uploaded from the Brand Voice screen. Requires view access to Brand Voice.

Scope

social_brand_voice:read

Permission

View the module

MCP tool

social_brand_voice_documents_listOn the full surface; on the compact one, mb_execute_operation with id: "social_brand_voice.documents.list".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/social-brand-voice/documents" \
  -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/social-brand-voice/documents" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one brand voice document with its text

social_brand_voice.documents.get

Returns one Brand Voice document with the text MB Suite extracted from it (extracted_text, up to 50,000 characters; empty while it is processing or when extraction failed), the text the AI reads to write in the brand's voice. Not found (brand_voice_document_not_found) when the id does not exist or is one of the organization profile's general documents. The file itself is downloaded from the screen. Requires view access to Brand Voice.

Scope

social_brand_voice:read

Permission

View the module

MCP tool

social_brand_voice_documents_getOn the full surface; on the compact one, mb_execute_operation with id: "social_brand_voice.documents.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/social-brand-voice/documents/{document_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/social-brand-voice/documents/{document_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete a brand voice document

social_brand_voice.documents.delete

Deletes a Brand Voice document for good: the file, its extracted text and its AI fragments, so it stops feeding Content Studio and the inbox. The organization profile's general documents are not reachable here. It does not go to the trash and cannot be undone: outside the screen it always needs a dry run (which says how many AI fragments go) and its confirm_token. Returns how many fragments were removed. Requires edit access to Brand Voice.

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

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

Permission

Edit in the module

MCP tool

social_brand_voice_documents_deleteOn the full surface; on the compact one, mb_execute_operation with id: "social_brand_voice.documents.delete".

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

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/social-brand-voice/documents/{document_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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 DELETE "https://api.mb-suite.com/v1/social-brand-voice/documents/{document_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'