canonical: https://jentic.com/apis/hcaptcha.com/hcaptcha # hCaptcha Siteverify API The hCaptcha Siteverify API verifies the response token returned when a user solves an hCaptcha challenge on a webpage or mobile screen. A backend service posts the token, the site secret, and optionally the user IP to /siteverify, and hCaptcha returns whether the token is genuine, unused, and tied to the expected sitekey. Teams use it to gate signups, comment forms, and login flows against bots without storing user-identifying data. ## For AI agents Verify an hCaptcha challenge response token server-side to confirm the request came from a human and not a bot. ## Scope Does not handle widget rendering, account fraud scoring, or identity verification - use for server-side hCaptcha token verification only. ## Capabilities - Verify an hCaptcha challenge response token through POST /siteverify - Confirm the verifying domain matches the hostname registered for the sitekey - Detect token reuse, expired tokens, and missing-input errors from the response payload - Pass the optional remoteip parameter to scope verification to a specific client IP - Gate signups, comment posts, and login attempts behind a server-side bot check ## Use cases ### Signup Form Bot Protection Embed the hCaptcha widget on the signup page and post the resulting token to /siteverify before creating the user record. The endpoint returns success only if the token is unused, unexpired, and tied to the registered sitekey, so fake account scripts that scrape the page without solving the challenge fail at the verification step. This stops the most common signup spam without adding friction for real users. Example prompt: POST to /siteverify with secret, response, and remoteip fields and reject the signup when success is false ### Comment Form Anti-Spam Wire /siteverify into the comment-submission handler so each posted comment carries a fresh, unused hCaptcha token. The verification check sits server-side, so attackers cannot bypass it by stripping the widget. Combine with the optional remoteip field to catch token-replay attempts coming from different IP addresses. Example prompt: POST to /siteverify and reject the comment if the response error-codes array contains timeout-or-duplicate ### Login Form Brute-Force Defense Trigger an hCaptcha challenge after a small number of failed login attempts and require a successful /siteverify response before processing the next attempt. The verification step ensures the next try comes from a real browser solving a real challenge, slowing automated credential-stuffing tools to a crawl. Pair this with rate limiting for layered defense. Example prompt: POST to /siteverify after a third failed login and only process the next password attempt if success is true ### AI Agent Captcha Gate via Jentic Agents that automate signups or form submissions on partner sites call the hCaptcha verify operation through Jentic to confirm a token before forwarding it on. Jentic stores the site secret in the vault, so multiple agents can share the operation without each holding the raw key. This makes it practical to build captcha-aware automation toolkits. Example prompt: Use Jentic search 'verify a captcha token' to load /siteverify and execute with the secret pulled from the vault ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /siteverify | Verify an hCaptcha response token | ## Key resources - **Siteverify** — Verify a challenge response token via /siteverify ## Why Jentic - **Setup:** Wiring hCaptcha by hand means posting form-encoded requests to /siteverify and placing the account secret in the request body on every verification. Through Jentic you install once, import the hCaptcha Siteverify API from the API Directory, store the site secret once, and your agent calls it. - **Permission scoping:** hCaptcha exposes a single verification operation and sends the secret and response token in the request body, so limit the agent to the operation it needs, verifying a captcha token. You choose the operations it may call, so nothing beyond siteverify is included unless you add it. - **Credential handling:** Your hCaptcha site secret is stored once, encrypted, by your own Jentic One instance and injected into the request at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'verify a captcha token' or 'check an hcaptcha response', and Jentic returns the /siteverify operation with its input schema so the agent calls it without browsing the reference docs. ## Related APIs - **Google APIs** — Google's reCAPTCHA covers similar bot-verification needs through siteverify - **Cloudflare API** — Cloudflare Turnstile and Bot Management complement hCaptcha at the edge and DNS layer - **Snyk API** — Snyk scans the application code that integrates hCaptcha for known dependency and configuration issues ## FAQ ### What authentication does the hCaptcha Siteverify API use? Authentication is through the secret query parameter, which carries your hCaptcha site secret. Jentic securely stores the secret and adds it to each /siteverify call, so agents never hold the raw key. ### Can I verify an hCaptcha token without sending the user IP? Yes. The remoteip field on POST /siteverify is optional. Sending it adds a check that the verifying IP matches the IP that solved the challenge, which is a useful extra signal but not required. ### What are the rate limits for the hCaptcha Siteverify API? hCaptcha does not enforce a public per-account rate limit on /siteverify; the endpoint scales with your traffic. Excessive verifications against unrelated tokens can still trigger account-level review. ### How do I verify a captcha token through Jentic? Search Jentic for 'verify a captcha token', load the /siteverify operation for hcaptcha.com, and execute with the response token from the form. Jentic supplies the site secret from the vault. ### Is the hCaptcha Siteverify API free? hCaptcha's Publisher plan is free and includes server-side /siteverify calls. Enterprise plans add risk scoring and account defender features but use the same endpoint. ### Why does my /siteverify call return timeout-or-duplicate? That error code means the token has already been verified or was generated more than two minutes before the call. Generate a fresh token from the widget and post it once - tokens are single-use. ### Can I limit what my agent is allowed to do with the hCaptcha Siteverify API? Yes. The hCaptcha Siteverify API exposes a single verification operation, so with your self-hosted Jentic One instance you decide which operations the agent may call and restrict it to just verifying a captcha token through POST /siteverify. Your own rules govern access, so nothing beyond siteverify is available unless you explicitly add it. The site secret is injected into each request at execution time rather than handed to the agent, so the agent can confirm a token without ever holding the raw credential.