Docs
Ctrl+K Rechercher Alt+[Alt+] Guides
Obtenir une clé API

Guides

Getting started

This guide walks through the first call against the WinningHunter HTTP API. Five minutes, end to end.

TL;DR: Use an account that includes API access, retrieve your key from /api, include it as an Clé X-API header, call /api/v1/tiktok-shop/crédits to verify the connection, then build using the Référence API.

1. Account access

The HTTP API is available on eligible WinningHunter accounts. If your key is valid but requests are denied with HTTP 403, the signed-in account may not include API access—check plan and billing from your dashboard after signing in.

2. Obtain your API key

Open /api while logged in. The page displays:

  • Your API key (header value, click to copy).
  • Your monthly credit usage (out of 20,000).
  • A request log with status codes and timestamps.
  • A regenerate button — old keys stop working immediately upon regeneration.

The same screen also lists the available TikTok Shop HTTP endpoints for quick reference.

3. Make your first request

Use a read-only endpoint to verify authentication and credit metering. /api/v1/tiktok-shop/crédits is recommended — it returns your current credit balance and costs 1 crédit.

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

A successful response is JSON, with an HTTP 200 status and Content-Type: application/json. If you receive an error:

4. Execute a search query

Most developers start with /api/v1/tiktok-shop/products/explore. It supports both OBTENIR et PUBLICATION methods and returns a paginated list of products.

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

Utilisation POST JSON when your filter set is large — long query strings can result in a 414 URI Too Long error. Both methods accept the same parameters. Filter names, aliases, defaults, and pagination are documented in the TikTok Shop filters reference.

4b. Call Magic AI (optional)

Magic AI is also available on the API-key surface at POST /api/v1/magic-ai.

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
  -X POST "{origin}/api/v1/magic-ai" \
  --data-urlencode "text=Find winning beauty products for US women 25-34"

Important:

  • Utilisation /api/v1/magic-ai for API-key integrations.
  • /api/magic-ai (without v1) is the dashboard session route used by the web app.

5. Review usage

After making several calls, refresh the /api page (or call /api/usage while logged in) — your usage chart and remaining credits will reflect the new activity. Each successful request consumes 1 crédit and is counted toward the per-minute rate limit.

6. (Optional) Use MCP from an AI client

Claude Desktop, Cursor, ChatGPT (with MCP connectors), Gemini (where Google enables remote MCP), and n8n (MCP Client / MCP Client Tool) can call WinningHunter as tools instead of hand-writing curl.

  • Same requirements: an account with API access and the same API key as above — sent as Clé X-API in the client config.
  • Endpoint: Streamable HTTP at https://YOUR_HOST/mcp (see the guide for exact JSON).
  • Metering: each successful outils/appel = 1 crédit; MCP has its propre per-minute cap (see MCP guide).

Open MCP (Claude, Cursor, ChatGPT, Gemini, n8n) — you get ready-to-paste claude_desktop_config.json et mcp.json snippets, ChatGPT and Gemini connector notes, n8n setup steps, and agent instruction text. Tool names and arguments: MCP · tools reference. Product context: TikTok Shop filters, Tendances. Site manifest for crawlers: /llms.txt.

What to read next