API Reference

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

For interactive API documentation with request builder, visit the Scalar API Reference.

GET /challenge

Request a new PoW challenge. The widget calls this automatically.

IP Binding: The challenge is bound to the requesting IP. The subsequent /verify call must come from the same IP address.

Headers

Header	Required	Description
`X-Site-Key`	Yes	Your public site key

Response

{
  "nonce": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "difficulty": 18,
  "algorithm": "sha256",
  "expiresAt": 1709251200000
}

Field	Type	Description
`nonce`	string	32-char hex nonce to solve
`difficulty`	integer	Leading zero bits required (16–28, adaptive)
`algorithm`	string	Always `sha256`
`expiresAt`	number	Expiry timestamp (Unix ms)

Rate Limits

60 requests/min per IP (global)
30 requests/min per IP per site key

Errors

Code	Description
`400`	Invalid or missing `X-Site-Key` header
`403`	Site key invalid, site inactive, or origin not allowed
`429`	Rate limit exceeded
`503`	Service temporarily unavailable

POST /verify

Submit the PoW solution with browser signals. Returns a verification token if the challenge passes.

IP Binding: Must be called from the same IP that requested the challenge. Mismatched IPs return 403.

Headers

Header	Required	Description
`X-Site-Key`	Yes	Your public site key
`Content-Type`	Yes	`application/json`

Body

{
  "nonce": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "counter": 182637,
  "solveTimeMs": 245,
  "fingerprintHash": "e3b0c44298fc1c149afbf4c8996fb924...",
  "environment": {
    "webdriver": false,
    "chromeAbsent": false,
    "swiftShader": false,
    "noPlugins": false,
    "notificationDenied": false,
    "zeroScreen": false,
    "noLanguages": false
  }
}

Field	Type	Required	Description
`nonce`	string	Yes	32-char hex nonce from `/challenge`
`counter`	integer	Yes	Counter value that solves the PoW
`solveTimeMs`	number	No	Client-reported solve time (ms)
`fingerprintHash`	string	Yes	SHA-256 of browser signals
`environment`	object	No	Headless detection signals

Response (passed)

{
  "token": "1709424000|a1b2c3d4...|182637|e3b0c442...|hmac...",
  "passed": true,
  "expiresAt": 1709424300000
}

Response (failed)

{
  "token": null,
  "passed": false,
  "expiresAt": null
}

Note: If the site has IP rules configured (Pro plan), blocked IPs or IPs not on the allowlist receive an immediate passed: false response without going through the full scoring pipeline.

Field	Type	Description
`token`	string \| null	Verification token for your backend. Null if failed.
`passed`	boolean	Whether verification passed the site threshold
`expiresAt`	number \| null	Token expiry (Unix ms, 5 min TTL). Null if failed.

Rate Limits

30 requests/min per IP (global)
20 requests/min per IP per site key

Errors

Code	Description
`400`	Invalid body, expired nonce, or missing fields
`403`	IP mismatch, invalid site key, or origin not allowed
`429`	Rate limit exceeded
`503`	Service temporarily unavailable

POST /verify-token

Server-side token verification. Call this from your backend only — this endpoint does not support CORS.

Tokens are single-use and expire after 5 minutes.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer YOUR_API_KEY`
`Content-Type`	Yes	`application/json`

Body

{
  "token": "1709424000|a1b2c3d4...|182637|e3b0c442...|hmac...",
  "expectedIp": "203.0.113.42"
}

Field	Type	Required	Description
`token`	string	Yes	Token from `/verify`
`expectedIp`	string	No	IP to match against. Recommended for security.

Response (success)

{
  "success": true,
  "score": 0.85,
  "ip": "203.0.113.42",
  "solvedAt": 1709424000000
}

Response (failure)

{
  "success": false,
  "error": "Token already used"
}

Field	Type	Description
`success`	boolean	Whether the token is valid
`score`	number	Confidence score (0.0 = bot, 1.0 = human)
`ip`	string	IP that solved the challenge
`solvedAt`	number	When the challenge was solved (Unix ms)
`error`	string	Error message (only when `success: false`)

Rate Limits

100 requests/min per IP (global, fail-closed)
200 requests/min per API key (fail-closed)

Errors

Code	Description
`400`	Invalid token, expired, site mismatch, or already used
`401`	Missing or invalid Authorization header
`429`	Rate limit exceeded
`503`	Service temporarily unavailable (fail-closed)

CORS

Endpoint	CORS
`GET /challenge`	Yes (`*`)
`POST /verify`	Yes (`*`)
`POST /verify-token`	No — backend only

The /challenge and /verify endpoints accept requests from any origin. The /verify-token endpoint is server-to-server only and does not include CORS headers.

On this page