API referenceLaunches

Create campaign launch

Creates an empty launch (batch) under the brand and returns its id. The launch holds no campaigns until you add one. title defaults to "Untitled Batch".

POST
/v1/brands/{brandId}/launches

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
title?string

Optional human title; defaults to "Untitled Batch" server-side.

Length1 <= length <= 200
description?string
Lengthlength <= 2000

Response Body

Create campaign launch

application/json
  1. response
id*string
title*string|null
brandId*number
brandName*string|null
accountId*string|null
curl -X POST "https://example.com/v1/brands/0/launches" \  -H "Authorization: Bearer koast_sk_..." \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "title": "string",  "brandId": 0,  "brandName": "string",  "accountId": "string"}

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

List Koast batches

Lists the brand's Koast launches (batches), drafts and published, with their status and campaign, ad set and ad counts. Filter by status or by a title substring with search.

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.