API リファレンス

ベース URL

すべての API リクエストはこのルートに送信します：

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

HTTPS は必須です。HTTP リクエストは拒否されます（リダイレクトはされません）。

認証

すべてのリクエストで、Authorization ヘッダーに Bearer トークンが必要です。ダッシュボードの「設定 → API Keys」で発行してください。キーには live と test の 2 種類があり、それぞれ自分の環境にしかアクセスできません。

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

• live キーの形式：dxk_live_ で始まる 64 文字
• test キーの形式：dxk_test_ で始まり、sandbox アカウントのみにアクセス可能
• フロントエンドのコードでキーを直接使わないでください —— 自社のバックエンド経由でプロキシしてください
• 漏洩した場合は、ダッシュボードで直ちに失効させて再発行してください

Claude Desktop / Cursor から直接使う（MCP サーバー）

依存関係ゼロの Model Context Protocol サーバーを公開しています。Claude Desktop や Cursor などの MCP クライアントから、AdWhiz の状態を直接読み取れます。コードは不要です —— 設定ブロックをコピーし、API キーを貼り付けて、クライアントを再起動するだけです。

• 読み取り専用の 5 ツール：広告アカウント一覧、AI の提案表示、今月の節約額、最近のアクティビティ、API クォータの確認
• 書き込み系ツール（apply / pause）は意図的にまだ公開していません —— オプティマイザーが shadow mode を抜け、制御に必要なキャリブレーションの根拠がそろってから公開します
• Node 18+ の単一スクリプト。npm install 不要。オフライン / エアギャップ環境のマシンでも問題なく動作します
• API キーがお使いのマシンの外に出ることはありません。すべてのリクエストは 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 キー管理、クォータの確認、変更履歴フィードをカバーします。

リクエスト例

3 プラットフォームの最適化提案を新たに生成します：

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 キー不要）で、帯域を節約する 4 つの方法に対応しています：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 ヘッダーが返ります —— 指数バックオフを推奨します

エラーコード

すべてのエラーは error.code、error.message、error.request_id を含む JSON で返されます：