API 参考

Base URL

所有 API 请求都发到这个根地址：

https://api.7275.com/v1

所有请求必须使用 HTTPS。HTTP 请求会被拒绝（不重定向）。

认证

所有请求需在 Authorization 头携带 Bearer token。在 dashboard「设置 → API Keys」生成。Key 分 live 和 test 两种环境，分别只能访问对应账户。

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

• live 环境 key 格式：dxk_live_ 开头，64 位字符
• test 环境 key 格式：dxk_test_ 开头，可访问 sandbox 账户
• 前端代码中绝不要直接使用 key —— 请通过你自己的后端代理
• 泄露立即在 dashboard 撤销并重新生成

Claude Desktop / Cursor 直连（MCP server）

我们发布了一个零依赖的 Model Context Protocol server，让 Claude Desktop、Cursor 这类 MCP 客户端直接读取你的 AdWhiz 账户状态。不用写代码，复制配置 + 填 API key 就能用。

• 5 个 read-only 工具：列出广告账户、看 AI 推荐、看本月省钱数、看最近活动、查 API 配额
• 故意不暴露写操作（apply / pause）—— 等优化器出 shadow mode + calibration evidence 凑齐再开
• 纯 Node 18+ 单脚本，零 npm install，离线 / airgapped 机器也能跑
• API key 不离开你本机，所有请求 HTTPS 直连 app.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://api.7275.com/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://app.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://app.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://app.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://app.7275.com/api/v1/changelog'

速率限制

基于订阅套餐分级，避免对上游 Google / Meta / TikTok API 配额冲击：

• 专业版：120 请求 / 分钟
• 商业版：600 请求 / 分钟
• 企业版：定制（典型 3000 请求 / 分钟）
• 超过限制返回 429 + retry-after 头，建议指数退避

错误码

所有错误返回 JSON，包含 error.code、error.message、error.request_id：