API Reference

Base URL: https://api.captchaoculto.com

POST /verify

Verify a verdict token from a form submission. This is the main endpoint you'll use from your backend.

Request Body (JSON)

Parameter	Type	Description
`token` required	string	The verdict token from the `_co_verdict` form field
`api_key` required	string	Your API key (`ak_...`). Can also be sent as `X-API-Key` header.

Success Response (200)

				{
  "valid": true,
  "score": 12,
  "classification": "human",
  "threshold": 50,
  "session_id": "co_a1b2c3..."
}
			

Response Fields

Field	Type	Description
`valid`	boolean	Whether the token is valid and not expired
`score`	integer	Bot score from 0 (human) to 100 (bot)
`classification`	string	`"human"` (0-25), `"suspicious"` (26-50), or `"bot"` (51-100)
`threshold`	integer	Your configured score threshold
`session_id`	string	Unique session identifier

Error Responses

Status	Error	Description
400	`token_required`	Missing verdict token
400	`api_key_required`	Missing API key
401	`invalid_api_key`	API key not found or inactive
400	`invalid_token`	Token signature invalid or expired
409	`already_verified`	This token was already used (anti-replay)

GET /stats

Get usage statistics for your site. Requires your API key.

Query Parameters

Parameter	Type	Description
`api_key` required	string	Your API key. Can also be sent as `X-API-Key` header.
`action`	string	One of: `summary` (default), `recent`, `distribution`
`limit`	integer	For `recent` action: number of results (max 200, default 50)
`month`	string	For `distribution` action: `YYYY-MM` format

Summary Response

				{
  "distribution": {
    "total": 1500,
    "human": 1350,
    "suspicious": 100,
    "bot": 50,
    "avg_score": 15.3
  },
  "usage": [
    {
      "year_month": "2026-02",
      "total_inits": 5000,
      "total_scores": 2000,
      "total_verifications": 1500,
      "total_human": 1350,
      "total_suspicious": 100,
      "total_bot": 50
    }
  ]
}
			

GET /health

Health check endpoint. No authentication required.

				{
  "status": "ok",
  "service": "CAPTCHA Oculto",
  "version": "3.0.0",
  "architecture": "zero-kv"
}
			

Rate Limits

Endpoint	Limit	Window
`/init`	30 requests	Per minute per IP
`/score`	20 requests	Per minute per IP
`/verify`	No limit	Server-side calls only

Score Classification

Score Range	Classification	Recommended Action
0 - 25	human	Process normally
26 - 50	suspicious	Process but flag for review
51 - 100	bot	Reject (phantom success recommended)

Phantom Success: Instead of showing an error to bots, return a fake success response. This prevents bots from adapting their behavior based on error messages.