AdnovaDocs
Ad Launcher

Create a launch

Submit one or more ads for asynchronous launch. Returns immediately with a batchId (status pending); poll Get launch at the retryAfterSeconds cadence until terminal. Supply an Idempotency-Key header to make retries safe. This write endpoint uses a stricter rate-limit bucket than reads. Each ad is also validated against its selected ad sets and rejected with 400 on a mismatch: an unknown ad set ID; a regulated-location ad set selected alongside others; selected ad sets with mixed conversion locations (Web & App, App-conversion, App-promotion); an ad type the ad set's conversion location doesn't allow; a missing webLink on a creative ad whose ad set is not App-conversion or App-promotion; an App-conversion webLink that is not the ad set's app-store URL; or adSchedule when any selected ad set's campaign objective is not OUTCOME_SALES. See Ad set compatibility.

POST
/meta/launches

Authentication

authentication
api-key<token>

Create an API key from the Adnova dashboard (Account integrations). Pass the key value in the api-key request header on every call.

In: header

Header Parameters

x-workspace-id*string

Workspace the request operates in. Get it from List workspaces.

Length1 <= length
x-org-id*string

Organization context (required on every endpoint). For lookup endpoints the org is derived from the ad account in the URL, so any org id you have access to is accepted.

Length1 <= length
Idempotency-Key?string

Optional. Any string ≤64 chars. Retries with the same key return the original response for 24h.

Lengthlength <= 64

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.adnova.ai/ad-launcher/v1/meta/launches" \  -H "x-workspace-id: string" \  -H "x-org-id: string" \  -H "Content-Type: application/json" \  -d '{    "adAccountId": "01H8Y4...",    "platform": "meta",    "ads": [      {        "adName": "Hero Carousel — Spring Sale",        "adSets": [          "123456789012345"        ],        "creativeDetails": {          "groupType": "carousel",          "creatives": [            {              "_id": "01H8YA...",              "cardTitle": "Spring Sale — 40% Off",              "cardDescription": "Hand-picked styles, limited time",              "webLink": "https://example.com/spring-sale",              "productHeadline": "Best of Spring",              "productDescription": "Featured products from the spring collection"            }          ]        },        "adProfiles": {          "facebook_page_id": "123456789012345",          "instagram_account_id": "987654321098765",          "page_backed_instagram_account_id": null        },        "cta": "SHOP_NOW",        "defaultPrimaryText": "Big sale this spring — up to 40% off",        "primaryTextVariations": [          "Limited-time spring sale, up to 40% off",          "Spring fashion sale ends Sunday"        ],        "defaultHeadline": "Up to 40% off",        "headlineVariations": [          "40% off spring collection",          "Spring sale — shop now"        ],        "adDescription": "Free shipping on orders over $50.",        "webLink": "https://example.com/spring-sale",        "displayLink": "example.com/spring",        "utm": "utm_source=facebook&utm_medium=cpc&utm_campaign=spring_sale",        "productSetData": {          "business_id": "1029384756",          "catalog_id": "456789012345",          "product_set_id": "678901234567"        },        "productSetId": "678901234567",        "leadGenFormId": null,        "adSchedule": {          "startDate": "2026-06-01T00:00:00Z",          "endDate": "2026-06-30T23:59:59Z"        },        "promoCodeDetails": {          "type": "manual",          "manualCodes": [            "SPRING40",            "EARLYBIRD"          ]        }      }    ]  }'
{
  "batchId": "01H8YB...",
  "status": "pending",
  "retryAfterSeconds": 10
}
{
  "error": {
    "code": "string",
    "message": "string"
  },
  "message": "string"
}
{
  "error": {
    "code": "string",
    "message": "string"
  },
  "message": "string"
}
{
  "error": {
    "code": "string",
    "message": "string"
  },
  "message": "string"
}
{
  "error": {
    "code": "string",
    "message": "string"
  },
  "message": "string"
}
{
  "error": {
    "code": "string",
    "message": "string"
  },
  "message": "string"
}