Upload creative

Stores an image in the brand's creative library and returns its creativeId. Pass exactly one of imageUrl (a public https URL that Koast downloads and re-hosts) or fileData (base64 bytes, with contentType and fileName). Uploading bytes the brand already holds returns the existing creative with reused: true. Images only; no ad is created or changed.

POST

/v1/brands/{brandId}/creatives

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

Request Body

application/json

body

imageUrl?string

Public https url of the image to store. Koast downloads it and re-hosts it, so a link that later expires does not rot the ad. Use this whenever the user gives you a link.

Length1 <= length

fileData?string

Standard base64 of the image bytes, with NO data-url prefix. Intended for the Koast creative gallery, which reads a dropped file and sends it here. Do not attempt to write this yourself, if the user attached an image to the chat, say you cannot read its bytes and ask for a link or for them to drop it in the gallery.

Length1 <= length <= 13333338

contentType?string

Media type of fileData. Required with fileData, ignored with imageUrl.

Value in"image/jpeg""image/png""image/webp""image/gif"

fileName?string

File name to store it under. Required with fileData; defaults to the url's own name otherwise.

Length1 <= length <= 200

name?string

Display name for the creative. Defaults to the file name.

Length1 <= length <= 200

Response Body

Upload creative

application/json

response

creativeId*integer

Pass this as creativeId to addAds, distributeCreative or swapCreatives.

Range-9007199254740991 <= value <= 9007199254740991

name*string

url*string|null

previewUrl*|

The url a Koast view may render, filtered through the same host list that writes the view CSP. Null means the asset is stored somewhere the iframe may not load, the creative still works in an ad.

width*number|null

height*number|null

reused*boolean

True when the brand already held these exact bytes, so the existing creative was returned instead of a duplicate being made.

[key: string]?unknown

curl -X POST "https://example.com/v1/brands/0/creatives" \  -H "Authorization: Bearer koast_sk_..." \  -H "Content-Type: application/json" \  -d '{}'

{  "creativeId": -9007199254740991,  "name": "string",  "url": "string",  "previewUrl": "string",  "width": 0,  "height": 0,  "reused": true,  "property1": null,  "property2": null}

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