不正対策 Data API

Data API は Web SDK のサーバーサイド版です。判定の取得、統計の集計、そして レポーティングと突き合わせ のためのデータエクスポートに使います——あなた自身のシステムが 合意できる数字を取り出すためのものです。

ベース URL

https://apiv1.captcha.la

認証

すべての Data API リクエストは、不正対策アプリケーションの認証情報をヘッダーとして送信して 認証します。

X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

WARNING

X-App-Secret は サーバーサイド専用 です。ブラウザ・モバイルアプリ・公開リポジトリに 決して露出させないでください。ページ SDK が使うのは公開用の appKey のみです。

エンドポイント

判定を取得する

単一アクセスの判定を取得します（例：特定のアクセスを突き合わせる場合）。

GET /v1/bot/verdict?cid=CID_OF_THE_VISIT
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

レスポンスの data は BotVerdict オブジェクトです。

{
  "code": 0,
  "data": {
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "consistency": { "ok": false },
    "degraded": false
  }
}

集計統計

時間範囲にわたるバケット単位の集計——合計、ボット比率、action/level 別の内訳——を取得し、 ダッシュボードや品質レポートに使います。

GET /v1/bot/stats?from=2026-06-01&to=2026-06-30
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

{
  "code": 0,
  "data": {
    "from": "2026-06-01",
    "to": "2026-06-30",
    "total": 124500,
    "bots": 18230,
    "bot_rate": 0.146,
    "by_action": { "record_only": 102100, "flag": 19800, "challenge": 2600 },
    "by_level":  { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 }
  }
}

エクスポート

オフラインでの突き合わせ用に、時間範囲ごとのアクセス単位の判定行をエクスポートします。

GET /v1/bot/export?from=2026-06-01&to=2026-06-30&format=csv
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

各行はアクセスの識別子、タイムスタンプ、判定フィールド（is_bot、score、level、action） を含むので、あなた自身のログに結合できます。

クリック単位の突き合わせ

有料トラフィックのシナリオでは、単一のアクセスを特定の配信済みクリックに紐づけ、2 者が それで精算できます。これはクリックトークンを使うもので、広告不正 ガイドで扱います。

次のステップ

• Verdict リファレンス — これらのエンドポイントが返すフィールド
• Web SDK — ページ上で判定を収集する