Search inspiration

Searches Pinterest or Cosmos by query and returns image urls with their title, author and page link, to use as visual references in generation. Page with cursor.

GET

/v1/brands/{brandId}/inspiration

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

source*string

pinterest for a wide pool of everyday and product imagery; cosmos for curated, design-led images (editorial, branding, type, art direction).

Value in"pinterest""cosmos"

query*string

What to look for, in a few words: a style, a subject, a mood or a kind of ad ("minimal skincare flat lay", "bold typographic poster").

Length1 <= length <= 200

limit?integer

Images to return, 1-30. Defaults to 12.

Range1 <= value <= 30

cursor?string

nextCursor from the previous page of the same search.

Length1 <= length <= 500

Response Body

Search inspiration

application/json

response

images*array<>

nextCursor*string|null

[key: string]?unknown

curl -X GET "https://example.com/v1/brands/0/inspiration?source=pinterest&query=string" \  -H "Authorization: Bearer koast_sk_..."

{  "images": [    {      "source": "pinterest",      "id": "string",      "imageUrl": "string",      "previewUrl": "string",      "title": "string",      "pageUrl": "string",      "author": "string",      "property1": null,      "property2": null    }  ],  "nextCursor": "string",  "property1": null,  "property2": null}

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