Copies

List ad copies

ad_creator.copies.list

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.

Scope

ad_creator:read

Permission

View the module

MCP tool

ad_creator_copies_listOn the full surface; on the compact one, mb_execute_operation with id: "ad_creator.copies.list".

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

Parameters

Response

Errors

Example

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

Get one ad copy

ad_creator.copies.get

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.

Scope

ad_creator:read

Permission

View the module

MCP tool

ad_creator_copies_getOn the full surface; on the compact one, mb_execute_operation with id: "ad_creator.copies.get".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/ad-creator/copies/{copy_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/ad-creator/copies/{copy_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Generate ad copies (AI)

ad_creator.copies.generate

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.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

ad_creator:write

Permission

Edit in the module

MCP tool

ad_creator_copies_generateOn the full surface; on the compact one, mb_execute_operation with id: "ad_creator.copies.generate".

Events it can emit

ad_creator.copy.generated

Declared cost: up to 8 reads and 4 writes per call (they count against the daily quota). Touches an external platform (ai): it counts against the external operations quota.

Parameters

Response

Errors

Example

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

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. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.

Delete an ad copy

ad_creator.copies.delete

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.

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

ad_creator:write and “Allow deletions” (ad_creator:delete in OAuth)

Permission

Edit in the module

MCP tool

ad_creator_copies_deleteOn the full surface; on the compact one, mb_execute_operation with id: "ad_creator.copies.delete".

Events it can emit

ad_creator.copy.deleted

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

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/ad-creator/copies/{copy_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/ad-creator/copies/{copy_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"