Extended | RequestGuard Docs

SDK (Preferred)

bun add @requestguard/js

import RequestGuard from "@requestguard/js";

RequestGuard.captcha({
  el: ".rg-captcha",
  theme: "dark",
  onVerify: (result) => {
    document.getElementById("contact-send").disabled = !result.success;
  }
});

<div class="rg-captcha"></div>
<button id="contact-send" disabled>Send</button>

Script Tag

<script src="https://requestguard.com/js/captcha.js"></script>
<div class="rg-captcha"></div>
<button id="contact-send" disabled>Send</button>
<script>
  RequestGuard.captcha({
    el: ".rg-captcha",
    theme: "dark",
    onVerify: (result) => {
      document.getElementById("contact-send").disabled = !result.success;
    }
  });
</script>

What `onVerify` Means

When the user completes the challenge, the widget exchanges the proof‑of‑work solution for a short‑lived verification token from RequestGuard, then the SDK verifies it in the background.

onVerify fires after the SDK’s background check and gives you { success, token, challenge_ts }. You can trust success for UX (enable buttons, auto‑submit). Tokens expire quickly and are single‑use by default, which prevents replay.

Invisible Mode

Use invisible mode to run verification in the background without showing the widget.

RequestGuard.captcha({
  el: ".rg-captcha",
  invisible: true,
  onVerify: (result) => {
    if (result.success) {
      document.getElementById("contact-send").disabled = false;
    }
  }
});

Language Override

Language is auto-detected from the browser by default. To force a specific language:

RequestGuard.captcha({
  el: ".rg-captcha",
  language: "de"
});

Verify Tokens Server-Side (Optional)

The SDK already verifies tokens with RequestGuard in the background. If you want stricter control, you can disable autoVerify and verify on your own backend.

POST https://requestguard.com/api/captcha/siteverify

{
  "response": "<token-from-client>"
}

Response

{
  "success": true,
  "challenge_ts": "2026-01-27T10:11:12.000Z"
}

Options

Option	Type	Description
`el`	string \| HTMLElement	Target element (required)
`theme`	”auto” \| “light” \| “dark”	Widget theme (default: `auto`)
`invisible`	boolean	Hide the widget and auto-run verification (default: `false`)
`onVerify`	function	Called after background verification
`onError`	function	Called when the widget reports an error
`onReset`	function	Called when the widget resets
`fieldName`	string	Hidden input name (default: `rg-captcha-token`)
`autoVerify`	boolean	Verify token automatically in the background (default: `true`)
`verifyUrl`	string	Override verification endpoint
`api`	string	Override API base used by the widget (default: `/api/captcha/`)
`host`	string	Override RequestGuard host for self-hosting
`origin`	string	Override origin sent to RequestGuard (default: `window.location.origin`)
`instanceId`	string	Custom instance ID for multi-captcha pages
`title`	string	Iframe title for accessibility
`width`	string	Iframe width (default: `100%`)
`height`	string	Iframe height (default: `90px`)
`borderRadius`	string	Iframe border radius (default: `12px`)

Listening for Verification

You can listen via the instance or a DOM event:

<script>
  const instance = RequestGuard.captcha({ el: ".rg-captcha" });
  instance.on("verified", (event) => {
    console.log("verified token", event.detail.token);
  });

  document.addEventListener("rg:captcha:verified", (event) => {
    console.log("verified token", event.detail.token);
  });
</script>

API Endpoints

Challenge

POST https://requestguard.com/api/captcha/challenge

Returns challenge data and a challenge token for the widget.

Redeem

POST https://requestguard.com/api/captcha/redeem

Body:

{
  "token": "<challenge-token>",
  "solutions": [123, 456, 789]
}

Returns a short-lived verification token.

Site Verify

POST https://requestguard.com/api/captcha/siteverify