Documentation

API Reference

REST endpoints, credits metering and auth

wordradar API（Phase 0）

Base URL：https://YOUR_DOMAIN（本地 http://localhost:8080）

鉴权与计量

  • API key：wr_ 开头（明文只创建时返回一次）。account 面板已上线（登录 → 用户菜单 → API Keys）；也可直接调接口： POST /api/v1/me/keys（body {name?}，默认 "default"、截 40 字）→ 返回 {key}；GET 列表；DELETE ?id=<uuid> 吊销
  • 请求头：Authorization: Bearer wr_...（或浏览器登录 session）
  • 限流：每用户 60s 窗口 120 次（/api/v1 与 /mcp 共享），超限 429+Retry-After
  • 计量：每端点标注 credits；扣费顺序=校验→查询成功→扣费（失败/400/503 不扣）；余额不足 402。ledger/pulse 免费
  • credits 来源：注册赠送已接（WORDRADAR_REG_CREDITS，deploy.sh 生产默认 50）、每日签到默认关（admin 后台两键）；内测期补发走 admin，详见 docs/pricing.md
  • Invalid params return 400 (e.g. an out-of-enum type) — never metered

REST 端点

端点方法credits参数
/api/v1/ledger/pulseGET免费—（最新期新词数）
/api/v1/ledger/wordsGET1type=新词|二次爆火|长期大词|存量、direction=AI|游戏|工具、site=站名（站群匹配）、limit≤200
/api/v1/kd/serpPOST1body {keyword?, results}（results 为 SERP 数组）（SERP 前十，喂入打分）
/api/v1/sites/latestGET1hosting=free|custom|all、min_points、limit
/api/v1/trends/:keywordGET2路径参数=关键词（读采集缓存，fetched_at 即新鲜度）
/api/v1/domains/:domain/timelineGET2RDAP+Wayback 实时
/api/v1/stripe/leaderboardGET1month=YYYYMM（缺省最新期）
/api/v1/me/keysGET/POST/DELETE—key 管理（session 登录）
/api/v1/configGET免费公开开关（invite_required/reg_credits/email_verification/social）
/api/healthzGET—健康+数据新鲜度
/ingest/bundlePOST—仅采集机（INGEST_TOKEN）

MCP（主分发面）

端点: POST https://<域名>/mcp   （streamable HTTP；GET→405，通知→202，DELETE→204）
tools: ledger_pulse / ledger_words / proxy_kd_score / site_radar_latest
       / trends_rising / domain_timeline / stripe_leaderboard / get_usage

客户端配置（Claude/Cursor 等）：

{ "mcpServers": { "wordradar": {
    "type": "http", "url": "https://<域名>/mcp",
    "headers": { "Authorization": "Bearer wr_..." } } } }

口径注（诚实声明）

  • proxy-kd 权重未校准（calibrate 待拟合），只做相对比较；判定线 <20 极易 / <40 可打 / <60 中等 / >=60 难
  • trends 是被动截获的采集缓存，非实时 API
  • ledger 首现=suggest 语料第一次出现，非趋势口径；类型判定 <3 期降级二分

Full scoring weights and data semantics: Methodology.

On this page

wordradar API（Phase 0）鉴权与计量REST 端点MCP（主分发面）口径注（诚实声明）