API referenceLaunches

Import live campaign

Wraps a campaign that exists on the ad platform but not in Koast (providerCampaignId) in a new launch, so it can be reported on and extended with new ad sets and ads that publish into the same campaign. Idempotent: if a launch already wraps that campaign, its campaignLaunchId is returned with alreadyExisted: true.

POST
/v1/brands/{brandId}/launches/import

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.

Header Parameters

Idempotency-Key?string

Retrying with the same key within 24 hours returns the first response without acting again.

Lengthlength <= 255

Request Body

application/json
  1. body
providerCampaignId*string

Campaign id on the ad platform (the raw id from listAccountCampaigns rows).

Length1 <= length
title?string

Optional batch title; defaults to the campaign name server-side.

Length1 <= length <= 200

Response Body

Import live campaign

application/json
  1. response
campaignLaunchId*string
alreadyExisted*boolean
title*string|null
curl -X POST "https://example.com/v1/brands/0/launches/import" \  -H "Authorization: Bearer koast_sk_..." \  -H "Content-Type: application/json" \  -d '{    "providerCampaignId": "string"  }'
{  "campaignLaunchId": "string",  "alreadyExisted": true,  "title": "string"}

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

Clone live campaign

Deep-copies the ad platform campaign providerCampaignId (ad sets, ads, copy and creatives) into count new launches as editable drafts with all platform ids stripped. Each clone gets its own launch, since a launch holds one campaign. Returns the new campaignLaunchId of each clone.

Delete batch or pipeline card

Permanently deletes the launch (or pipeline card) and every campaign, ad set and ad it holds in Koast. Anything already published to the ad platform is untouched and keeps running and spending; pause it first if that is the intent.