API reference

JSON HTTP endpoints for programmatic integrations. Parameter detail lives in the topic guides: TikTok Shop filters, Meta ad library, Pinterest ads, Brands.

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

Authentication#

Send your key on every request as a header (preferred) or query param:

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

• Header: X-API-Key: <key> or Authorization: Bearer <key>
• Query (fallback): ?api_key=<key>
• Plan: requires an account with API access.
• Metering: 1 credit per request; 60 requests/minute. See Rate limits and Credits & billing.
• Response: JSON, { "success": true, ... }.

Create and copy keys on the in-app /api page.

Versioning#

Use /api/v1/... for all new work. Un-versioned aliases (/api/adlibrary, /api/store-tracker, /api/store-explorer) still hit the same metered surface, but not every /api/v1/X has an /api/X twin. Dashboard /api/tiktok-shop/* and /api/brands routes are session-only and behave differently — don't use them for API-key integrations.

MCP#

MCP endpoint: /mcp. Authenticate with connector OAuth (/mcp/oauth/authorize, /mcp/oauth/token, discovery at /.well-known/oauth-authorization-server/mcp) or the same X-API-Key header where the client allows custom headers. Full setup: MCP.

Programmatic API (API key + credits)#

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

Parameter detail per surface: Meta ad library, Pinterest ads, Magic AI, Store explorer, Brands. Brand detail tabs (/api/brands/ads, …) stay session-authenticated — not under /api/v1/brands/*.

Example — list tracked brands:

curl -sS -H "X-API-Key: $WH_API_KEY" "{origin}/api/v1/brands"

{
  "success": true,
  "data": [
    { "id": "8421", "name": "Allbirds", "domain": "allbirds.com", "active_ads": 142 },
    { "id": "8530", "name": "Gymshark", "domain": "gymshark.com", "active_ads": 318 }
  ],
  "total": 2
}

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.