ウィジェットエンドポイント
これらのエンドポイントは SilentShield ウィジェットが呼び出します。通常はご自身で呼び出す必要はありません。ページ上で何が起きているかを追えるように記載しています。
Base URL: https://api.silentshield.io
POST/api/v1/telemetry/behavior
現在の操作の挙動データ（マウス、キーボード、スクロール）を送信し、nonce と判定を返します。フォームはこの nonce を `behavior_nonce` フィールドとして送信します。
Auth: APIキー（X-Api-Keyヘッダー）
Request Body:
{"ts": 1767225600000, "nonce": "bh_abc123", "event": "submit", "form_key": "contact", "feature_hash": "...", "metrics": {...}, "signature": "..."}Response:
{"id": "...", "nonce": "bh_abc123", "status": "queued", "verdict": "human", "score": 0.87, "captcha_solved": false, "challenge_required": false, "difficulty": "pass", "reason_codes": [], "action": "allow"}イベント `submit` が nonce とともに届いた時点で割り当てに計上されます — 送信ごとにちょうど 1 回です。`init`、`telemetry`、`form_detected` は計上されません。
POST/api/v1/captcha/challenge
判定が不確かだった場合に計算問題を要求します。ウィジェットが自動で行います。問題は一度きりで、nonce に紐づいています。
Auth: APIキー（X-Api-Keyヘッダー）
Request Body:
{"nonce": "bh_abc123", "difficulty": "medium"}Response:
{"ok": true, "challenge_id": "ch_xyz789", "a": 7, "op": "+", "b": 5}テレメトリの応答が `challenge_required: true` を返した場合にのみ必要です。
POST/api/v1/captcha/verified
解いた問題を送信します。サーバーがこのキー向けに発行した問題と答えが一致した場合にのみ、nonce が人間として記録されます。
Auth: APIキー（X-Api-Keyヘッダー）
Request Body:
{"challenge_id": "ch_xyz789", "answer": 12}Response:
{"ok": true} // 403: {"ok": false, "reason": "invalid_solution"}フェイルクローズド：誤答または期限切れは 403 と `reason: "invalid_solution"` を返します。問題は一度きりです。
POST/api/v1/captcha/verify-nonce
ウィジェットによって生成されたNonceを検証します。フォーム送信が正当であることを確認するために、サーバーからこのエンドポイントを呼び出してください。
Auth: APIキー（X-Api-Keyヘッダー）
Request Body:
{"nonce": "nonce_xyz789"}Response:
{"valid": true, "verdict": "human", "score": 0.92, "timestamp": "2025-01-15T10:30:00Z"}このエンドポイントはクォータにカウントされます。Nonceは使い捨てで、5分後に期限切れになります。