Openai Ads

OpenAI Ads Campaigns

Strategic guide for managing the OpenAI Advertiser API. All operations go through https://api.ads.openai.com/v1.

Requirements

• Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
• OpenAI Ads integration connected (an OpenAI Ads API key, scoped to one ad account) at https://app.hyperfx.ai/apps.

If openai_ads_ad_accounts_get is not found, the integration to connect is OpenAI Ads. After connecting, openai_ads_health_check() verifies the key — if connected=false, the API key is missing, invalid, or expired.

How to run the tools in this skill

Every tool in this skill is named by its canonical tool name. Run it with the call your surface gives you:

If a tool is not found: in Hyper chat, find its toolkit id with discover_toolkits and pass it to enable_toolkit. On an MCP client or the CLI, tell the user which integration to connect in Hyper.

Out of scope — defer to other skills

• Creative generation (ad imagery, copy) → ad-creative-generation / image-generation.
• Cross-platform campaign launches → use this skill for OpenAI Ads, then invoke meta-ads / google-ads separately.

Critical Rules

CRITICAL: Auth is bearer API-key auth, not OAuth. One Ads API key is scoped to exactly one ad account. There is no list ad accounts endpoint; openai_ads_ad_accounts_get returns the connected account for that key.

CRITICAL: All money values on inputs are integer micros. $1.00 = 1_000_000 micros. $50/day = 50_000_000. The daily_spend_limit_micros minimum is 1_000_000 ($1). The ad group max_bid_micros is capped at 100_000_000 ($100). Insights responses use plain floats in account currency, not micros.

CRITICAL: Always create campaigns, ad groups, and ads with status="paused". Surface what was created to the user, then activate using the dedicated activate endpoint after approval.

CRITICAL: Ads have review_status. New ads enter in_review and will not serve until review_status="approved", even if status="active".

CRITICAL: chat_card creatives require target_url and file_id. Upload the image first via openai_ads_images_upload, then pass the returned file_id to openai_ads_create. PNG, 1024x1024, <= 1 MB.

IMPORTANT: Creative types are chat_card and product_ad_template. Product-ad templates get image and destination URL from the selected product feed item, so they do not require file_id or target_url.

IMPORTANT: Campaign bidding_type can be impressions or clicks. Ad group billing_event_type can be impression or click.

Tool surface

Phase 1: Account Discovery

Run these after connect:

textCopy code
openai_ads_ad_accounts_get()
openai_ads_campaigns_list(limit=100)
openai_ads_list_custom_audiences(limit=100)
openai_ads_list_conversion_event_settings(limit=100)

The connect-time context builder may have already populated a cached snapshot. Prefer:

textCopy code
openai_ads_caches_get()

If success=False because the cache is empty, refresh once:

textCopy code
openai_ads_caches_refresh()

Phase 2: Plan and Confirm

Before creating anything, confirm with the user:

• Objective in plain language.
• Daily and/or lifetime budget in account currency.
• Target geos: simple country codes like ["US", "GB"], or location IDs from openai_ads_search_geo_locations.
• Any custom audiences to include or exclude.
• Whether this is a normal chat_card campaign or a product-feed campaign.
• Headline (title, <= 50 chars), body (<= 100 chars), and click-through URL for chat_card.
• One image asset for chat_card, either a public URL or a base64 blob.
• Max bid in micros (max_bid_micros; for example 2_000_000).
• Optional context_hints, short natural-language phrases that describe when the ad should show.
• Optional conversion event setting IDs to attach to the campaign.

If anything is missing, ask. Do not invent budgets, geos, or copy.

All reference files live in references/. Read them at references/<file> (e.g. references/campaign-creation.md).

Routing table

Safety Rules

Never:

• Pass dollar amounts directly. All money inputs are micros.
• Activate a campaign, ad group, ad, or account without explicit user approval.
• Skip image upload for a chat_card; it needs a real file_id.
• Use geo exclusions; use included geos and audience exclusions instead.
• Assume an ad is delivering just because status="active". Always check review_status.
• Treat archive as reversible.
• Promise paid traffic on a new ad. New ads sit in review_status="in_review" until OpenAI approves them.