Base URL
https://challenges.trustedcaptcha.com/api/v1
POST /siteverify
Server-to-server. Validate a token submitted by your user's form.
Parameters
| Field | Required | Description |
|---|---|---|
secret | yes | Your site's secret key. Never share, never embed in client code. |
response | yes | The token from the form's trustedcaptcha-response field. |
remoteip | recommended | The end user's IP address. Used for risk-engine cross-check. |
Successful response
{
"success": true,
"score": 0.92,
"mode": "smart",
"hostname": "example.com",
"challenge_ts": "2026-05-11T09:00:00+00:00",
"action": null,
"error_codes": []
}Error response
{
"success": false,
"error_codes": ["invalid-input-response"]
}Error codes
| Code | HTTP | Cause |
|---|---|---|
missing-input-secret | 200 | secret field empty. |
invalid-input-secret | 200 | Secret doesn't match any site. |
missing-input-response | 200 | response field empty. |
invalid-input-response | 200 | Token doesn't exist, or wrong site. |
timeout-or-duplicate | 200 | Token expired or already verified. |
rate-limited | 200 | Too many verify calls for this secret. Back off. |
POST /challenge & /answer
These are called by the widget directly. You generally don't need them. They're documented in widget reference and used by SDK authors who want to build a non-iframe widget.
Rate limits
| Endpoint | Limit | Scope |
|---|---|---|
/challenge | 60/min | per IP |
/answer | 60/min | per IP |
/siteverify | 600/min | per secret |
| Per sitekey | 5000/min | all /challenge for one sitekey |
Pro plans have higher quotas. Contact us if you need volume above 10 M verifications/month.