Docs
Ctrl+K Search Alt+[Alt+] Guides
Get API key

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 X-API-Key header, call /api/v1/tiktok-shop/credits to verify the connection, then build using the API reference.

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/credits is recommended — it returns your current credit balance and costs 1 credit.

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:

  • 401 Unauthorized — the header is missing, malformed, or the key is incorrect. See Authentication.
  • 403 Forbidden — API access is not enabled for this account; resolve from the dashboard (plan / billing).
  • 429 — see Rate limits and Credits & billing.

4. Execute a search query

Most developers start with /api/v1/tiktok-shop/products/explore. It supports both GET and POST 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
  }'

Use 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:

  • Use /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 credit 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 X-API-Key in the client config.
  • Endpoint: Streamable HTTP at https://YOUR_HOST/mcp (see the guide for exact JSON).
  • Metering: each successful tools/call = 1 credit; MCP has its own per-minute cap (see MCP guide).

Open MCP (Claude, Cursor, ChatGPT, Gemini, n8n) — you get ready-to-paste claude_desktop_config.json and 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, Trends. Site manifest for crawlers: /llms.txt.

What to read next