Belgeler
Ctrl+K Arama Alt+[Alt+] Kılavuzlar
API anahtarını al

Kılavuzlar

Başlangıç

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-Anahtarı header, call /api/v1/tiktok-shop/krediler to verify the connection, then build using the API kılavuzu.

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

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 AL ve YAYIN 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
  }'

Kullanım JSON Gönder 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:

  • Kullanım /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 kredi 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-Anahtarı in the client config.
  • Endpoint: Streamable HTTP at https://YOUR_HOST/mcp (see the guide for exact JSON).
  • Metering: each successful araçlar/çağrı = 1 kredi; MCP has its kendi per-minute cap (see MCP guide).

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

What to read next