Campanhas

List the rows of a media plan

media_planner.campaigns.list

Lists the rows of a media plan in their display order, paginated by cursor (limit up to 200): campaigns in a campaigns-mode plan, platform rows or account rows in the other modes (row_kind says which). Each row has platform, budget, currency, status, own flight dates if any (start_day/end_day), labels, the link to a real campaign and the known spend (last_synced_cost). Filters status and platform fill the page (the rows are read until limit rows match). Requires view access to the Media Planner. With Google Ads, LinkedIn or TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).

Escopo

media_planner:read

Permissão

Ver o módulo

Tool do MCP

media_planner_campaigns_listNa superfície completa; na compacta, mb_execute_operation com id: "media_planner.campaigns.list".

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

Parâmetros

Resposta

Erros

Exemplo

curl "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/campaigns" \
  -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/media-planner/plans/{plan_id}/campaigns" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one row of a media plan

media_planner.campaigns.get

Returns one row of a media plan (a campaign, a platform row or an account row) with its budget, currency, status, dates, labels, link to a real campaign, carryover applied, manual spend and known spend. Not found: media_plan_not_found for the plan, media_plan_row_not_found for the row. Requires view access to the Media Planner. With Google Ads, LinkedIn or TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).

Escopo

media_planner:read

Permissão

Ver o módulo

Tool do MCP

media_planner_campaigns_getNa superfície completa; na compacta, mb_execute_operation com id: "media_planner.campaigns.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/media-planner/plans/{plan_id}/campaigns/{campaign_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/media-planner/plans/{plan_id}/campaigns/{campaign_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Add a row to a media plan

media_planner.campaigns.create

Adds a row to a media plan and recomputes the plan's totals. What a row is depends on the plan's mode: in campaigns mode it is a planned campaign (name and platform required; it can be linked to a real campaign with mapped_campaign_id + external_customer_id, an ad account connected to this organization for that platform, to sync its spend); in platforms mode it is one row per ad platform (platform required, one row per platform except 'other', which needs platform_custom_name; MB Suite names it and its spend is the total of that platform's accounts); in account mode it is one row per currency (MB Suite names it; excluded_account_ids leaves connected accounts out of its total). manual_spend (platforms and account modes) adds spend entered by hand. Fields that do not apply to the plan's mode are rejected (field_not_in_mode). Defaults: budget 0, the plan's currency, status draft for a campaign and active for a platform or account row, no own dates (the row follows the plan window), last position. label_ids must be campaign labels of this organization or of its workspace. Errors: platform_row_exists, currency_row_exists and limit_reached (409; a plan holds up to 500 rows, details.resource media_plan_rows), external_account_not_linked (404: an ad account that is not connected to the organization; details.platform), link_incomplete and unknown_label_ids (400). Returns the row and the plan's new totals. Requires full access to the Media Planner. With Google Ads, LinkedIn or TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).

Escopo

media_planner:write

Permissão

Editar no módulo

Tool do MCP

media_planner_campaigns_createNa superfície completa; na compacta, mb_execute_operation com id: "media_planner.campaigns.create".

Eventos que pode emitir

media_planner.campaign.changed

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/campaigns" \
  -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/media-planner/plans/{plan_id}/campaigns" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Update a row of a media plan

media_planner.campaigns.update

Updates one or more fields of a row, sent inside updates ({ plan_id, campaign_id, updates: { … } }): name, platform and platform_custom_name (campaigns mode), budget, currency, start_date/end_date (YYYY-MM-DD; null clears them so the row follows the plan), status, label_ids, the link to a real campaign (mapped_campaign_id + external_customer_id together; mapped_campaign_id null unlinks; changing the platform of a linked campaign unlinks it), manual_spend (null clears it; the known spend keeps the synced part), excluded_account_ids (account mode) and order. What a row is depends on the plan's mode: in campaigns mode it is a planned campaign (name and platform required; it can be linked to a real campaign with mapped_campaign_id + external_customer_id, an ad account connected to this organization for that platform, to sync its spend); in platforms mode it is one row per ad platform (platform required, one row per platform except 'other', which needs platform_custom_name; MB Suite names it and its spend is the total of that platform's accounts); in account mode it is one row per currency (MB Suite names it; excluded_account_ids leaves connected accounts out of its total). manual_spend (platforms and account modes) adds spend entered by hand. A platform row cannot change its platform (platform_immutable). Each change is kept in the campaign history (media_planner.changes.list); budget and currency changes recompute the plan's totals. skip_activity: true keeps the change out of the account's Activity feed, for automated syncs that name each row after its real campaign: it only goes with name and the link fields (mapped_campaign_id, mapped_campaign_name, external_customer_id); with any other field it is invalid_input (400) and nothing is saved. The change stays in the audit log and the history, and the webhook still fires. An update that changes nothing returns changed: false. Requires full access to the Media Planner. With Google Ads, LinkedIn or TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).

Escopo

media_planner:write

Permissão

Editar no módulo

Tool do MCP

media_planner_campaigns_updateNa superfície completa; na compacta, mb_execute_operation com id: "media_planner.campaigns.update".

Eventos que pode emitir

media_planner.campaign.changed

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

Parâmetros

Resposta

Erros

Exemplo

curl -X PATCH "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/campaigns/{campaign_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/media-planner/plans/{plan_id}/campaigns/{campaign_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Delete a row of a media plan

media_planner.campaigns.delete

Deletes one row of a media plan and recomputes the plan's totals. The row goes to the 30-day trash, where an owner or admin can restore it (platform.trash.restore; its comments stay and come back with it, and restoring recomputes the plan totals; 409 trash_restore_parent_missing if the plan no longer exists). The deletion is kept in the plan's change history. Outside the app it needs a dry run and a confirm_token, except a REST DELETE with a key allowed to delete. Requires full access to the Media Planner.

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

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

Permissão

Editar no módulo

Tool do MCP

media_planner_campaigns_deleteNa superfície completa; na compacta, mb_execute_operation com id: "media_planner.campaigns.delete".

Eventos que pode emitir

media_planner.campaign.changed

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

Parâmetros

Resposta

Erros

Exemplo

curl -X DELETE "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/campaigns/{campaign_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/media-planner/plans/{plan_id}/campaigns/{campaign_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Reorder the rows of a media plan

media_planner.campaigns.reorder

Sets the display order of a plan's rows: campaign_ids in the new order (position = index); rows not listed keep their relative order after them. All or nothing: an id that is not a row of the plan stops the whole reorder (404). In a platforms-mode plan the order matters: if two rows ever share a platform, the first one receives the platform's spend. Returns how many rows moved and the final order. Requires full access to the Media Planner.

Escopo

media_planner:write

Permissão

Editar no módulo

Tool do MCP

media_planner_campaigns_reorderNa superfície completa; na compacta, mb_execute_operation com id: "media_planner.campaigns.reorder".

Custo declarado: até 501 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/media-planner/plans/{plan_id}/campaigns/reorder" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "campaign_ids": [
    "CAMPAIGN_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/media-planner/plans/{plan_id}/campaigns/reorder" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "campaign_ids": [
    "CAMPAIGN_ID"
  ]
}'

Edit many rows of a media plan

media_planner.campaigns.bulk.update

Applies the same change to up to 500 rows of a plan, like the selection bar of the app: status, start_date/end_date (YYYY-MM-DD; null clears), currency (not in account mode, where each row is one currency), add_label_ids and remove_label_ids. Ids that are not rows of the plan are skipped and returned in not_found; rows that would end before they start stop the whole call (date_range_invalid). Each changed row is kept in the campaign history. Outside the app it requires a dry run (which lists the rows) and a confirm_token. Requires full access to the Media Planner.

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

media_planner:write

Permissão

Editar no módulo

Tool do MCP

media_planner_campaigns_bulk_updateNa superfície completa; na compacta, mb_execute_operation com id: "media_planner.campaigns.bulk.update".

Eventos que pode emitir

media_planner.campaign.changed

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/campaigns/bulk/update" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "campaign_ids": [
    "CAMPAIGN_ID"
  ],
  "updates": {},
  "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/media-planner/plans/{plan_id}/campaigns/bulk/update" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "campaign_ids": [
    "CAMPAIGN_ID"
  ],
  "updates": {},
  "dry_run": true
}'

Delete many rows of a media plan

media_planner.campaigns.bulk.delete

Deletes up to 500 rows of a plan and recomputes its totals; each row goes to the 30-day trash and can be restored on its own. Ids that are not rows of the plan are skipped and returned in not_found. The deletions are kept in the plan's change history. Outside the app it requires a dry run (which lists the rows) and a confirm_token. Requires full access to the Media Planner.

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

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

Permissão

Editar no módulo

Tool do MCP

media_planner_campaigns_bulk_deleteNa superfície completa; na compacta, mb_execute_operation com id: "media_planner.campaigns.bulk.delete".

Eventos que pode emitir

media_planner.campaign.changed

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/campaigns/bulk/delete" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "campaign_ids": [
    "CAMPAIGN_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/media-planner/plans/{plan_id}/campaigns/bulk/delete" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "campaign_ids": [
    "CAMPAIGN_ID"
  ],
  "dry_run": true
}'

Import campaigns from another plan

media_planner.campaigns.import

Copies campaigns from another campaigns-mode plan of this organization (source_plan_id; campaign_ids to pick some, default all, up to 200) to the end of this plan, which must be in campaigns mode too. Each copy keeps name, platform, currency and labels, takes its original budget (without carryover), the window of this plan and status draft, and drops the link to the real campaign, the spend, the carryover and the Auto-Budget bookkeeping. Recomputes the plan's totals and keeps the import in the change history with the source plan's name. Returns the new row ids. Requires full access to the Media Planner.

Escopo

media_planner:write

Permissão

Editar no módulo

Tool do MCP

media_planner_campaigns_importNa superfície completa; na compacta, mb_execute_operation com id: "media_planner.campaigns.import".

Eventos que pode emitir

media_planner.campaign.changed

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/campaigns/import" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "source_plan_id": "SOURCE_PLAN_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/media-planner/plans/{plan_id}/campaigns/import" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "source_plan_id": "SOURCE_PLAN_ID"
}'