Live Demo
API Documentation
Getting Started
To use this API, you first need to get a site key:
Store your site key securely. It cannot be retrieved if lost.
1. Generate CAPTCHA
Generate either an image or math CAPTCHA:
async function generateCaptcha(siteKey, type = 'image') {
try {
const response = await fetch('/api/generate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
site_key: siteKey,
type: type // 'image' or 'math'
})
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.detail || 'Generate failed');
}
const data = await response.json();
return data; // Contains captcha_id and image/question
} catch (error) {
console.error('Generate error:', error);
throw error;
}
}Possible Errors:
- 403 Forbidden: Invalid site key
- 429 Too Many Requests: Rate limit exceeded (100 requests/hour)
- 500 Internal Server Error: Failed to generate CAPTCHA
2. Validate CAPTCHA
Validate user input:
async function validateCaptcha(siteKey, captchaId, userInput) {
try {
const response = await fetch('/api/validate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
site_key: siteKey,
captcha_id: captchaId,
user_input: userInput
})
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.detail || 'Validation failed');
}
const data = await response.json();
return data; // Contains valid status and token if successful
} catch (error) {
console.error('Validation error:', error);
throw error;
}
}
Possible Errors:
- 400 Bad Request: Invalid or expired CAPTCHA
- 403 Forbidden: Invalid site key
- 429 Too Many Requests: Rate limit exceeded (200 requests/hour)
- 500 Internal Server Error: Validation failed
Rate Limits & Expiration
- Generate: 100 requests per hour per site key
- Validate: 200 requests per hour per site key
- CAPTCHA expires after 5 minutes
- Rate limits reset hourly
Security Information
- Validation tokens expire after 5 minutes
- Each CAPTCHA can only be used once
- Failed validation attempts are counted against rate limits
- The API uses JWT for validation tokens
Response Format
Generate Success:
{
"captcha_id": "unique-identifier",
"type": "image" | "math",
"image": "base64-string" | undefined,
"question": "math-problem" | undefined
}
Validate Success:
{
"valid": true | false,
"token": "jwt-token" | undefined
}
Error Response:
{
"detail": "Error message"
}