Referência da API · Reports

Templates

reports · templates · 8 operações

GET/v1/reports/templates

List report templates

reports.templates.list

LeituraIdempotenteDesde 2026-11-01

Lists the organization's report templates (source=organization, the default) or, for an account, the published templates it inherits from its workspace (source=inherited), in the screen's manual order (position; the ones never ordered after, by title) and paginated by cursor (limit 50 by default, up to 200). Each item is a summary: title, status (draft|published), version, position, supported platforms, data source slots, labels, how many pages and blocks it has and who created it (created_by, created_by_name); fetch the pages with reports.templates.get. Filter by status. System templates are listed by reports.system_templates.list. Requires view access to Reports.

Escopo: reports:read
Permissão: Ver o módulo
Tool do MCP: reports_templates_listNa superfície completa; na compacta, mb_execute_operation com id: "reports.templates.list".

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

Parâmetros

limitintegerqueryopcional

How many templates per page (default 50, at most 200).

Padrão: 50

cursorstringqueryopcional

The next_cursor of the previous page, to get the next one; omit it for the first page.

sourceenumqueryopcional

organization (its own, default) or inherited (the workspace's published ones, for an account).

Valores: organization, inherited · Padrão: "organization"

statusenumqueryopcional

draft or published.

Valores: draft, published

Resposta

dataarray<object>

has_moreboolean

next_cursorstring

Erros

invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Exemplo

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

GET/v1/reports/templates/{template_id}

Get a report template with its pages

reports.templates.get

LeituraIdempotenteDesde 2026-11-01

Returns one report template with all its pages (sections) and blocks, its data source slots, default date range, cover page, theme and labels. Use source=inherited from an account to read a published template of its workspace. Not found if the id does not exist in the organization (or, for inherited, is not a published template of the parent). Requires view access to Reports.

Escopo: reports:read
Permissão: Ver o módulo
Tool do MCP: reports_templates_getNa superfície completa; na compacta, mb_execute_operation com id: "reports.templates.get".

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

Parâmetros

template_idstringrotaobrigatório

The template id (reports.templates.list).

sourceenumqueryopcional

organization (default) or inherited (a published one of the workspace).

Valores: organization, inherited · Padrão: "organization"

Resposta

idstring

Template id.

titlestring

Title.

statusenum

draft or published.

Valores: draft, published

sourceenum

organization, inherited or system.

Valores: organization, inherited, system

descriptionstring | null

Description.

subtitlestring | null

Subtitle.

accent_colorstring | null

Accent color.

versionnumber | null

Version (goes up with each update and publication).

positionnumber | null

Manual order.

is_system_templateboolean | null

A system template.

supported_platformsarray<string> | null

Platforms it is built for.

data_source_slotsarray<object> | null

Data slots a report maps to its sources.

default_date_rangeobject | null

Default period (type preset, fixed or dynamic).

sectionsarray<object> | null

Pages and blocks, as stored.

cover_pageobject | null

Cover page settings.

table_of_contentsboolean | null

Whether it has a table of contents.

module_pagesarray<object> | null

Module pages and where they go.

label_idsarray<string> | null

Template labels.

theme_idstring | null

Report theme.

theme_sourcestring | null

system or organization.

data_freshness_checked_atnumber | null

When the editor last refreshed live data (epoch ms).

created_atnumber | null

Created (epoch ms).

updated_atnumber | null

Last edited (epoch ms).

created_bystring | null

Uid of who created it.

created_by_namestring | null

Their name («MB Suite» for the system).

Erros

invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Exemplo

curl "https://api.mb-suite.com/v1/reports/templates/{template_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/reports/templates/{template_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

POST/v1/reports/templates

Create a report template

reports.templates.create

EscritaDesde 2026-11-01

Creates a report template of the organization as a draft (version 1). Only the title is required; you can also send its pages (sections with blocks), data source slots, supported platforms, default date range (last month if omitted), cover page, table of contents, module pages, theme and labels. Blocks that read a platform must point to a slot or to a data source connected to the organization (reports.data_sources.list). Publish it with reports.templates.publish. Requires edit access to Reports.

Escopo: reports:write
Permissão: Editar no módulo
Tool do MCP: reports_templates_createNa superfície completa; na compacta, mb_execute_operation com id: "reports.templates.create".

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

Parâmetros

titlestringcorpoobrigatório

Title.

descriptionstringcorpoopcional

Description.

subtitlestringcorpoopcional

Subtitle.

accent_colorstring | nullcorpoopcional

Accent color (hex); null for the theme's.

sectionsarray<object>corpoopcional

The pages and their blocks (new block types, slots, metrics and presets are checked; what the template already had is kept).

cover_pageobject | nullcorpoopcional

Cover page settings; null for no cover.

table_of_contentsbooleancorpoopcional

Add a table of contents.

module_pagesarray<object>corpoopcional

Module pages (module_tasks, module_pacing, module_social, module_seo) and where they go.

data_source_slotsarray<object>corpoopcional

The data slots a report from this template maps to its account's sources (id, name, platform).

supported_platformsarray<string>corpoopcional

Platforms it is built for.

default_date_rangeobjectcorpoopcional

Default period of the reports made from it (a new preset_key must be one of the presets).

theme_idstring | nullcorpoopcional

Report theme (reports.themes.list); null for the default.

theme_sourceenum | nullcorpoopcional

system or organization, with theme_id.

Valores: system, organization

label_idsarray<string>corpoopcional

Template labels (reports.labels.list with of: templates); an unknown id is label_unknown.

Resposta

template_idstring

Erros

invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

curl -X POST "https://api.mb-suite.com/v1/reports/templates" \
  -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/reports/templates" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "TITLE"
}'

PATCH/v1/reports/templates/{template_id}

Update a report template

reports.templates.update

EscritaDesde 2026-11-01

Updates fields of a report template: title, description, pages (send the full sections array), data source slots, supported platforms, default date range, cover page (null removes it), table of contents, module pages, theme (null = default) and labels; fields go inside updates. Every save bumps its version. To publish or unpublish use reports.templates.publish. New platform data sources in the blocks must be connected to the organization; new block types, data slots (they must be data_source_slots of the template), metrics, dimensions and presets are checked (report_block_type_unknown, report_block_slot_unknown, unknown_metric, unknown_dimension, preset_unknown, with the valid ones in details) and labels must exist (label_unknown, reports.labels.list with of: templates); what the template already had is kept. Returns the updated template. Requires edit access to Reports.

Escopo: reports:write
Permissão: Editar no módulo
Tool do MCP: reports_templates_updateNa superfície completa; na compacta, mb_execute_operation com id: "reports.templates.update".

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

Parâmetros

template_idstringrotaobrigatório

The template id (reports.templates.list).

updatesobjectcorpoobrigatório

The fields to change (the rest keep their value).

Resposta

templateobject

Erros

report_template_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

curl -X PATCH "https://api.mb-suite.com/v1/reports/templates/{template_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/reports/templates/{template_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

POST/v1/reports/templates/{template_id}/publish

Publish or unpublish a report template

reports.templates.publish

EscritaIdempotenteDesde 2026-11-01

Publishes a report template (published: true) so the organization's accounts inherit it and it is offered when generating reports, or returns it to draft (published: false). Setting the status it already has changes nothing (changed: false). Publishing fires reports.template.published. Requires edit access to Reports.

Escopo: reports:write
Permissão: Editar no módulo
Tool do MCP: reports_templates_publishNa superfície completa; na compacta, mb_execute_operation com id: "reports.templates.publish".
Eventos que pode emitir: reports.template.published

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

Parâmetros

template_idstringrotaobrigatório

The template id (reports.templates.list).

publishedbooleancorpoobrigatório

true publishes it (its accounts see it and «Generate report» offers it); false moves it back to draft.

Resposta

template_idstring

statusenum

Valores: draft, published

changedboolean

Erros

report_template_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

curl -X POST "https://api.mb-suite.com/v1/reports/templates/{template_id}/publish" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "published": 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/reports/templates/{template_id}/publish" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "published": true
}'

POST/v1/reports/templates/{template_id}/duplicate

Duplicate a report template

reports.templates.duplicate

EscritaDesde 2026-11-01

Copies a report template of the organization into a new draft titled '<title> (Copia)' (the suffix in the caller's language: (Copia), (Copy) or (Cópia)), with the same pages, slots, platforms and theme. Returns the new template id. Requires edit access to Reports.

Escopo: reports:write
Permissão: Editar no módulo
Tool do MCP: reports_templates_duplicateNa superfície completa; na compacta, mb_execute_operation com id: "reports.templates.duplicate".

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

Parâmetros

template_idstringrotaobrigatório

The template id (reports.templates.list).

Resposta

template_idstring

titlestring

Erros

report_template_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

curl -X POST "https://api.mb-suite.com/v1/reports/templates/{template_id}/duplicate" \
  -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/reports/templates/{template_id}/duplicate" \
  -H "Authorization: Bearer $MB_TEST_KEY"

DELETE/v1/reports/templates/{template_id}

Delete a report template

reports.templates.delete

IrreversívelDesde 2026-11-01

Deletes a report template of the organization; it stays 30 days in the trash (platform.trash.restore brings it back with the same id). Report instances already generated from it keep their own copy and are not affected; recurring deliveries that use it fail until it is restored or replaced: the dry run says how many deliveries use it and how many are scheduled. Requires edit access to Reports. Outside the screen it needs a dry run and a confirm_token, or a key with deletion enabled.

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: reports:write e «Permitir exclusões» (reports:delete no OAuth)
Permissão: Editar no módulo
Tool do MCP: reports_templates_deleteNa superfície completa; na compacta, mb_execute_operation com id: "reports.templates.delete".

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

Parâmetros

template_idstringrotaobrigatório

The template id (reports.templates.list).

Resposta

oktrue

trash_item_idstring

The trash item this deletion left: the item_id of platform.trash.restore (POST /trash/{item_id}/restore). Missing if nothing went to the trash.

trash_item_idsarray<string>

Only when the deletion left more than one copy: all of them, the first being trash_item_id.

trash_expires_atnumber

When the copy leaves the trash for good (epoch ms): 30 days after the deletion.

Erros

report_template_not_found delete_not_allowed confirmation_required invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

curl -X DELETE "https://api.mb-suite.com/v1/reports/templates/{template_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/reports/templates/{template_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

POST/v1/reports/templates/{template_id}/deploy

Create an editable report from a template

reports.templates.deploy

EscritaDesde 2026-11-01

Creates an editable report document (reports.reports.*) from a template: the organization's own (template_source=ORGANIZATION), a published one of the parent workspace (INHERITED) or a published system template (SYSTEM), with its data source slots mapped to the organization's connections (data_source_mapping: slot or platform → data source id from reports.data_sources.list). Use it to customize a report before generating its PDF; to generate a dated report instance directly use reports.instances.generate. Returns the new report id. Requires edit access to Reports.

Escopo: reports:write
Permissão: Editar no módulo
Tool do MCP: reports_templates_deployNa superfície completa; na compacta, mb_execute_operation com id: "reports.templates.deploy".

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

Parâmetros

template_idstringrotaobrigatório

The template to make an editable report from (reports.templates.list or reports.system_templates.list).

template_sourceenumcorpoopcional

ORGANIZATION (default: the organization's own), INHERITED (published by the workspace) or SYSTEM (published by MB Suite).

Valores: SYSTEM, ORGANIZATION, INHERITED · Padrão: "ORGANIZATION"

source_org_idstringcorpoopcional

INHERITED only: this account's workspace (optional; any other is 403).

data_source_mappingobjectcorpoopcional

Template slot or platform → connection id of this organization (google_ads:1234567890, from reports.data_sources.list).

titlestringcorpoopcional

The report's title (default: the template's).

descriptionstringcorpoopcional

The report's description (default: the template's).

Resposta

report_idstring

Erros

invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

curl -X POST "https://api.mb-suite.com/v1/reports/templates/{template_id}/deploy" \
  -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/reports/templates/{template_id}/deploy" \
  -H "Authorization: Bearer $MB_TEST_KEY"