Getting started

Five steps to your first authenticated request.

1. Use an account with API access (Basic plan or higher).
2. Open /api while logged in and copy the plaintext key immediately (shown once on first create / regenerate — later visits show a masked wh_••••…).
3. Send it as X-API-Key.
4. Call GET /api/v1/credits to confirm auth and metering.
5. Run one TikTok Shop explore search.

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

Get your API key#

Open /api while logged in. On first visit or after regenerate, copy the plaintext key (wh_ + hex) immediately — it cannot be shown again. Regenerating invalidates the old key immediately.

Verify with credits#

GET /api/v1/credits returns the monthly programmatic API pool. It costs 1 credit.

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
  }
}

limit depends on plan: 100 (Basic), 20000 (Standard+), 0 otherwise. total_remaining = monthly remaining + addon_remaining.

401 = bad/missing key · 403 = no API access · 429 = rate limit or credits exhausted — see Errors.

Run a TikTok Shop search#

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "{origin}/api/v1/tiktok-shop/products/explore" \
  -d '{ "country": "US", "period": "30d", "limit": 20, "page": 1 }'

Gebruik POST JSON for large filter sets. See Filters in TikTok Shop.

Next#