WinningHunter HTTP API reference

This document lists JSON HTTP endpoints for programmatic integrations (API key + credits). Deep parameter docs live in the topic guides: TikTok Shop filters, Meta ad library, Brands.

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

Versioning#

• Canonical for new work: /api/v1/... — especially all /api/v1/tiktok-shop/* programmatic routes and /api/v1/brands, /api/v1/magic-ai, etc. An API key does not use the dashboard-only /api/tiktok-shop/* or /api/brands list routes the same way as /api/v1/....
• Aliases (still supported where registered): e.g. /api/adlibrary is the same metered surface as /api/v1/adlibrary; /api/store-tracker and /api/store-explorer likewise. Prefer /api/v1/... for new integrations — not every /api/v1/X has an /api/X twin.

Authentication#

1. API key (external / programmatic)#

Used by the endpoints listed under Programmatic API (API key) below, including all /api/v1/tiktok-shop/* routes. Prefer /api/v1/...; a few non-TikTok routes also have legacy /api/... aliases — see Versioning above.

• Header (preferred): X-API-Key: <your key>
  or Authorization: Bearer <your key>
• Query (fallback): ?api_key=<your key>
• Plan: An eligible account with API access is required after the key is resolved.
• Metering: Requests consume monthly API credits and are subject to a 60 requests / minute rate limit per user (see Rate limits and Credits & billing).
• Response type: JSON (Content-Type: application/json).

Keys are created on the in-app API page while you are logged in: open /api in the browser.

2. Browser session (dashboard)#

Most /api/* routes used by the web UI expect a logged-in session (cookies). Many also require an eligible subscription in addition to login. These are not the same as the public API key flow unless you send the same headers while logged in.

3. MCP connector auth (OAuth or API key)#

MCP endpoint: /mcp.

• Connector OAuth (recommended): For connector UIs that do not allow custom headers (for example Claude custom connector), use OAuth authorization code flow.
  • Authorization endpoint: /mcp/oauth/authorize
  • Token endpoint: /mcp/oauth/token
  • Discovery metadata: /.well-known/oauth-authorization-server/mcp
• Header API key (supported): X-API-Key: <your key> (or Authorization: Bearer <your key>) for clients that support custom headers (Cursor/Desktop configs, n8n, scripts).

Programmatic API (API key + credits)#

These routes share the same API key auth, credits, and rate limits as the rest of the programmatic surface.

Meta ad library (parameters, upgrade responses): Meta ad library. Magic AI (body, filters, pagination): Magic AI. Store explorer (search + visual search): Store explorer. Brands (API key list + session detail tabs): Brands & Brand tracker. In short, /api/v1/adlibrary accepts the same query shape as the in-app Meta ads search; /api/v1/brands returns the tracked-brands list for API keys. Brand detail tabs (/api/brands/ads, …) stay session-authenticated — not under /api/v1/brands/*.

Session-only helpers (browser login — not the metered JSON API):

TikTok Shop public API (/api/v1/tiktok-shop/*)#

All paths below are prefixed with /api/v1/tiktok-shop/. They accept GET, POST, or GET or POST as indicated. Behaviour matches the TikTok Shop areas in the web app, but each call is billed and authorized as the API key owner.

Filters & query bodies: See TikTok Shop · filters & query params for explore/count entity filters, pagination, aliases, and POST JSON merging. Detailed JSON bodies for shops, products, and creators are in TikTok Shop · details & aggregates.

GET or POST: both verbs are registered; use whichever matches your client.

Categories#

Shops#

Shop detail (aggregates & sub-resources)#

Creators#

Creator detail#

Videos (list)#

Products (list)#

Product detail#

Path parameters ({id})#

These URLs include {id} (alphanumeric, _, -). Prefix: /api/v1/tiktok-shop/.

Search, credits, trending, country#

Video transcript / AI helpers#

GET /api/v1/tiktok-shop/video/transcript#

Fetches a previously generated transcript from MongoDB (tiktok_video_transcriptions). Does not consume quota.

Response: JSON object { transcript, segments, script_analysis, similar_scripts }. All fields are null / [] when no transcript exists yet.

POST /api/v1/tiktok-shop/video/transcript/generate#

Generates (or returns a cached) transcript for a TikTok video using OpenAI Whisper. The result is persisted to MongoDB and returned. This endpoint is session-only — it requires a logged-in browser session; it is not accessible with just an API key.

Auth / plan gates (evaluated in order):

POST body (form-encoded or JSON):

The server first resolves the playback URL from MongoDB (videos.video_play_url_cdn). If not found, it falls back to video_cdn_url then video_url from the request body. Audio is extracted via ffmpeg, then sent to the Whisper API.

Success response:

{
  "success": true,
  "transcript": "Full transcript text...",
  "segments": [
    { "start": 0.0, "end": 2.5, "text": "Hello..." }
  ],
  "source": "generated",
  "script_generations_remaining": 14
}

Error responses (beyond the gate table above):

POST /api/v1/tiktok-shop/video/script/similar#

Generates a similar ad script based on an existing transcript using GPT. Consumes one monthly script-generation credit. Session-only.

POST body:

Success response:

{
  "success": true,
  "script": { "framework_used": "AIDA", "rows": [...] },
  "script_analysis": { "framework": {...}, "ad_pattern": {...}, "creative_strategies": [...] },
  "similar_scripts": [...],
  "script_generations_remaining": 13
}

Favorites#

Filter presets (TikTok Shop)#

Detailed query strings, POST JSON bodies, and filter aliases are documented in TikTok Shop · filters & query params.

Session-based JSON (dashboard)#

The in-app UI calls JSON endpoints under paths like /api/tiktok-shop/..., /api/product-detail/..., and /api/brands/... using your browser session, not the API key. For programmatic integrations, use /api/v1/... and the guides linked at the top of this page. Session brand tabs (/api/brands/ads, date filters, folders, boards, …) are covered in Brands & Brand tracker.