API reference

JSON HTTP endpoints for programmatic integrations. Each resource below has its own page with parameters, example requests, and response tabs.

Replace {origin} with your site base URL (e.g. https://app.winninghunter.com).

How to browse

Pick a resource below, or open API in the sidebar — each page has params and example responses. This page is the full route index.

Jump to a resource

Meta Ad LibrarySearch Facebook and Instagram ads with dashboard filters. Pinterest AdsKeyword, country, engagement, and date filters. TikTok AdsSearch TikTok ads and creatives with dashboard filters. Google AdsGlobal browse and store-scoped creatives. Magic AISimilar-ad discovery from text or image input. LandersPremium Explorer landing page library and favorites. Saved AdsFolders, boards, and programmatic save. BrandsList, track, boards, and analyze Meta brands. NotificationsInbox and brand digest notification prefs. TikTok ShopExplore and count products, shops, creators, and videos. TikTok Shop DetailsShop, product, creator, and video detail endpoints. TikTok SuggestionsAutocomplete for categories, shops, creators, and products. Shopify ExplorerSearch stores and visual similarity search. Shopify TrackerTracked store count and plan cap. TrendsExploding Topics search, detail, and autocomplete.

Auth

Prefer X-API-Key: $WH_API_KEY. Also accepted: Authorization: Bearer …, ?api_key=…. Requires Basic plan or higher. 1 credit per metered call; 60/min. See Authentication, Credits, Errors.

curl -sS -H "X-API-Key: $WH_API_KEY" "{origin}/api/v1/credits"

{
  "success": true,
  "credits": {
    "used": 142,
    "limit": 20000,
    "remaining": 19858,
    "addon_remaining": 500,
    "total_remaining": 20358
  }
}

Versioning

Use /api/v1/... for new work. A few un-versioned aliases (/api/adlibrary, /api/store-tracker, /api/store-explorer) hit the same metered surface. Legacy dashboard paths without the v1 prefix mirror the same handlers but are session-oriented — prefer /api/v1/... with an API key.

Programmatic routes

Method	Path	Purpose
GET	`/api/v1/credits`	Programmatic credit balance
GET	`/api/v1/adlibrary`	Meta (Facebook / Instagram) ads
GET	`/api/v1/pinterest-ads`	Pinterest ads
GET	`/api/v1/tiktok-ads`	TikTok ads — see TikTok Ads
GET	`/api/v1/tiktok-ads/{id}`	Single TikTok ad detail
GET	`/api/v1/google-ads`	Google Ads creatives
GET	`/api/v1/store/google-ads`	Store-scoped Google Ads — see Google Ads
GET	`/api/v1/store/google-ads/*`	Store Google Ads count, detail, overview, advertiser, creative
POST	`/api/v1/magic-ai`	Magic AI similar ads
POST	`/api/v1/landers/explore`	Landers library — see Landers
GET	`/api/v1/landers/favorites`	Lander favorites list
POST	`/api/v1/landers/favorites/toggle`	Toggle lander favorite
GET/POST	`/api/v1/saved-ads/*`	Saved ads folders, boards, save — see Saved Ads
POST	`/api/v1/trends/*`	Exploding Topics — see Trends
GET	`/api/v1/brands`	Tracked brands list
GET	`/api/v1/brands/*`	Brand tracker tabs — see Brands
GET/POST	`/api/v1/notifications/*`	Product inbox — see Notifications
GET	`/api/v1/store-tracker`	Tracked Shopify store count
POST	`/api/v1/store-explorer`	Shopify store explorer
POST	`/api/v1/store-explorer/visual-search`	Similar stores by image
GET	`/api/v1/ad-transcript`	Stored ad transcript
POST	`/api/v1/ad-transcript-generate`	Generate ad transcript
POST	`/api/v1/ad-similar-script-generate`	Similar ad script

Pagination (ad library, Pinterest, TikTok ads, Magic AI): opaque scroll token; optional limit on first request (default 20, max 50).

Brand tracker (`/api/v1/brands/*`)

Full docs: Brands. Highlights:

Method	Path	Purpose
GET	`/api/v1/brands`	List tracked brands
GET	`/api/v1/brands/ads`	Paginated ads for a page (`id`)
POST	`/api/v1/brands/follow`	Track a Meta page
POST	`/api/v1/brands/unfollow`	Untrack
GET	`/api/v1/brands/overview-cards`	KPI summary
GET	`/api/v1/brands/ad-copies`	Copy insights
GET	`/api/v1/brands/notifications/prefs`	Digest email prefs
GET	`/api/v1/brands/folders-with-boards`	Brand boards tree
POST	`/api/v1/brands/create-folder`	Create brand folder
POST	`/api/v1/brands/add-to-board`	Add brand to board

Plus 20+ insight tabs (hooks, landing pages, personas, …), board/folder CRUD, and share links — all 1 credit each.

Notifications (`/api/v1/notifications/*`)

Method	Path	Purpose
GET	`/api/v1/notifications`	Inbox list
GET	`/api/v1/notifications/unread-count`	Unread count
POST	`/api/v1/notifications/mark-read`	Mark ids read
POST	`/api/v1/notifications/mark-all-read`	Mark all read

See Notifications. Brand digest prefs live under /api/v1/brands/notifications/*.

Session helpers (browser login)

Method	Path	Notes
GET	`/api`	API key page (HTML)
POST	`/api/regenerate`	Regenerate key
GET	`/api/usage`	Usage JSON
GET	`/api/logs`	Request logs

TikTok Shop (`/api/v1/tiktok-shop/`)

Same auth, credits, and rate limits. Prefix every path below with /api/v1/tiktok-shop/. Filters: TikTok Shop · Details: TikTok Shop Details.

HTTP	Path suffix	Purpose
GET or POST	`categories/explore`	List / search categories
GET or POST	`categories/count`	Count matches
GET	`categories/hierarchy`	Category tree
GET	`categories/layers`	By layer depth
GET	`categories/summary`	One category summary
GET	`categories/history`	Category history
GET	`categories/siblings`	Sibling categories
POST	`categories/top-products`	Top products
POST	`categories/top-shops`	Top shops
POST	`categories/top-creators`	Top creators

Shops

HTTP	Path suffix	Purpose
GET or POST	`shops/explore`	List / search shops
GET or POST	`shops/count`	Count shops
GET	`shops/summary`	Shop summary
POST	`shops/products`	Shop products
GET	`shops/details`	Shop profile
GET	`shop-details`	Alias of `shops/details`

Shop detail

HTTP	Path suffix	Purpose
POST	`shop-detail`	Full shop detail
POST	`shop-detail/total`	Aggregates
POST	`shop-detail/extraTotal`	Extra aggregates
POST	`shop-detail/history`	Metrics over time
POST	`shop-detail/searchCooperativeCreators`	Cooperative creators
POST	`shop-detail/product/queryList`	Product list
POST	`shop-detail/searchVideos`	Shop videos
POST	`shop-detail/searchNewProducts`	New products
POST	`shop-detail/salesStrategy/selfPromotion`	Self-promotion
POST	`shop-detail/salesStrategy/affiliate`	Affiliate strategy

Creators

HTTP	Path suffix	Purpose
GET or POST	`creators/explore`	List / search creators
GET or POST	`creators/count`	Count creators
POST	`creator-detail`	Creator detail
POST	`creator-detail/total`	Aggregates
POST	`creator-detail/history`	History
POST	`creator-detail/searchShopList`	Linked shops
POST	`creator-detail/searchCooperativeShops`	Cooperative shops
POST	`creator-detail/searchProducts`	Products
POST	`creator-detail/video/queryList`	Videos

Videos & products

HTTP	Path suffix	Purpose
GET or POST	`videos/explore`	List / search videos
GET or POST	`videos/count`	Count videos
GET	`products`	Simple product list
GET or POST	`products/explore`	List / search products
GET or POST	`products/count`	Count products
POST	`product-detail`	Product detail (POST)
GET	`product-details`	Product details (GET)
POST	`product-detail/total`	Aggregates
POST	`product-detail/history`	History
POST	`product-detail/salesTrend`	Sales trend
POST	`product-detail/creator/queryList`	Creators
POST	`product-detail/video/queryList`	Videos
POST	`product-detail/searchCreators`	Search creators
POST	`product-detail/searchVideos`	Search videos
POST	`product-detail/creator/getConversionRadio`	Conversion metrics
GET	`product-other-visits`	Related visits
GET	`category-visit-events`	Category visit counts
GET	`detail-visit-events`	Detail visit counts

Path `{id}` routes

HTTP	Path pattern	Purpose
GET	`product-detail/{id}`	Product by ID
GET	`products/{id}/sales-channel`	Sales channels
GET	`videos/{id}`	Video by ID
GET	`videos/{id}/metrics`	Video metrics
GET	`videos/{id}/products`	Products in video
GET	`videos/{id}/history`	Video history
GET	`videos/{id}/similar`	Similar videos
GET	`creators/{id}/history`	Creator history

Search, credits, trending

HTTP	Path suffix	Purpose
GET	`credits`	TikTok Shop search credits (`credits_remaining`) — not the programmatic pool
GET	`trending`	Trending products
GET	`search`	Product search
GET	`suggestions`	Autocomplete
POST	`request-country`	Country preference

Transcripts / AI / favorites / presets

HTTP	Path suffix	Purpose
GET	`video/transcript`	Fetch transcript
POST	`video/transcript/generate`	Generate transcript
POST	`video/script/similar`	Similar script
GET	`favorites`	List favorites
POST	`favorites/toggle`	Toggle favorite
POST	`favorites/add`	Add favorite
POST	`favorites/remove`	Remove favorite
POST	`favorites/check`	Check favorite
GET	`filter-presets`	List presets
POST	`filter-presets/save`	Save preset
POST	`filter-presets/update`	Update preset
POST	`filter-presets/delete`	Delete preset

MCP: /mcp with OAuth or X-API-Key. See MCP.

API reference

Jump to a resource#

Auth#

Versioning#

Programmatic routes#

Brand tracker (/api/v1/brands/*)#

Notifications (/api/v1/notifications/*)#

Session helpers (browser login)#

TikTok Shop (/api/v1/tiktok-shop/)#

Categories#

Shops#

Shop detail#

Creators#

Videos & products#

Path {id} routes#

Search, credits, trending#

Transcripts / AI / favorites / presets#