Reference

ads_draft_launch

Draft an ad launch

POST /api/v2/ads/launches

Makes a DRAFT only. Nothing launches or spends until a person opens review_url and presses Launch. Needs the ads:write scope.

Auth: API key (Authorization: Bearer)
Key scope needed: ads:write
Raw spec: https://app.diffusr.ai/api/v2/openapi.json

Request body (JSON)

Name	Type	Required	Description
`ad_account_id`	string	yes	An id from ads_list_accounts. Its platform (Meta or TikTok) and currency come with it.
`name`	string	no	The campaign’s name. Leave out for ” · ”.
`goal`	“traffic” \| “sales”	yes	“traffic” = visits to a site; “sales” = purchases, needs pixel_id.
`pixel_id`	string	no	Sales only: the Meta pixel / TikTok pixel code to count purchases with.
`daily_budget`	number	yes	What the whole launch may spend a day, in the account’s currency as people say it: 20 = $20 a day.
`start_at`	string	no	Leave out to start as soon as it’s approved.
`end_at`	string	no	Leave out to run until paused.
`countries`	string[]	yes	Two-letter country codes, like [“US”, “CA”].
`age_min`	integer	no	Default 18.
`age_max`	integer	no	Default 65.
`gender`	“all” \| “female” \| “male”	no	Default “all”.
`ads`	object[]	yes	One ad per video or picture, each with its own words.
`ads[].creative_id`	string	yes	An id from ads_list_creatives.
`ads[].text`	string	yes	The ad’s words over the video. TikTok allows 100 characters, Meta far more (first ~125 show).
`ads[].headline`	string	no	Meta only, optional: the bold line under the video.
`ads[].cta`	“learn_more” \| “shop_now” \| “sign_up” \| “download” \| “contact_us” \| “book_now”	yes	The button.
`ads[].url`	string	yes	Where the button goes. Must start with https://.

Example

cURL

curl -X POST "https://app.diffusr.ai/api/v2/ads/launches" \
  -H "Authorization: Bearer $DIFFUSR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ad_account_id": "ACCOUNT_ID",
  "goal": "traffic",
  "daily_budget": 20,
  "countries": [
    "US"
  ],
  "ads": [
    {
      "creative_id": "asset:CREATIVE_ID",
      "text": "Fresh and fizzy.",
      "cta": "shop_now",
      "url": "https://example.com"
    }
  ]
}'

Response

201 ApiAdsLaunch

A DRAFT with a review_url.

Name	Type	Required
`id`	string	yes
`status`	string	yes
`step`	string \| null	yes
`error`	string \| null	yes
`platform`	string	yes
`account`	string	yes
`name`	string	yes
`daily_budget`	number	yes
`currency`	string	yes
`review_url`	string \| null	yes
`open_url`	string \| null	yes
`live_at`	string \| null	yes
`next`	string	yes

Errors

Every error body is { error, code, request_id, ... }. All codes and what to do.

401: Missing, wrong, revoked or expired API key (code UNAUTHORIZED, KEY_REVOKED, KEY_EXPIRED).
403: The key may not do this (SCOPE_DENIED, MODEL_NOT_ALLOWED, TEST_MODE_UNSUPPORTED, ACCOUNT_BLOCKED, allowance_exceeded).
404: No such id, or it is not yours, or it belongs to the other key mode (NOT_FOUND).
422: The request is not valid (VALIDATION_FAILED, INVALID_JSON, PREFLIGHT_FAILED, CALLBACK_URL_INVALID, REFERENCE_*). `issues` lists each problem. Nothing was charged.
429: Too many requests or jobs (RATE_LIMITED, CONCURRENCY_LIMIT, UPLOAD_QUOTA, …). Wait Retry-After seconds, then retry.
500: Our fault (INTERNAL_ERROR). Quote request_id to support.
503: Paused or busy (API_PAUSED, MODEL_PAUSED, PROVIDER_PAUSED, PROVIDER_BUSY, UNAVAILABLE). Wait Retry-After seconds, then retry.

Charges

Free. Makes a draft only; nothing launches or spends until a person presses Launch in the app.