Upload creative
Store an image in the active brand's creative library and return its creativeId, ready to put in an ad with addAds, distributeCreative or swapCreatives.
Tool name: upload-creative.
Store an image in the active brand's creative library and return its creativeId, ready to put in an ad with addAds, distributeCreative or swapCreatives. Give it a public https imageUrl and Koast downloads and re-hosts it. Uploading the same bytes twice returns the creative that already exists rather than duplicating it. Images only, videos are uploaded on the Creatives page. This does NOT create or change any ad; it only adds to the library.
When to use
Get an image into Koast so it can be used in an ad. Use it whenever the user gives you an image URL and wants an ad made from it. If the user attached a file to the chat instead, you cannot read its bytes, ask for a link, or tell them to drop it on the Koast creative gallery (listCreatives), which uploads it for them. It writes to the library, so it is unavailable in plan mode and refused to a read-only credential.
Access
| Property | Value |
|---|---|
| Required scope | write |
| Publishes | No |
| Read-only | No |
| Destructive | No |
| Idempotent | Yes |
| Open world | Yes |
Input
| Field | Type | Required | Description |
|---|---|---|---|
imageUrl | string | No | 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. |
fileData | string | No | 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. At most 13333338 characters. |
contentType | string | No | Media type of fileData. Required with fileData, ignored with imageUrl. One of image/jpeg, image/png, image/webp, image/gif. |
fileName | string | No | File name to store it under. Required with fileData; defaults to the url's own name otherwise. At most 200 characters. |
name | string | No | Display name for the creative. Defaults to the file name. At most 200 characters. |
Output
| Field | Type | Required | Description |
|---|---|---|---|
creativeId | integer | Yes | Pass this as creativeId to addAds, distributeCreative or swapCreatives. |
name | string | Yes | |
url | string | null | Yes | |
previewUrl | string | null | Yes | 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 | Yes | |
height | number | null | Yes | |
reused | boolean | Yes | True when the brand already held these exact bytes, so the existing creative was returned instead of a duplicate being made. |
REST equivalent
POST /v1/brands/{brandId}/creatives, Upload creative. CLI: koast upload-creative.