Documentation

Everything needed to drop Katcha into a site: the script tag, the verify endpoint, and how to test both before going live.

Quickstart

Add the widget script to any page with a form you want protected, then verify the resulting token on your server before acting on the submission.

index.html

<script src="https://cdn.katcha.eu/v1/widget.js"
        data-site-key="YOUR_SITE_KEY"
        async></script>

<form id="signup" action="/submit" method="post">
  <input name="email" type="email">
  <button type="submit">Sign up</button>
</form>

The script watches the page silently. On submit, it attaches a signed katcha_token field to the form. You don't need to touch your form's markup or validation beyond reading that field server-side.

Configuration

Pass options as attributes on the script tag, or per-form via data-katcha-* attributes on an individual form.

Attribute	Values	Default
`data-site-key`	string, required	None
`data-mode`	`invisible` · `widget`	`invisible`
`data-threshold`	`low` · `medium` · `high`	`medium`
`data-lang`	ISO language code	browser default

widget mode renders a small visible checkbox for sites that want an explicit "verified" moment; invisible mode (default) shows nothing unless a session looks suspicious.

Server-side verification

Never trust the token on its own. Confirm it server-side before treating a submission as human-verified.

request

POST https://api.katcha.eu/v1/verify
Content-Type: application/json

{
  "token": "<katcha_token from the form>",
  "site_key": "YOUR_SITE_KEY"
}

response

{
  "success": true,
  "risk": "low",
  "reasons": []
}

Only act on the submission when success is true. risk is one of low, medium, or high; reasons lists which signals contributed when risk isn't low.

Error codes

Code	Meaning
`invalid-site-key`	The site key doesn't match a registered domain.
`token-expired`	The token wasn't verified within its short validity window. Ask the visitor to resubmit.
`token-already-used`	Tokens are single-use; this one was already verified once.
`missing-token`	No token was attached to the request. Check that the widget script loaded before submit.

Testing

Use a sandbox site key during development. It always returns "risk": "low" so you can build your integration without triggering real detection logic.

Sandbox key: katcha_test_00000000, for local development only, not for production traffic.

Rate limits

Each plan includes a monthly allowance of protected requests (see pricing). Going over it never blocks traffic. Extra requests are billed at your plan's rate on the next invoice, and we email you at 80% and 100% of your allowance.