NexusClearance API

A self-hosted HTTP microservice for solving Cloudflare challenges, AWS WAF, and CAPTCHAs via a real patched Chromium browser.

Quick Start

Docker

Copydocker run -d \
  -p 3000:3000 \
  --shm-size=2g \
  --cap-add=SYS_ADMIN \
  nexustechpro/clearance:latest

First Request

Copycurl -X POST http://localhost:3000/bypass \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","mode":"cloudflare"}'

Response

Copy{
  "success": true,
  "data": {
    "cf_clearance": "abc123...",
    "userAgent": "Mozilla/5.0 ...",
    "cookies": [ { "name": "cf_clearance", "value": "abc123...", ... } ],
    "title": "Example Domain",
    "finalUrl": "https://example.com/",
    "solveMs": 4200,
    "mode": "cloudflare"
  }
}

FlareSolverr Migration

NexusClearance is a drop-in replacement for FlareSolverr v3.x. Change one setting in your tool (Prowlarr, Jackett, etc.):

Copy# Before
FlareSolverr URL: http://flaresolverr:8191

# After — that's it
FlareSolverr URL: http://nexus-clearance:3000

The /v1 endpoint accepts identical request/response shapes including session management.

POST /bypass

Universal solver endpoint. Supports all 10 solver modes.

Field	Type	Required	Description
url	string	required	Target URL to solve
mode	string	optional	Solver mode (default: cloudflare)
siteKey	string	optional	Required for turnstile-min
waitFor	number	optional	ms to wait after solve (max 10000)
getPageSource	boolean	optional	Include full HTML in response
useProxy	boolean	optional	Use auto proxy from pool
proxy	object	optional	Manual proxy: {host, port, protocol, username, password}
country	string	optional	Proxy country filter: HK, KH, TW, KR, VN
setCookies	array	optional	Inject cookies before navigation
intercept	array	optional	Capture in-flight responses: [{url, type}]
actions	array	optional	Actions pipeline executed sequentially after page load (see below)
sessionId	string	optional	Reuses a dedicated persistent browser context & open tab for up to 5 minutes (auto-destroyed after 5 mins TTL). DOM and cookies persist across multiple /bypass requests.
async	boolean	optional	Fire-and-forget, returns jobId
webhook	object	optional	POST result to URL when done: {url, method, headers}

Actions Pipeline

15 action types executed sequentially: click, type, scroll, hover, select, keypress, wait, navigate, waitForSelector, waitForText, waitForURL, evaluate, evaluateAndReturn, screenshot, and resolve.

Copy"actions": [
  { "type": "waitForSelector", "selector": "#login-btn" },
  { "type": "click", "selector": "#login-btn" },
  { "type": "type", "selector": "#email", "value": "user@example.com" },
  { "type": "wait", "ms": 500 },
  { "type": "evaluateAndReturn", "script": "return document.title", "name": "pageTitle" },
  { "type": "screenshot", "name": "after_login", "fullPage": false }
]

Visual AI & Canvas Solver: resolve

The resolve action provides universal, caller-driven visual puzzle solving. NexusClearance captures the target element, injects the base64 image into your custom HTTP request, calls your AI vision model (Google Gemini, OpenAI GPT-4o, Anthropic Claude, or a custom solver), parses the target coordinates, and executes a human-like Bezier mouse movement and click directly on the canvas.

Available Body Placeholders:

• {{image}} — The raw base64-encoded PNG data of the target element.
• {{w}} — The element's client width in CSS pixels.
• {{h}} — The element's client height in CSS pixels.

Example 1: Google Gemini Flash Vision Solver

Copy{
  "url": "https://example.com/login",
  "mode": "cloudflare",
  "sessionId": "user_session_1",
  "actions": [
    { "type": "waitForSelector", "selector": "canvas#captcha" },
    {
      "type": "resolve",
      "selector": "canvas#captcha",
      "request": {
        "url": "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent?key=YOUR_API_KEY",
        "method": "POST",
        "headers": { "Content-Type": "application/json" },
        "body": {
          "contents": [{
            "parts": [
              { "text": "Locate the target puzzle coordinates x and y within width {{w}} and height {{h}}. Output strictly JSON: {\"x\": number, \"y\": number}" },
              { "inline_data": { "mime_type": "image/png", "data": "{{image}}" } }
            ]
          }]
        }
      },
      "timeout": 25000
    },
    { "type": "wait", "ms": 1500 }
  ]
}

Example 2: OpenAI GPT-4o Vision Solver

Copy{
  "url": "https://example.com/portal",
  "mode": "cloudflare",
  "actions": [
    {
      "type": "resolve",
      "selector": "canvas#captcha-box",
      "request": {
        "url": "https://api.openai.com/v1/chat/completions",
        "method": "POST",
        "headers": {
          "Content-Type": "application/json",
          "Authorization": "Bearer YOUR_OPENAI_KEY"
        },
        "body": {
          "model": "gpt-4o",
          "response_format": { "type": "json_object" },
          "messages": [{
            "role": "user",
            "content": [
              { "type": "text", "text": "Locate target coordinates x and y within width {{w}} and height {{h}}. Output strictly JSON: {\"x\": number, \"y\": number}" },
              { "type": "image_url", "image_url": { "url": "data:image/png;base64,{{image}}" } }
            ]
          }]
        }
      }
    }
  ]
}

POST /bypass/batch

Copy{
  "requests": [
    { "url": "https://site1.com", "mode": "cloudflare" },
    { "url": "https://site2.com", "mode": "cf-clearance" }
  ]
}
// Response: { "success": true, "data": { "jobs": [{ "jobId": "uuid", "url": "..." }] } }

Shorthand Mode Endpoints

Endpoint	Mode	Returns
POST /cloudflare	cloudflare	Full BypassResult
POST /turnstile-min	turnstile-min	{token}
POST /turnstile-max	turnstile-max	{token}
POST /cf-clearance	cf-clearance	{cf_clearance, userAgent}
POST /waf-session	waf-session	{cookies, headers}
POST /source	source	{source}
POST /hcaptcha	hcaptcha	{token}
POST /recaptcha-v2	recaptcha-v2	{token}
POST /recaptcha-v3	recaptcha-v3	{token, score}
POST /aws-waf	aws-waf	{aws_waf_token, cookies}

Job Queue

Copy// Poll pattern
POST /bypass { "async": true } → { "jobId": "uuid", "status": "pending" }
GET /job/uuid → { "status": "done"|"failed"|"pending", "result": {...}, "error": null }

Sessions & Persistent Browser Contexts

Persistent sessions allow multiple /bypass requests or direct page interactions to share the same isolated browser context and open page tab without re-initializing browser state or losing cookies. Every persistent session has a hard 5-minute auto-destroy TTL (300,000 ms) to guarantee system memory is always reclaimed.

Listing Active Sessions

Copy// GET /sessions
// Response:
{
  "success": true,
  "data": [
    {
      "sessionId": "user_session_1",
      "createdAt": "2026-09-12T18:00:00.000Z",
      "expiresInMs": 240000
    }
  ]
}

Destroying Sessions

Copy// Destroy a specific session immediately
POST /session/destroy
{ "sessionId": "user_session_1" }

// Or terminate all active sessions at once
POST /session/destroy
{ "sessionId": "all" }

Direct Session Navigation

Copy// Navigate or submit forms within the session's active tab
POST /session/get  { "url": "https://example.com/dashboard", "sessionId": "user_session_1" }
POST /session/post { "url": "https://example.com/settings", "sessionId": "user_session_1", "fields": { "#email": "user@example.com" } }

Proxy Endpoints

Proxy pool auto-refreshes every 5 minutes from ProxyScrape v4 (HK, KH, TW, KR, VN — elite anonymity, >80% uptime, <2000ms). New proxies start at score 3/5; banned after 3 failures.

Environment Variables

Variable	Default	Description
PORT	3000	HTTP server port
TIMEOUT_MS	120000	Global solver timeout per request (ms)
BROWSER_LIMIT	20	Max concurrent browser contexts
CONTEXT_POOL_SIZE	1	Pre-warmed context pool size (need 2GB+ RAM to increase)
BATCH_LIMIT	10	Max requests per /bypass/batch
JOB_TTL_MS	300000	Job expiry time (ms)
MEMORY_LIMIT_MB	1024	Heap threshold for memory manager (MB)
GEMINI_KEYS		Comma-separated Gemini API keys for hCaptcha fallback
HEADED	false	Run browser in headed (visible) mode
TRANSFORMERS_CACHE	/tmp/whisper-cache	Xenova/Transformers model cache path

Error Codes

Code	HTTP	When
NOT_READY	503	Browser not initialized yet
TOO_MANY	429	At BROWSER_LIMIT capacity
BAD_REQUEST	400	Invalid URL, missing required field, invalid mode
FAILED	500	Solver threw — challenge not solved, timeout, context crash
NOT_FOUND	404	Job ID not found, unknown route
NO_PROXY	503	Proxy pool empty or exhausted

Solver Comparison

Mode	Speed	What it solves	Use when
cloudflare	Medium	Full CF bypass	Need full cookie set + source
cf-clearance	Fast	CF cookie only	Just need the clearance cookie
turnstile-min	Fastest	Turnstile token	You have the siteKey, no live page needed
turnstile-max	Medium	Turnstile from live page	Widget embedded in real CF page
waf-session	Medium	CF cookies + headers	Need to replay via CycleTLS/curl
source	Medium	Page HTML after CF clears	Scraping CF-protected content
hcaptcha	Slow	hCaptcha token	Site uses hCaptcha (not CF)
recaptcha-v2	Slow	reCAPTCHA v2 token	Audio challenge approach
recaptcha-v3	Medium	reCAPTCHA v3 token + score	Behaviour-based, no visual challenge
aws-waf	Medium	AWS WAF token cookie	Amazon/AWS-protected endpoints