Search the reference library

Returns the winning public image ads from the reference library closest to a brief, or to the brand's saved style guide, closest first. Each ad carries its labels, tier and an image url on Koast storage.

GET

/v1/brands/{brandId}/reference-library

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

brief?string

What the brand sells, to whom, and how its ads should look, in a few sentences. The ads closest to it come back. Defaults to the brand's saved style guide.

Length1 <= length <= 1200

format?string

The layout device the ad is built on. Only ads with this format come back.

Value in"native_mockup""quiz_or_form""event_webinar""lead_magnet_mockup""before_after""comparison""problem_solution""advertorial""meme""note_or_letter""testimonial_quote""founder_expert""offer_banner""big_number""feature_callout""infographic""listicle""product_ui_screen""collection_grid""ugc_photo""text_statement""scene_photo""product_hero""other"

excludeRiskFlags?array<>

Leave out ads carrying any of these policy risks.

Itemsitems <= 10

minTier?string

Lowest winner tier to include. Defaults to STRONG.

Value in"TOP""STRONG""AVERAGE"

limit?integer

Ads to return, 1-12. Defaults to 4. Fewer come back when few are close to the brief.

Range1 <= value <= 12

Response Body

Search the reference library

application/json

response

ads*array<>

modelImages?array<>

Images shown to you after this call

Itemsitems <= 12

[key: string]?unknown

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

{  "ads": [    {      "id": -9007199254740991,      "source": "public",      "imageUrl": "string",      "advertiserName": "string",      "headline": "string",      "startedAt": "string",      "daysRunning": -9007199254740991,      "tier": "TOP",      "score": 0,      "industry": "string",      "offeringType": "string",      "format": "string",      "hero": "string",      "angle": "string",      "hookDevice": "string",      "offerType": "string",      "visualStyle": "string",      "tone": "string",      "textDensity": "string",      "funnelStage": "string",      "proofElements": [        "string"      ],      "riskFlags": [        "string"      ],      "niche": "string",      "description": "string",      "whyItWorks": "string",      "property1": null,      "property2": null    }  ],  "modelImages": [    {      "url": "string",      "label": "string",      "property1": null,      "property2": null    }  ],  "property1": null,  "property2": null}

Required scope: read. CLI: koast search-reference-library, see Reference Library commands. Authentication, headers, errors and pagination work the same on every operation. See Conventions.