List creatives

Lists the images and videos in the brand's creative library, newest first, with the creativeId used when attaching a creative to an ad. Filter with search and kind, or pass creativeIds to fetch a specific set. A creative with ready: false is a video still processing and cannot be attached yet.

GET

/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.

Query Parameters

search?string

Filter by creative or file name. Omit to list everything, newest first.

Length1 <= length <= 200

kind?string

Narrow to images or to videos. Defaults to ALL.

Value in"ALL""IMAGES""VIDEOS"

creativeIds?array<>

Look up an explicit set of creative ids instead of browsing. This is also what the gallery sends when a user picks creatives in it, so the ids reach you.

Itemsitems <= 60

page?integer

1-based page. Defaults to 1.

Range1 <= value <= 9007199254740991

limit?integer

Page size.

Range1 <= value <= 100

Default50

cursor?string

Opaque cursor from the previous page's nextCursor. Omit for the first page.

Response Body

List creatives

application/json

response

creatives*array<>

total*integer

Range-9007199254740991 <= value <= 9007199254740991

page*integer

Range-9007199254740991 <= value <= 9007199254740991

pages*integer

Range-9007199254740991 <= value <= 9007199254740991

selection*boolean

True when the call named explicit creativeIds, i.e. it is a selection rather than a browse.

nextCursor*|

Pass as cursor to read the next page. Null when there is no next page.

[key: string]?unknown

curl -X GET "https://example.com/v1/brands/0/creatives" \  -H "Authorization: Bearer koast_sk_..."

{  "creatives": [    {      "creativeId": -9007199254740991,      "name": "string",      "kind": "image",      "url": "string",      "previewUrl": "string",      "previewable": true,      "width": 0,      "height": 0,      "aspectRatio": "string",      "durationSeconds": 0,      "sizeBytes": 0,      "isImported": true,      "ready": true,      "createdAt": "string",      "property1": null,      "property2": null    }  ],  "total": -9007199254740991,  "page": -9007199254740991,  "pages": -9007199254740991,  "selection": true,  "nextCursor": "string",  "property1": null,  "property2": null}

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