Menú

Referencia de la API · Ad Creator

Copies

ad_creator · copies · 4 operaciones

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

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

Alcance: ad_creator:read
Permiso: Ver el módulo
Tool del MCP: ad_creator_copies_listEn la superficie completa; en la compacta, mb_execute_operation con id: "ad_creator.copies.list".

Costo declarado: hasta 202 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

limitintegerqueryopcional

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

Por defecto: 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.

Respuesta

dataarray<object>

has_moreboolean

next_cursorstring

Errores

invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Ejemplo

curl "https://api.mb-suite.com/v1/ad-creator/copies" \
  -H "Authorization: Bearer $MB_API_KEY"

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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

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

Alcance: ad_creator:read
Permiso: Ver el módulo
Tool del MCP: ad_creator_copies_getEn la superficie completa; en la compacta, mb_execute_operation con id: "ad_creator.copies.get".

Costo declarado: hasta 1 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

copy_idstringrutarequerido

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

Respuesta

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.

Errores

ad_copy_not_found invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Ejemplo

curl "https://api.mb-suite.com/v1/ad-creator/copies/{copy_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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

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

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

Pide confirmación: primero dry_run: true (vista previa y confirm_token, que vale 10 minutos y una sola vez), después el mismo cuerpo con confirm_token. En unas pocas, solo con ciertos datos: la descripción dice cuándo. Por qué y cómo: Vista previa y confirmación.

Alcance: ad_creator:write
Permiso: Editar en el módulo
Tool del MCP: ad_creator_copies_generateEn la superficie completa; en la compacta, mb_execute_operation con id: "ad_creator.copies.generate".
Eventos que puede emitir: ad_creator.copy.generated

Costo declarado: hasta 8 lecturas y 4 escrituras por llamada (cuentan en el cupo diario). Toca una plataforma externa (ai): cuenta en el cupo de operaciones externas.

Parámetros

product_descriptionstringcuerporequerido

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

platformsarray<enum>cuerporequerido

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

namestringcuerpoopcional

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

toneenumcuerpoopcional

Writing tone. Ignored when custom_tone is given.

Valores: professional, casual, urgent, aspirational, informational · Por defecto: "professional"

custom_tonestringcuerpoopcional

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

variant_countintegercuerpoopcional

Variants per platform (1 to 10).

Por defecto: 3

key_benefitsstringcuerpoopcional

Benefits to highlight.

cta_directionstringcuerpoopcional

What the call to action should ask for.

landing_page_urlstringcuerpoopcional

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

landing_page_contextstringcuerpoopcional

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

Respuesta

copy_idstring

The new ad copy's id.

copyobject

The ad copy with its variants.

Errores

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

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar. En la práctica esta operación no se simula (toca otra plataforma): responde 409 sandbox_external_unavailable.

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

Delete an ad copy

ad_creator.copies.delete

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

Con una API key, este DELETE se ejecuta directo: el registro queda 30 días en la papelera y la respuesta trae su trash_item_id. Con un token OAuth, y por el MCP, pide dry_run → confirm_token.

Alcance: ad_creator:write y «Permitir eliminar» (ad_creator:delete en OAuth)
Permiso: Editar en el módulo
Tool del MCP: ad_creator_copies_deleteEn la superficie completa; en la compacta, mb_execute_operation con id: "ad_creator.copies.delete".
Eventos que puede emitir: ad_creator.copy.deleted

Costo declarado: hasta 1 lecturas y 2 escrituras por llamada (cuentan en el cupo diario).

Parámetros

copy_idstringrutarequerido

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

Respuesta

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.

Errores

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

Ejemplo

curl -X DELETE "https://api.mb-suite.com/v1/ad-creator/copies/{copy_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

curl -X DELETE "https://api.mb-suite.com/v1/ad-creator/copies/{copy_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"