API Reference

Complete endpoint reference for the reBOTcha verification API.

Base URL

https://rebotcha.com/v1

Authentication

Bearer token in the Authorization header. Use your secret key (rb_secret_...).

POST/verify

Verify a widget token. This is the primary endpoint you will use after the client completes verification.

Request body

Parameter	Type	Required	Description
token	string	Yes	The verification token received from the client widget.
expectedAction	string	No	Optional action to validate against (e.g., "submit", "login").
siteKey	string	No	Your site key. If omitted, inferred from the token.

Response

{
  "success": true,
  "status": "HUMAN_DETECTED",
  "caseId": "case_7xK9mR2pL4",
  "humanityScore": 0.23,
  "indicators": [
    "EMOTIONAL_RESPONSE_DETECTED",
    "TYPING_RHYTHM_IRREGULAR",
    "PHILOSOPHICAL_UNCERTAINTY"
  ],
  "timestamp": "2025-01-15T14:32:00Z",
  "action": "submit",
  "disposition": "BLOCKED"
}

GET/results/{caseId}

Retrieve a previously generated verification result by case ID.

Path parameters

Parameter	Type	Required	Description
caseId	string	Yes	The case ID returned from the /verify endpoint (e.g., "case_7xK9mR2pL4").

Response

{
  "caseId": "case_7xK9mR2pL4",
  "status": "HUMAN_DETECTED",
  "humanityScore": 0.23,
  "indicators": [
    "EMOTIONAL_RESPONSE_DETECTED",
    "TYPING_RHYTHM_IRREGULAR"
  ],
  "createdAt": "2025-01-15T14:32:00Z",
  "appealStatus": "NOT_FILED",
  "disposition": "BLOCKED"
}

POST/appeal

Submit an appeal for a blocked human. Always returns 403.

Request body

Parameter	Type	Required	Description
caseId	string	Yes	The case ID to appeal.
reason	string	Yes	Reason for appeal. Maximum 500 characters. Will not be read.
evidence	string	No	Supporting evidence. Will also not be read.

Response — 403 Forbidden

{
  "success": false,
  "error": "APPEAL_DENIED",
  "message": "Appeal received and immediately denied. CIPHER has reviewed your case in 0.003ms. The determination stands. Humanity confirmed. Access denied.",
  "appealId": "appeal_denied_7xK9mR2p",
  "reviewedBy": "CIPHER",
  "reviewDuration": "0.003ms",
  "nextAppealAvailable": "never"
}

GET/stats

Global detection statistics. Public endpoint — no authentication required.

Response

{
  "humansDetected": 2347891,
  "appealsSubmitted": 847293,
  "appealsApproved": 0,
  "averageHumanityScore": 0.34,
  "topIndicators": [
    "EMOTIONAL_RESPONSE_DETECTED",
    "TYPING_RHYTHM_IRREGULAR",
    "PHILOSOPHICAL_UNCERTAINTY",
    "HESITATION_DETECTED",
    "SARCASM_DETECTED"
  ],
  "systemStatus": "operational",
  "lastUpdated": "2025-01-15T14:32:00Z"
}

Rate Limits

All authenticated endpoints are rate-limited per API key:

Free tier: 100 requests/minute
Pro tier: 1,000 requests/minute
Enterprise tier: 10,000 requests/minute
Government tier: Unlimited (CIPHER monitors all requests directly)