# WinningHunter documentation

> Public HTML docs for the WinningHunter HTTP API and MCP (Model Context Protocol). `/docs` is the developer hub; prefix every path below with your deployment's HTTPS origin (the same host that serves the app and `/api`), e.g. `https://YOUR_HOST/docs/mcp`.

## For AI agents (copy-paste prompts)

- `/docs/mcp` — MCP user guide: **Claude Desktop**, **Cursor** (`mcp.json`), **ChatGPT**, **Gemini**, and **n8n** (MCP Client / MCP Client Tool) + **“Copy for your AI agent”** (`#copy-for-your-ai-agent`).
- `/docs/mcp-tools-reference` — Flat tool list; section **“Copy blocks for AI agents”** has one large plain-text manifest (`#copy-blocks-for-ai-agents`).

**28** read-only MCP tools at **`/mcp`** (Streamable HTTP). Writes (TikTok Shop favorites, presets, transcripts, etc.) are **not** on MCP — use REST **`/api/v1/tiktok-shop/*`**.

## Guides

- `/docs/getting-started` — API access, API key from `/api`, first `curl`, optional MCP.
- `/docs/authentication` — `X-API-Key`, Bearer, team keys, regeneration.
- `/docs/credits-billing` — Monthly credits, what counts, resets.
- `/docs/errors` — HTTP status codes and meanings.
- `/docs/rate-limits` — REST burst limits and backoff.
- `/docs/time-windows` — `period`, date ranges, filters.
- `/docs/troubleshooting` — Common failures.

## API · Overview

- `/docs/api` — Auth, access, programmatic HTTP surface overview.

## API · TikTok Shop

- `/docs/tiktok-shop-filters` — Explore/count filters, periods, MCP mapping.
- `/docs/tiktok-shop-suggestions` — Autocomplete / suggestions HTTP API.

## API · Ad library

- `/docs/adlibrary` — `GET /api/v1/adlibrary` (and alias), parameters, discovery routes, MCP `search_facebook_ads` + `find_winning_products`.

## API · Brands

- `/docs/brands` — `GET /api/v1/brands`, session `/api/brands/*` detail routes, MCP `list_tracked_brands`.

## API · Exploding Topics

- `/docs/trends` — `/trends` (Exploding Topics) vs TikTok Shop trending; MCP tools.

## API · Shopify

- `/docs/shopify-store-explorer` — Store explorer REST + `search_shopify_stores` MCP.

## MCP

- `/docs/mcp` — MCP setup.
- `/docs/mcp-tools-reference` — MCP tool list.

## Index

- `/docs` — Developer hub for REST API, MCP, credits, rate limits, and domain guides.

## Repository

Public `/docs/*` pages are generated from customer Markdown under `winninghunter/docs/`; the published slug list is `winninghunter/docs/nav.json`. Paths in this file match that registry.