Create launch
Create ads PAUSED — campaign, ad set and ads — and record the launch.
PAUSED is the draft: nothing spends until POST /api/v1/launches/{launchId}/activate. Each creative is uploaded from a public https URL, every Advantage+ enhancement is opted out, and ad names must be canonical (id__locale__format__persona__angle__concept__variant). With a launch preset only creatives is required: campaign, ad_set and copy default to the preset's (preset_id, or the workspace default). A retry without an Idempotency-Key reuses an ad set the failed attempt already made, but can still upload twice — send the key.
Requires a key with write scope or higher.
MCP: meta_launch_ads.
bearerAuthAuthorizationBearer <token>An API key from Settings → API keys, sent as Authorization: Bearer rsk_….
Authorization has two independent axes.
The scope is ranked — a key satisfies any requirement at or below its own tier:
read— every GET.write— launch ads PAUSED, sync, pull history, edit thresholds, Values, briefs, tests, swipes and research.admin— everythingwritecan. No operation requires more thanwritetoday.
There is no approve scope. It was a rung once; it is not one now, and a key requested with it is rejected.
The approval grant (can_approve) is a separate boolean, not a rung. Changing spend on Meta — activating a launch, pausing or resuming ads, retargeting an ad set, or rebuilding a launch's live creative — needs write and the grant. Keeping them on separate axes is what makes the review gate a control rather than a convention: a key that may propose is not automatically a key that may approve its own proposal.
A key reaches the one workspace — one Meta ad account — it was minted in, and stops working when the operator who minted it leaves the workspace. The same key authenticates the MCP endpoint (/api/mcp) for a headless agent, with the same scope and grant.
Idempotency-Key?stringAny unique string up to 256 characters. A retry with the same key and body replays the first success (Idempotency-Replay: true) instead of doing the work twice; the same key with a different body is refused.
length <= 256application/json- body
preset_id?stringThe launch preset that fills whatever this call leaves out — campaign, adSet, copy. Omitted: the workspace default preset, used only when one of the three is missing.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidcampaign?|Omit to take the preset's: its campaign by name, or a new CBO campaign.
ad_set?|Omit for a new ad set with the preset's audience and destination.
creatives*array<||>1 <= items <= 20copy?Omit to take the preset's: the angle's approved messaging (when the preset writes from the recipe) or its fallback copy, with its destination.
page_id?stringThe Facebook Page the ads publish under. Omit for the workspace default.
^\d+$pixel_id?stringThe Pixel for conversion tracking. Omit for the workspace default.
^\d+$test_id?stringThe Test these ads run for: the launch and its ads are linked to it. Still PAUSED.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidbrief_id?stringThe brief these ads were made from: the launch is linked to it, and the brief goes live when an ad first delivers. Still PAUSED.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidCreated. The body is the tool's own result — the same payload the MCP tool returns.
application/json- response
curl -X POST 'https://winandscale.com/api/v1/launches' \ -H 'Content-Type: application/json' \ -d '{ "creatives": [ { "name": "string", "media_url": "http://example.com" } ]}'{}