Getting started

Make your first authenticated request in five minutes.

1. Use an account with API access.
2. Copy your key from /api.
3. Send it as an Clé X-API en-tête.
4. Call /api/v1/tiktok-shop/crédits to confirm it works.

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

Get your API key#

Open /api while logged in. The page shows your key (click to copy), monthly credit usage, a request log, and a Regenerate button. Regenerating invalidates the old key immediately.

Verify your key#

GET /api/v1/tiktok-shop/credits is read-only and the cheapest way to confirm auth and metering. It costs 1 credit.

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

{
  "success": true,
  "credits": {
    "used": 142,
    "limit": 20000,
    "remaining": 19858
  }
}

A 200 avec Content-Type: application/json means you're set. On an error: 401 is a bad/missing key (Authentification), 403 means the account has no API access, 429 is rate or credit limits (Limites de débit).

Run a search#

Most integrations start with /api/v1/tiktok-shop/products/explore. It accepts OBTENIR ou PUBLICATION and returns a paginated product list.

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, "min_revenue": 50000 }'

{
  "success": true,
  "data": [
    {
      "id": "1729384756102394",
      "title": "Vitamin C Brightening Serum",
      "price": 24.9,
      "revenue": 312540,
      "sales": 12550,
      "country": "US"
    }
  ],
  "page": 1,
  "total": 20
}

Utilisation PUBLICATION JSON for large filter sets — long query strings can hit 414 URL trop longue. Both verbs accept the same parameters; see the TikTok Shop filters reference.

Review usage#

Each successful request costs 1 credit and counts toward the per-minute rate limit. Refresh /api (or call /api/usage while logged in) to see updated usage.

Next steps#

• API reference — the full route list.
• TikTok Shop filters — explore/count parameters.
• MCP setup — call WinningHunter as tools from Claude, Cursor, ChatGPT, Gemini, or n8n.