API reference · Reports

Templates

reports · templates · 8 operations

GET/v1/reports/templates

List report templates

reports.templates.list

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

Scope: reports:read
Permission: View the module
MCP tool: reports_templates_listOn the full surface; on the compact one, mb_execute_operation with id: "reports.templates.list".

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

Parameters

limitintegerqueryoptional

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

Default: 50

cursorstringqueryoptional

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

sourceenumqueryoptional

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

Values: organization, inherited · Default: "organization"

statusenumqueryoptional

draft or published.

Values: draft, published

Response

dataarray<object>

has_moreboolean

next_cursorstring

Errors

invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Example

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

GET/v1/reports/templates/{template_id}

Get a report template with its pages

reports.templates.get

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

Scope: reports:read
Permission: View the module
MCP tool: reports_templates_getOn the full surface; on the compact one, mb_execute_operation with id: "reports.templates.get".

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

Parameters

template_idstringpathrequired

The template id (reports.templates.list).

sourceenumqueryoptional

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

Values: organization, inherited · Default: "organization"

Response

idstring

Template id.

titlestring

Title.

statusenum

draft or published.

Values: draft, published

sourceenum

organization, inherited or system.

Values: 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).

Errors

invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Example

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

POST/v1/reports/templates

Create a report template

reports.templates.create

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

Scope: reports:write
Permission: Edit in the module
MCP tool: reports_templates_createOn the full surface; on the compact one, mb_execute_operation with id: "reports.templates.create".

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

Parameters

titlestringbodyrequired

Title.

descriptionstringbodyoptional

Description.

subtitlestringbodyoptional

Subtitle.

accent_colorstring | nullbodyoptional

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

sectionsarray<object>bodyoptional

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

cover_pageobject | nullbodyoptional

Cover page settings; null for no cover.

table_of_contentsbooleanbodyoptional

Add a table of contents.

module_pagesarray<object>bodyoptional

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

data_source_slotsarray<object>bodyoptional

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

supported_platformsarray<string>bodyoptional

Platforms it is built for.

default_date_rangeobjectbodyoptional

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

theme_idstring | nullbodyoptional

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

theme_sourceenum | nullbodyoptional

system or organization, with theme_id.

Values: system, organization

label_idsarray<string>bodyoptional

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

Response

template_idstring

Errors

invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Example

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

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

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

Scope: reports:write
Permission: Edit in the module
MCP tool: reports_templates_updateOn the full surface; on the compact one, mb_execute_operation with id: "reports.templates.update".

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

Parameters

template_idstringpathrequired

The template id (reports.templates.list).

updatesobjectbodyrequired

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

Response

templateobject

Errors

report_template_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Example

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": {}
}'

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

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

Scope: reports:write
Permission: Edit in the module
MCP tool: reports_templates_publishOn the full surface; on the compact one, mb_execute_operation with id: "reports.templates.publish".
Events it can emit: reports.template.published

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

Parameters

template_idstringpathrequired

The template id (reports.templates.list).

publishedbooleanbodyrequired

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

Response

template_idstring

statusenum

Values: draft, published

changedboolean

Errors

report_template_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Example

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

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

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

Scope: reports:write
Permission: Edit in the module
MCP tool: reports_templates_duplicateOn the full surface; on the compact one, mb_execute_operation with id: "reports.templates.duplicate".

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

Parameters

template_idstringpathrequired

The template id (reports.templates.list).

Response

template_idstring

titlestring

Errors

report_template_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Example

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

DELETE/v1/reports/templates/{template_id}

Delete a report template

reports.templates.delete

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

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: reports:write and “Allow deletions” (reports:delete in OAuth)
Permission: Edit in the module
MCP tool: reports_templates_deleteOn the full surface; on the compact one, mb_execute_operation with id: "reports.templates.delete".

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

Parameters

template_idstringpathrequired

The template id (reports.templates.list).

Response

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.

Errors

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

Example

curl -X DELETE "https://api.mb-suite.com/v1/reports/templates/{template_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/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

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

Scope: reports:write
Permission: Edit in the module
MCP tool: reports_templates_deployOn the full surface; on the compact one, mb_execute_operation with id: "reports.templates.deploy".

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

Parameters

template_idstringpathrequired

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

template_sourceenumbodyoptional

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

Values: SYSTEM, ORGANIZATION, INHERITED · Default: "ORGANIZATION"

source_org_idstringbodyoptional

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

data_source_mappingobjectbodyoptional

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

titlestringbodyoptional

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

descriptionstringbodyoptional

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

Response

report_idstring

Errors

invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Example

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