{"openapi":"3.1.0","info":{"title":"wordradar API","version":"1.0.0","summary":"Keyword radar for indie SEO: emerging-keyword ledger, HN site radar, SERP difficulty, Google Trends risers, Stripe referral boards.","description":"wordradar REST API (base path /api/v1). Machine surfaces: this spec, /llms.txt, MCP server at POST /mcp (Streamable HTTP).\n\n**Metering**: every endpoint below lists its credit cost via `x-credits` (0 = free). Billing order is validate → query succeeds → deduct; failed/400/503 calls are never metered. Insufficient balance returns 402.\n**Auth**: `Authorization: Bearer wr_...` API key (issue/revoke via /api/v1/me/keys) or a logged-in browser session. Anonymous calls work only on endpoints marked free (config, ledger/pulse, healthz).\n**Rate limit**: 120 requests per 60s window per user, shared across /api/v1 and /mcp; 429 carries Retry-After.\n**Credits source**: signup grant + daily check-in + Stripe top-up packs ($19/2,000 · $49/6,500 · $99/15,000, never expire).","contact":{"email":"support@wordradar.dev"},"license":{"name":"Proprietary","url":"https://www.wordradar.dev/legal/terms-of-service"}},"servers":[{"url":"https://www.wordradar.dev"}],"tags":[{"name":"ledger","description":"Emerging-keyword ledger (suggest-corpus first-seen)"},{"name":"radar","description":"HN site radar, trends risers, meme radar"},{"name":"kd","description":"SERP-composition difficulty scoring"},{"name":"stripe","description":"Stripe official referral boards"},{"name":"me","description":"API key self-service"},{"name":"meta","description":"Config and health (free, anonymous)"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/config":{"get":{"tags":["meta"],"operationId":"getConfig","summary":"Public config switches (free, anonymous)","x-credits":0,"security":[],"responses":{"200":{"description":"Invite gate, signup credits, email verification, social login switches","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"429":{"description":"Rate limited (in /api/v1 window); see Retry-After header"}}}},"/api/v1/ledger/pulse":{"get":{"tags":["ledger"],"operationId":"getLedgerPulse","summary":"New-keyword pulse for the latest ledger period (free, anonymous)","description":"Count of keywords first seen in the newest ledger period, plus corpus total. Same data as the MCP tool `ledger_pulse`.","x-credits":0,"security":[],"responses":{"200":{"description":"Pulse snapshot","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","required":["n_new","total_words","unit","source"],"properties":{"n_new":{"type":"integer"},"period":{"type":"string"},"total_words":{"type":"integer"},"unit":{"type":"string"},"source":{"type":"string"}}},"error":{"type":"string"}}}}}},"429":{"description":"Rate limited (in /api/v1 window); see Retry-After header"}}}},"/api/v1/ledger/words":{"get":{"tags":["ledger"],"operationId":"listLedgerWords","summary":"Query the keyword ledger","description":"Filter by type / direction / site-cluster match. Same data as the MCP tool `ledger_words`.","x-credits":1,"parameters":[{"name":"type","in":"query","description":"Keyword type (default: all)","schema":{"type":"string","enum":["新词","二次爆火","长期大词","存量"]}},{"name":"direction","in":"query","description":"Direction filter (default: all)","schema":{"type":"string","enum":["AI","游戏","工具"]}},{"name":"site","in":"query","description":"Site-cluster substring match","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Max rows (default 30, max 200)","schema":{"type":"integer","maximum":200,"default":30}}],"responses":{"200":{"description":"Matched ledger rows","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","required":["count","filters","words"],"properties":{"count":{"type":"integer"},"filters":{"type":"object","additionalProperties":true},"words":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"error":{"type":"string"}}}}}},"400":{"description":"Bad request: type out of enum (never metered)"},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}}},"/api/v1/ledger/verdicts":{"get":{"tags":["ledger"],"operationId":"getSeenVerdicts","summary":"Verdicts for up to 20 keywords","description":"words_seen verdicts (verdict / growth / note) for a comma-separated batch; keywords not in the ledger come back in `missing`.","x-credits":1,"parameters":[{"name":"keywords","in":"query","required":true,"description":"Comma-separated keywords (≤20 per batch)","schema":{"type":"string"}}],"responses":{"200":{"description":"Verdict rows plus missing list","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","required":["count","verdicts","missing"],"properties":{"count":{"type":"integer"},"verdicts":{"type":"array","items":{"type":"object","additionalProperties":true}},"missing":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}}},"error":{"type":"string"}}}}}},"400":{"description":"Bad request: empty keywords (never metered)"},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}}},"/api/v1/kd/serp":{"post":{"tags":["kd"],"operationId":"scoreSerp","summary":"Score a SERP top-10 composition (proxy KD 0-100)","description":"You supply the SERP results (scraped by you or your agent); the endpoint scores the composition. Weights are NOT calibrated — use for relative comparison only. Same scoring as the MCP tool `proxy_kd_score`.","x-credits":1,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"keyword":{"type":"string"},"results":{"type":"array","maxItems":10,"description":"SERP entries, order matters (top first)","items":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"domain":{"type":"string"},"title":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Score + verdict (<20 easy / <40 doable / <60 medium / >=60 hard)","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"400":{"description":"Bad request: empty results (never metered)"},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}}},"/api/v1/sites/latest":{"get":{"tags":["radar"],"operationId":"listLatestSites","summary":"Latest HN-launched sites (site radar)","description":"HN Algolia site-radar feed. Same data as the MCP tool `site_radar_latest`.","x-credits":1,"parameters":[{"name":"hosting","in":"query","description":"Hosting filter (default all)","schema":{"type":"string","enum":["free","custom","all"]}},{"name":"min_points","in":"query","description":"Minimum HN points","schema":{"type":"integer"}},{"name":"limit","in":"query","description":"Max rows (default 30)","schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"Site rows","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","required":["count","sites","source"],"properties":{"count":{"type":"integer"},"sites":{"type":"array","items":{"type":"object","additionalProperties":true}},"source":{"type":"string"}}},"error":{"type":"string"}}}}}},"400":{"description":"Bad request: hosting out of enum (never metered)"},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}}},"/api/v1/trends/{keyword}":{"get":{"tags":["radar"],"operationId":"getTrendsRising","summary":"Rising queries for a keyword (passive capture cache)","description":"Reads a periodically-collected cache, not a live Trends API: `fetched_at` is the freshness marker; unknown keywords return empty items. Same data as the MCP tool `trends_rising`.","x-credits":2,"parameters":[{"name":"keyword","in":"path","required":true,"description":"Keyword to look up (≤120 chars)","schema":{"type":"string"}}],"responses":{"200":{"description":"Rising queries snapshot","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true}},"fetched_at":{"type":"string"}}},"error":{"type":"string"}}}}}},"400":{"description":"Bad request: empty or >120-char keyword (never metered)"},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}}},"/api/v1/domains/{domain}/timeline":{"get":{"tags":["radar"],"operationId":"getDomainTimeline","summary":"Domain history (live RDAP × Wayback)","description":"LIVE third-party lookups (RDAP + Wayback), returns registration/renewal segments and ownership-change conclusions. Same data as the MCP tool `domain_timeline`.","x-credits":2,"parameters":[{"name":"domain","in":"path","required":true,"description":"Domain, e.g. example.com","schema":{"type":"string"}}],"responses":{"200":{"description":"Timeline segments and conclusions","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}}},"/api/v1/stripe/leaderboard":{"get":{"tags":["stripe"],"operationId":"getStripeLeaderboard","summary":"Stripe official referral leaderboard (monthly)","x-credits":1,"parameters":[{"name":"month","in":"query","description":"Month as YYYYMM (default: latest captured)","schema":{"type":"string","pattern":"^\\d{6}$"}}],"responses":{"200":{"description":"Leaderboard rows","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"400":{"description":"Bad request: month not YYYYMM (never metered)"},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}}},"/api/v1/stripe/domain/{domain}":{"get":{"tags":["stripe"],"operationId":"getStripeDomainHistory","summary":"Per-domain Stripe referral history (all months, ascending)","x-credits":1,"parameters":[{"name":"domain","in":"path","required":true,"description":"Domain, e.g. cursor.com","schema":{"type":"string"}}],"responses":{"200":{"description":"Monthly history (ascending)","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"history":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"error":{"type":"string"}}}}}},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}}},"/api/v1/tech/{domain}":{"get":{"tags":["radar"],"operationId":"lookupTechStack","summary":"Detect a website's tech stack (live fingerprint)","description":"Fetches the target homepage over HTTPS and matches ~210 fingerprint rules: CMS, site builders, frontend frameworks (incl. Next.js App Router, TanStack, SvelteKit), build tooling (Vite, Tailwind compiled), CDN/hosting, analytics, marketing pixels, payments, monitoring, plus dynamic extractors (WordPress theme & plugins, Shopify theme, meta generator, GA ID). Same engine as the free /tech-lookup page and the MCP tool `tech_lookup`. No history or change alerts.","x-credits":1,"parameters":[{"name":"domain","in":"path","required":true,"description":"Domain to scan, e.g. example.com","schema":{"type":"string"}}],"responses":{"200":{"description":"Detected technologies grouped by category","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","required":["domain","technologies"],"properties":{"domain":{"type":"string"},"final_url":{"type":"string"},"http_status":{"type":"integer"},"title":{"type":"string"},"technologies":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"category":{"type":"string"},"evidence":{"type":"string"}}}},"fetched_at":{"type":"string"},"cached":{"type":"boolean"}}},"error":{"type":"string"}}}}}},"400":{"description":"Bad request: invalid or blocked domain (never metered)"},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}}},"/api/v1/memes/{kw}":{"get":{"tags":["radar"],"operationId":"getMemeTerm","summary":"Meme-radar lookup for one term","description":"Monitored-layer capture (first seen / source / flag). Not-in-ledger returns found:false with a note, never an error. Same data as the MCP tool `meme_radar`.","x-credits":1,"parameters":[{"name":"kw","in":"path","required":true,"description":"Meme term (≤120 chars)","schema":{"type":"string"}}],"responses":{"200":{"description":"Hit, or {term, found:false, note}","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"term":{"type":"string"},"found":{"type":"boolean"},"note":{"type":"string"}}},"error":{"type":"string"}}}}}},"400":{"description":"Bad request: empty or >120-char kw (never metered)"},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}}},"/api/v1/me/alerts":{"get":{"tags":["me"],"operationId":"listMyAlerts","summary":"List my tracked-keyword alerts","description":"Keyword subscriptions for the RISING digest: when a tracked keyword appears in the latest Google Trends rising snapshot, one digest email per day (no hit, no email).","x-credits":0,"responses":{"200":{"description":"Subscription list","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}},"post":{"tags":["me"],"operationId":"trackKeyword","summary":"Track a keyword for RISING alerts (max 5)","x-credits":0,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["keyword"],"properties":{"keyword":{"type":"string","maxLength":120},"locale":{"type":"string","enum":["en","zh"]}}}}}},"responses":{"200":{"description":"Tracked","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"400":{"description":"Bad request: empty keyword (never metered)"},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"422":{"description":"Limit reached (max 5 keywords)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}},"delete":{"tags":["me"],"operationId":"untrackKeyword","summary":"Stop tracking a keyword","x-credits":0,"parameters":[{"name":"id","in":"query","required":true,"description":"Subscription id","schema":{"type":"string"}}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}}},"/api/v1/me/keys":{"get":{"tags":["me"],"operationId":"listMyKeys","summary":"List my API keys","x-credits":0,"responses":{"200":{"description":"Key list (hashes, never plaintext)","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}},"post":{"tags":["me"],"operationId":"createKey","summary":"Create an API key","description":"Plaintext key (wr_...) is returned exactly once at creation.","x-credits":0,"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Display name (default \"default\", max 40 chars)"}}}}}},"responses":{"200":{"description":"Created key","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}},"delete":{"tags":["me"],"operationId":"revokeKey","summary":"Revoke an API key","x-credits":0,"parameters":[{"name":"id","in":"query","required":true,"description":"Key id (uuid)","schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"401":{"description":"Missing/invalid credentials"},"402":{"description":"Insufficient credits (charged endpoints only)"},"429":{"description":"Rate limited (120 req/60s shared with /mcp); see Retry-After header"},"503":{"description":"Backing data not ready (never metered)"}}}},"/api/healthz":{"get":{"tags":["meta"],"operationId":"healthz","summary":"Health + data freshness (free, anonymous)","x-credits":0,"security":[],"responses":{"200":{"description":"Service health and DB freshness","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"429":{"description":"Rate limited; see Retry-After header"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key, wr_ prefix. Issue via POST /api/v1/me/keys (browser session also accepted)."}}}}