Referência da API · Ad Creator

Copies

ad_creator · copies · 4 operações

GET/v1/ad-creator/copiesList ad copies GET/v1/ad-creator/copies/{copy_id}Get one ad copy POST/v1/ad-creator/copiesGenerate ad copies (AI)DELETE/v1/ad-creator/copies/{copy_id}Delete an ad copy

GET/v1/ad-creator/copies

List ad copies

ad_creator.copies.list

LeituraIdempotenteDesde 2026-11-01

Lists the organization's Ad Creator ad copies (sets of AI-written ad texts for one product or service), newest first, paginated by cursor (limit up to 200). Each item is a summary: name, product description, platforms (google_search, meta_ads, linkedin_ads, tiktok_ads), tone or custom tone, variants requested per platform (variant_count), how many variants were generated in total (generated_variant_count), status and credits spent. The variants themselves come with ad_creator.copies.get. Requires view access to the Ad Creator.

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

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

Parâmetros

limitintegerqueryopcional

How many items this page brings at most (see the maximum and the default in the schema).

Padrão: 50

cursorstringqueryopcional

The next_cursor of the previous page, exactly as it came (only for the same list and filters); without it, the first page.

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/ad-creator/copies" \
  -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/ad-creator/copies" \
  -H "Authorization: Bearer $MB_TEST_KEY"

GET/v1/ad-creator/copies/{copy_id}

Get one ad copy

ad_creator.copies.get

LeituraIdempotenteDesde 2026-11-01

Returns one ad copy set with its brief (product description, key benefits, CTA direction, landing page, tone) and every generated variant, grouped by platform through each variant's platform and variant_index. A google_search variant has up to 15 headlines (30 characters each) and 4 descriptions (90 characters each); a meta_ads, linkedin_ads or tiktok_ads variant has primary_text, headline, description and, for Meta, a cta_suggestion. The texts are written to fit each platform's character limits, but the AI can exceed them: check lengths before publishing. Not found for an id of another organization. Requires view access to the Ad Creator.

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

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

Parâmetros

copy_idstringrotaobrigatório

Ad copy id (from ad_creator.copies.list; the same id as in the Ad Creator URL).

Resposta

idstring

Ad copy id.

namestring

Name in the Ad Creator list.

product_descriptionstring

What is advertised (the brief).

platformsarray<string>

Platforms it was written for.

variantsarray<object>

The generated variants.

statusstring

Generation status.

created_atnumber

Epoch ms.

tonestring | null

Writing tone.

custom_tonestring | null

Free-form tone, when one was given.

variant_countnumber | null

Variants asked per platform.

key_benefitsstring | null

Benefits to highlight.

cta_directionstring | null

What the call to action asks for.

landing_page_urlstring | null

Landing page (for reference).

landing_page_contextstring | null

Extra context about the landing page.

total_credits_consumednumber | null

AI credits it consumed.

created_bystring | null

Who generated it (uid).

created_by_namestring | null

That person's name (null when MB Suite does not know it: a former member).

updated_atnumber | null

Epoch ms.

Erros

ad_copy_not_found 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/ad-creator/copies/{copy_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/ad-creator/copies/{copy_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

POST/v1/ad-creator/copies

Generate ad copies (AI)

ad_creator.copies.generate

EscritaDesde 2026-11-01

Writes ad copy with AI for one product or service and saves it as a new copy set in the Ad Creator: variant_count variants (1 to 10, default 3) for each requested platform. google_search gets responsive search ad headlines and descriptions; meta_ads, linkedin_ads and tiktok_ads get primary text, headline and description. The AI uses product_description plus the optional key_benefits, cta_direction and landing_page_context, in the given tone (or custom_tone); landing_page_url is only stored. Costs 1 AI credit per call, charged before generating: with no credits left (or the Chat budget or the caller's monthly limit used up) it fails with 402 ai_credits_exhausted and nothing is created; if the AI fails, the credit is refunded and nothing is saved (502 ai_generation_failed, safe to retry). Takes a few seconds, up to about 30 with many variants. Not idempotent: send an Idempotency-Key to retry safely. Nothing is published to the ad platforms. Returns the new copy (same shape as ad_creator.copies.get) and emits ad_creator.copy.generated. Requires edit access to the Ad Creator.

Instruções para agentes

Show the person the variants grouped by platform and point out any text that exceeds its platform's character limit before they use it.

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: ad_creator:write
Permissão: Editar no módulo
Tool do MCP: ad_creator_copies_generateNa superfície completa; na compacta, mb_execute_operation com id: "ad_creator.copies.generate".
Eventos que pode emitir: ad_creator.copy.generated

Custo declarado: até 8 leituras e 4 escritas por chamada (contam na cota diária). Usa uma plataforma externa (ai): conta na cota de operações externas.

Parâmetros

product_descriptionstringcorpoobrigatório

What is being advertised: product or service, audience, offer. The main input of the generator.

platformsarray<enum>corpoobrigatório

Ad platforms to write for: google_search (responsive search ads), meta_ads, linkedin_ads, tiktok_ads.

Valores: google_search, meta_ads, linkedin_ads, tiktok_ads

namestringcorpoopcional

Name shown in the Ad Creator list. Default: the first 60 characters of product_description.

toneenumcorpoopcional

Writing tone. Ignored when custom_tone is given.

Valores: professional, casual, urgent, aspirational, informational · Padrão: "professional"

custom_tonestringcorpoopcional

Free-form tone description; when present it replaces tone.

variant_countintegercorpoopcional

Variants per platform (1 to 10).

Padrão: 3

key_benefitsstringcorpoopcional

Benefits to highlight.

cta_directionstringcorpoopcional

What the call to action should ask for.

landing_page_urlstringcorpoopcional

Landing page URL, stored for reference (it is not visited).

landing_page_contextstringcorpoopcional

Text about the landing page to give the generator more context.

Resposta

copy_idstring

The new ad copy's id.

copyobject

The ad copy with its variants.

Erros

confirmation_required ai_generation_failed external_rate_limited sandbox_external_unavailable 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/ad-creator/copies" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_description": "PRODUCT_DESCRIPTION",
  "platforms": [
    "google_search"
  ],
  "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. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.

DELETE/v1/ad-creator/copies/{copy_id}

Delete an ad copy

ad_creator.copies.delete

IrreversívelDesde 2026-11-01

Deletes an ad copy set with all its variants. It goes to the 30-day trash, where an owner or admin can restore it whole (platform.trash.restore). Outside the app it needs a dry run and a confirm_token, except a REST DELETE with a key allowed to delete. Emits ad_creator.copy.deleted. Not found for an id of another organization. Requires edit access to the Ad Creator.

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: ad_creator:write e «Permitir exclusões» (ad_creator:delete no OAuth)
Permissão: Editar no módulo
Tool do MCP: ad_creator_copies_deleteNa superfície completa; na compacta, mb_execute_operation com id: "ad_creator.copies.delete".
Eventos que pode emitir: ad_creator.copy.deleted

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

Parâmetros

copy_idstringrotaobrigatório

Ad copy id (from ad_creator.copies.list; the same id as in the Ad Creator URL).

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

ad_copy_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/ad-creator/copies/{copy_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/ad-creator/copies/{copy_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"