API 文件 v1

三種傳 token 方式（擇一）：

# 推薦
curl ... -H "Authorization: Bearer cuh_xxxxxxxxxx"

# Header
curl ... -H "X-API-Key: cuh_xxxxxxxxxx"

# Query string (僅測試用，會留 log)
curl "https://中文網址.tw/api/v1/lookup?q=...&api_key=cuh_xxxxx"

每個回應含 rate limit headers：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1778900000  # unix epoch

查單一中文網址，DB hit 回完整 metadata，miss 走 WHOIS fallback。

GET https://中文網址.tw/api/v1/lookup?q=購物.台灣

200 OK
{
  "ok": true,
  "zhUrl": "購物.台灣",
  "punycode": "xn--g2xv08c.xn--kpry57d",
  "status": "REGISTERED",   // REGISTERED | AVAILABLE | UNKNOWN
  "source": "db",            // db | whois | whois-error
  "site": {                  // 只在 source=db 時存在
    "title": "...",
    "description": "...",
    "targetUrl": "https://...",
    "thumbnailUrl": "https://...",
    "category": { "slug": "ecommerce", "nameZh": "電商購物", "emoji": "🛒" }
  }
}

列目錄。Cursor pagination。

• category — 分類 slug（選）
• status — REGISTERED / AVAILABLE / UNKNOWN（選）
• limit — 1-200（預設 50）
• cursor — 下一頁 cursor id

GET https://中文網址.tw/api/v1/sites?category=ecommerce&limit=20

200 OK
{
  "ok": true,
  "count": 20,
  "nextCursor": "cmp7mwoof...",
  "items": [
    {
      "zhUrl": "購物.台灣",
      "punycode": "xn--g2xv08c.xn--kpry57d",
      "title": "...",
      "description": "...",
      "status": "REGISTERED",
      "category": { "slug": "ecommerce", "nameZh": "電商購物" },
      "updatedAt": "2026-05-16T..."
    }
  ]
}

列已發布文章；帶 ?slug=... 取單篇含內文。

• slug — 取單篇（含 contentMd）
• limit — 1-100（預設 20）
• cursor — cursor id
• body=1 — 列表 mode 也帶 contentMd

GET https://中文網址.tw/api/v1/articles?limit=5

200 OK
{
  "ok": true,
  "count": 5,
  "nextCursor": "cmp7...",
  "items": [
    { "slug": "...", "title": "...", "summary": "...", "tags": [...], "publishedAt": "..." }
  ]
}

熱搜 top + 近期新註冊。

• hours — window 1-720（預設 24）
• limit — top N (1-100, 預設 20)

GET https://中文網址.tw/api/v1/trending?hours=168&limit=10

200 OK
{
  "ok": true,
  "windowHours": 168,
  "topLookups": [{ "zhUrl": "購物.台灣", "count": 3 }, ...],
  "newlyRegistered": [
    { "zhUrl": "...", "title": "...", "category": {...}, "registeredAt": "..." }
  ]
}

列 8 分類 + 各分類站台數。

GET https://中文網址.tw/api/v1/categories

200 OK
{
  "ok": true,
  "items": [
    { "slug": "ecommerce", "nameZh": "電商購物", "emoji": "🛒", "count": 7 },
    ...
  ]
}

• 不可重新散佈整個目錄當競品。
• 必須註明 「Powered by 中文網址.tw」（網頁 footer 或 about 頁）。
• 商用 / 高量請談 PRO。
• 濫用會被停用，無事先通知。