パブリッシャー収益監査 API

公開情報に基づくパブリッシャー収益のスクリーニングを実行し、Sulvo のレポートを取得し、承認済みパブリッシャーインベントリを管理できます。CLI と MCP サーバーが使用するものと同じ API です。

ホスト型ベース URL

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsCLI と MCP のセットアップ

基本

ベース URL

公開監査エンドポイントは、意図的に認証なしで利用できます。Sulvo アカウントのレポートとインベントリの呼び出しには、ダッシュボードで生成した API キーを使用します。

公開監査 API

POST

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-audits

Sulvo アカウント API

Bearer API キー

https://surge.sulvo.com/api

ホスト型 MCP エンドポイント

MCP

https://publisher-revenue-audit.sulvo.com/mcp

公開エンドポイント

収益監査を実行

このエンドポイントは、パブリッシャーのドメインを公開情報から概観するために使用します。応答は収益損失の証明でも、収益向上の保証でもありません。診断結果はパブリッシャー側のレポートと照らし合わせて検証してください。

cURL

curl -X POST https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-audits \
  -H "content-type: application/json" \
  -d '{
    "tool": "run_publisher_revenue_audit",
    "input": {
      "domain": "example.com",
      "vertical": "news",
      "options": {
        "format": "json",
        "compact": true,
        "maxPages": 2,
        "enablePageSpeed": true
      }
    }
  }'

項目	説明
input.domain	必須。パブリッシャーのドメインまたは公開ホスト。スキームのないドメインは HTTPS に正規化されます。プライベートな接続先、IP アドレスのみの指定、内部ホスト、標準外ポートは拒否されます。
input.vertical	任意。news、sports、entertainment、technology、education、gaming、other を指定できます。
input.metrics	任意。フィルレート、ビューアビリティ、平均 CPM、セッションあたりの収益、月間ページビュー、月間セッションなど、パブリッシャーがダッシュボードで提供するコンテキスト。
input.options	任意。format、compact、maxPages、includeEvidence、enableBrowser、includeScreenshots、enablePageSpeed、pageSpeedStrategy、concurrency、whiteLabel、partnerId など、出力と収集を制御する項目。

認証

アカウント API には Sulvo API キーを使用

Sulvo ダッシュボードのアカウント設定で API キーを生成します。Sulvo アカウント API リクエストでは、Bearer トークンとして送信してください。

Authorization ヘッダー

Authorization: Bearer $SULVO_API_KEY

reports:read

レポートのエクスポートと保存済みレポートの一覧表示に必要です。

reports:write

高度なレポートの作成、更新、実行、削除に必要です。

inventory:write

広告ユニットの作成と削除に必要です。アカウントの承認を受け、対象インベントリを所有している必要があります。

レポート

レポートのエンドポイントを参照

読み取り専用のレポートでは、Sulvo アカウント API のベース URL に対して GET リクエストを送信します。日付のみの値は UTC の 1 日全体の範囲として解釈されます。

レポートリクエスト

curl "https://surge.sulvo.com/api/v1/reports/by-date?start=2026-06-01&end=2026-06-07&domains=example.com" \
  -H "authorization: Bearer $SULVO_API_KEY" \
  -H "accept: application/json"

Method	Path	Notes
GET	/api/v1/reports/by-date	日次パフォーマンスの概要。date、domain、ad root、provider で絞り込めます。
GET	/api/v1/reports/by-date-and-ad-unit	広告ユニット別の日次パフォーマンス。
GET	/api/v1/reports/by-domain-and-ad-unit	ドメインと広告ユニット別のパフォーマンス内訳。
GET	/api/v1/reports/bot-filtering	アカウントのトラフィック品質を確認するためのボットフィルタリングレポート。
GET	/api/v1/reports/bot-scores	日付と関連ディメンション別のボットスコアレポート。
GET	/api/v1/reports/invalid-activity	無効なアクティビティのレポート。標準的な日付またはドメインのクエリは不要です。
GET	/api/v1/reports/direct-bidder-analysis	ダイレクトビッダーのレポート。directBidder が必須で、start と end を指定することもできます。
GET	/api/v1/inventory/ad-units-by-domain	ドメイン別の広告ユニットインベントリ。

共通クエリパラメーター：start、end、複数指定可能な domains、複数指定可能な adRoots、adProvider。ダイレクトビッダー分析では directBidder も必要です。

高度なレポート

スケジュール実行または即時配信のメールレポートを作成

高度なレポートは、即時に実行することも、スケジュールに沿って繰り返し実行することもできます。結果はインラインで返されず、メールで配信されます。

高度なレポートを保存

curl -X POST https://surge.sulvo.com/api/v2/reports/save-advanced-report \
  -H "authorization: Bearer $SULVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "reportType": "dimensions",
    "toAddress": "publisher@example.com",
    "immediateRun": true,
    "domains": ["example.com"],
    "dimensions": ["country", "device"],
    "start": "2026-06-01",
    "end": "2026-06-07"
  }'

Method	Path	Notes
GET	/api/v2/reports/advanced-reports	認証済みアカウントの保存済みの高度なレポートを一覧表示します。
POST	/api/v2/reports/save-advanced-report	高度なレポートを作成または更新します。reportType、toAddress、immediateRun と、adRoots または domains のいずれかの対象が必要です。
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	id を指定して、保存済みの高度なレポートを削除します。

レポートの種類

adUnit, dimensions, customData

ディメンション

country, device, os

頻度

daily, weekly, biweekly, monthly

インベントリ

承認済み広告ユニットを作成、削除

インベントリの書き込みには、承認済み Sulvo アカウントと、inventory:write スコープを持つ所有者発行の API キーが必要です。

広告ユニットを作成

curl -X PUT https://surge.sulvo.com/api/v2/inventory/unit \
  -H "authorization: Bearer $SULVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "domain": "example.com",
    "type": "display",
    "size": { "width": 300, "height": 250 }
  }'

Method	Path	Notes
PUT	/api/v2/inventory/unit	domain、type、任意の size、placement、custom name、focusedAd の設定を指定して、広告ユニットを 1 つ作成します。
PUT	/api/v2/inventory/interstitial-units	ドメインのデスクトップ向け、またはモバイル向けのインタースティシャル広告ユニットを作成します。
PUT	/api/v2/inventory/auto-sticky-units	ドメインのデスクトップ向けスティッキー広告ユニット、またはモバイル向けスティッキー広告ユニットを作成します。
DELETE	/api/v2/inventory/unit/{adId}	認証済みアカウントが所有する広告ユニットを削除します。

対応する広告ユニットの種類

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

エラー

エラー処理

2xx 以外の監査応答と Sulvo アカウント API の失敗時には、エージェントや CLI クライアント向けに設計された JSON 本文が返されます。

401

アカウント API の呼び出しに使用した API キーがないか、無効または期限切れです。公開監査エンドポイントにキーは必要ありません。

403

キーは認証されましたが、必要なスコープがない、アカウントが承認されていない、またはリソースが別のアカウントに属しています。

503 / 504

公開監査サービスが過負荷になっているか、監査がタイムアウトしました。時間をおいて再試行し、Retry-After が返された場合はその指示に従ってください。

監査エラーの形式

{
  "error": {
    "code": "audit_capacity_exceeded",
    "message": "Audit capacity is currently exhausted. Retry later."
  }
}

パッケージ化されたクライアントを使いますか？

npm パッケージと MCP のセットアップでは、これらのエンドポイントを代わりに呼び出し、対応する AI クライアントから同じ監査、レポート、インベントリのワークフローを利用できます。

セットアップを見る