API 參考文件

Base URL

所有 API 請求都發送到這個根網址：

https://www.7275.com/api/v1

所有請求必須使用 HTTPS。HTTP 請求會被拒絕（不會重新導向）。

驗證

所有請求都需在 Authorization 標頭攜帶 Bearer token。可在儀表板「設定 → API Keys」產生。Key 分為 live 與 test 兩種環境，各自只能存取對應的環境。

curl https://www.7275.com/api/v1/accounts \
  -H "Authorization: Bearer dxk_live_...your-key..."

• live 環境 key 格式：以 dxk_live_ 開頭，共 64 個字元
• test 環境 key 格式：以 dxk_test_ 開頭，僅能存取 sandbox 帳戶
• 切勿在前端程式碼中直接使用 key —— 請透過你自己的後端代理
• 一旦外洩，請立即在儀表板撤銷並重新產生

從 Claude Desktop / Cursor 直接使用（MCP 伺服器）

我們發布了一個零相依的 Model Context Protocol 伺服器，讓 Claude Desktop、Cursor 等 MCP 用戶端直接讀取你的 AdWhiz 帳戶狀態。不必寫程式：複製設定、貼上 API key、重新啟動用戶端即可。

• 5 個唯讀工具：列出廣告帳戶、查看 AI 建議、查看本月節省金額、查看近期活動、查詢 API 配額
• 刻意尚未開放寫入工具（apply / pause）—— 待最佳化器結束 shadow mode、累積足夠的校準證據後再開放
• 單一 Node 18+ 腳本，不需 npm install，離線 / 實體隔離（airgapped）的電腦也能執行
• API key 不會離開你的電腦，所有請求皆以 HTTPS 直連 www.7275.com

將以下內容加入 Claude Desktop 的 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "adwhiz": {
      "command": "node",
      "args": ["/path/to/mcp-server/src/index.mjs"],
      "env": {
        "ADWHIZ_API_KEY": "dxk_live_..."
      }
    }
  }
}

完整安裝指南、Cursor 設定與疑難排解請見 GitHub： github.com/dexun-inc/adwhiz/mcp-server.

端點列表

v1 API 提供 13 個核心端點，涵蓋身分驗證、帳戶讀取、建議產生（套用功能暫未開放）、稽核紀錄、API key 管理、配額查詢與更新日誌。

請求範例

產生新一批三平台最佳化建議：

curl -X POST https://www.7275.com/api/v1/recommendations/generate \
  -H "Authorization: Bearer dxk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "ga-548-203-7184",
    "platforms": ["google_ads", "meta_ads", "tiktok_ads"],
    "window": "7d"
  }'

回應範例：

{
  "summary": "Pausing 3 high-CPA keywords and reallocating budget...",
  "recommendations": [
    {
      "id": "rec_001",
      "type": "pause_keyword",
      "target": { "accountId": "ga-548-203-7184", "keywordText": "wool socks" },
      "title": "Pause broad-match 'wool socks'",
      "reason": "7-day CPA $45.82 vs target $8",
      "expectedImpact": "Save ~$412/week",
      "confidence": "high"
    }
  ]
}

增量輪詢 /changelog

/api/v1/changelog 是公開端點（不需 API key），提供四種節省頻寬的方式：ETag + If-None-Match、Last-Modified + If-Modified-Since（curl -z）、以 ?since=YYYY-MM-DD 依日期篩選、以 ?limit=N 限制筆數。SDK 與 cron 腳本可組合使用，高頻輪詢也不必重複下載同一份 JSON。

# 1. First call — store the ETag (or Last-Modified) you get back.
curl -i 'https://www.7275.com/api/v1/changelog?limit=10'

# 2. Subsequent calls — pass the stored ETag.
#    Server returns 304 with empty body if nothing has shipped.
curl -i 'https://www.7275.com/api/v1/changelog?limit=10' \
  -H 'If-None-Match: "abc123..."'

# 3. Or anchor on a date instead of an ETag.
#    Only entries whose `date >= since` come back; pair with ?limit
#    to cap the response size.
curl 'https://www.7275.com/api/v1/changelog?since=2026-01-01&limit=20'

# 4. curl -z for Last-Modified-style conditional GET (no ETag needed):
curl -z 'Mon, 20 May 2026 00:00:00 GMT' \
  'https://www.7275.com/api/v1/changelog'

速率限制

依訂閱方案分級，避免衝擊上游 Google / Meta / TikTok API 配額：

• 專業版：每分鐘 120 次請求
• 商務版：每分鐘 600 次請求
• 企業版：客製（通常每分鐘 3,000 次請求）
• 超過限制時回傳 429 + retry-after 標頭，建議採用指數退避

錯誤碼

所有錯誤皆回傳 JSON，包含 error.code、error.message 與 error.request_id：