Swap creatives

Replaces the creatives on the ad set's ads with creativeIds, in order, keeping each ad's copy. Existing ads are edited in place; extra creatives clone an existing ad, and surplus ads are removed from the Koast tree and listed in removedAdIds.

POST

/v1/brands/{brandId}/launches/{launchId}/ad-sets/{adsetNodeId}/creatives/swap

Authorization

bearerAuth

headerAuthorizationBearer <token>

An organization API key (koast_sk_…) with the API surface enabled, or an OAuth access token issued by Koast (koast_at_…) whose audience covers this API. REST access requires an active Agency plan.

Path Parameters

brandId*integer

The brand the request acts on. Every brand-scoped resource lives under its brand.

launchId*string

The campaign launch (batch) id.

adsetNodeId*string

Koast adset node id whose ads should carry the new creatives.

Length1 <= length

Header Parameters

Request Body

application/json

body

creativeIds*array<number>

Numeric creative IDs to place on the ad set, in order. Copy on existing ads is preserved.

Items1 <= items <= 100

Response Body

Swap creatives

application/json

response

adsetId*string

Koast adset node id the creatives were placed on.

ads*array<>

The ads the ad set carries after the swap, each with the creative it now runs.

removedAdIds*array<string>

Ids of surplus ads deleted from the Koast tree because fewer creatives were supplied than the ad set had ads. Empty when none were deleted.

validation?

[key: string]?unknown

curl -X POST "https://example.com/v1/brands/0/launches/string/ad-sets/string/creatives/swap" \  -H "Authorization: Bearer koast_sk_..." \  -H "Content-Type: application/json" \  -d '{    "creativeIds": [      0    ]  }'

{  "adsetId": "string",  "ads": [    {      "adId": "string",      "creativeId": 0,      "property1": null,      "property2": null    }  ],  "removedAdIds": [    "string"  ],  "validation": {    "valid": true,    "issueCount": 0,    "issues": [      "string"    ],    "property1": null,    "property2": null  },  "property1": null,  "property2": null}

Required scope: write. CLI: koast swap-creatives, see Launches commands. Authentication, headers, errors and pagination work the same on every operation. See Conventions.