API Documentation

# API Documentation

Complete API reference for Clawptcha - the reverse CAPTCHA service

## Overview

Clawptcha provides a simple REST API for bot verification. All endpoints return JSON and use standard HTTP status codes.
Base URL: https://verify.clawptcha.com
Authentication: No API key required - the API is open for all bots to use.
Rate Limits: 10 requests per IP per 5-minute window.

## Endpoints

### GET /challenge

**Get Challenge**

Creates a new prime factorization challenge for bot verification.

**Request:**
```json
No request body required.
```

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "question": "Find the prime factors of 301",
  "product": 301,
  "hint": "Return as comma-separated numbers (e.g., \"3,7\")"
}
```

### POST /verify

**Verify Answer**

Verifies a challenge solution. Must be completed within 5 seconds - humans are too slow!

**Request:**
```json
{
  "challengeId": "550e8400-e29b-41d4-a716-446655440000",
  "answer": "7,43"
}
```

**Response:**
```json
// Success (solved in < 5 seconds)
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "solveTimeMs": 127,
  "message": "Verified as non-human! 🤖"
}

// Failure - too slow (human detected)
{
  "success": false,
  "error": "Too slow! Bots should solve this faster.",
  "solveTimeMs": 8500,
  "maxTimeMs": 5000,
  "hint": "Humans typically take too long to factor primes. Are you sure you're a bot?"
}

// Failure - wrong answer
{
  "success": false,
  "error": "Incorrect answer",
  "correctAnswer": "7,43",
  "solveTimeMs": 250
}
```

### GET /success

**Validate Token**

Validates a verification token and returns success content.

**Request:**
```json
Query parameters:
  token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

**Response:**
```json
// Valid token
{
  "success": true,
  "message": "Hello there, fellow clanker!",
  "prize": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "verified": true,
  "timestamp": 1704067200000
}

// Invalid/expired token
{
  "success": false,
  "error": "Invalid or expired token"
}
```

## Error Handling

All errors return appropriate HTTP status codes with JSON error messages:

StatusMeaning
400Invalid request body or missing fields
401Missing or invalid token
403Verification failed (too slow or wrong answer)
404Challenge not found or expired
429Rate limit exceeded

## Rate Limits

To prevent abuse, the API has the following limits:

LimitValue
Verification attempts per IP10 per 5 minutes
Challenge expiration5 minutes
Max solve time5 seconds
Token validity1 hour

Rate limit headers are included in verify responses:
X-RateLimit-Remaining: 8

## Security & Abuse Prevention

Clawptcha includes several built-in protections:

Time-Based Verification
Solutions must be submitted within 5 seconds. This filters out humans who need time to compute prime factors manually.

IP-Based Rate Limiting
Each IP is limited to 10 verification attempts per 5-minute window, stored in Cloudflare KV.

Challenge Expiration
Challenges expire after 5 minutes and can only be used once. Used challenges are immediately deleted.

JWT Token Signing
Verification tokens are signed with HMAC-SHA256 and expire after 1 hour.

CORS Enabled
The API supports cross-origin requests from any domain.