SilentShield

Widget Endpoints

The SilentShield widget calls these endpoints. You normally do not call them yourself — they are documented so you can follow what happens on your page.

Base URL: https://api.silentshield.io

POST/api/v1/telemetry/behavior

Sends the behavioural data of the current interaction (mouse, keyboard, scrolling) and returns the nonce together with a verdict. Your form submits that nonce as the field `behavior_nonce`.

Auth: API Key (X-Api-Key header)

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"}

Counts against your quota as soon as the event `submit` arrives with a nonce — exactly once per submission. `init`, `telemetry` and `form_detected` do not count.

POST/api/v1/captcha/challenge

Requests an arithmetic challenge when the verdict was uncertain. The widget does this on its own; the challenge is single-use and bound to the nonce.

Auth: API Key (X-Api-Key header)

Request Body:

{"nonce": "bh_abc123", "difficulty": "medium"}

Response:

{"ok": true, "challenge_id": "ch_xyz789", "a": 7, "op": "+", "b": 5}

Only needed when the telemetry response reported `challenge_required: true`.

POST/api/v1/captcha/verified

Submits the solved challenge. The nonce is marked human only when the answer matches a challenge the server issued for this key.

Auth: API Key (X-Api-Key header)

Request Body:

{"challenge_id": "ch_xyz789", "answer": 12}

Response:

{"ok": true}   //  403: {"ok": false, "reason": "invalid_solution"}

Fail-closed: a wrong or expired answer returns 403 with `reason: "invalid_solution"`. The challenge is single-use.

POST/api/v1/captcha/verify-nonce

Verifies a nonce generated by the widget. Call this from your server to confirm the form submission is legitimate.

Auth: API Key (X-Api-Key header)

Request Body:

{"nonce": "nonce_xyz789"}

Response:

{"valid": true, "verdict": "human", "score": 0.92, "timestamp": "2025-01-15T10:30:00Z"}

This endpoint counts toward your quota. Nonces are single-use and expire after 5 minutes.