API Reference

CAPTCHA Solving

BrowseFleet integrates with 2captcha to automatically detect and solve CAPTCHAs on pages within active sessions. Supports reCAPTCHA v2, hCaptcha, and Cloudflare Turnstile.

How It Works

text

1. Call the solve endpoint on a session with a CAPTCHA-protected page
2. BrowseFleet scans the page DOM for CAPTCHA elements
3. Detects the CAPTCHA type (reCAPTCHA, hCaptcha, or Turnstile)
4. Extracts the site key from the data-sitekey attribute
5. Submits the challenge to 2captcha API
6. Polls for the solution (up to 120 seconds)
7. Injects the solution token into the page
8. Triggers any callback functions registered by the CAPTCHA

POST/v1/sessions/:id/captcha/solve

Detect and solve a CAPTCHA on the current page of an active session.

Parameters

Name	Type	Required	Default	Description
`type`	`"auto" \| "recaptcha" \| "hcaptcha" \| "turnstile"`	No	`"auto"`	CAPTCHA type to solve. Use 'auto' to detect automatically.

Request Body

{
  "type": "auto"
}

Response

{
  "success": true,
  "type": "recaptcha",
  "duration": 23450
}

# First navigate to the page with the CAPTCHA
curl -X POST "https://api.browsefleet.com/v1/sessions/sess_abc123/actions" \
  -H "Content-Type: application/json" \
  -H "x-api-key: bf_your_api_key" \
  -d '{"actions": [{"type": "navigate", "url": "https://site-with-captcha.com"}]}'

# Then solve the CAPTCHA
curl -X POST "https://api.browsefleet.com/v1/sessions/sess_abc123/captcha/solve" \
  -H "Content-Type: application/json" \
  -H "x-api-key: bf_your_api_key" \
  -d '{"type": "auto"}'

Supported CAPTCHA Types

Type	Detection Method	Solution Method
reCAPTCHA v2	Detects g-recaptcha elements and data-sitekey	Token injected into #g-recaptcha-response, callbacks triggered
hCaptcha	Detects h-captcha elements and data-sitekey	Token injected via 2captcha hCaptcha handler
Cloudflare Turnstile	Detects cf-turnstile elements and data-sitekey	Token injected via 2captcha Turnstile handler

Configuration

CAPTCHA solving requires a 2captcha API key. Set it via environment variable:

bash

CAPTCHA_API_KEY=your_2captcha_api_key
CAPTCHA_PROVIDER=2captcha

If no CAPTCHA API key is configured, the solve endpoint returns HTTP 501 with an error message.

Error Responses

No CAPTCHA detected

json

{ "success": false, "type": "none", "duration": 50, "error": "No CAPTCHA detected on page" }

Solve timeout

json

{ "success": false, "type": "recaptcha", "duration": 120000, "error": "CAPTCHA solve timed out" }

Not configured

HTTP 501:

json

{ "error": "CAPTCHA solving not configured. Set CAPTCHA_API_KEY." }