Captcha Solving API Reference

Overview

RageCaptcha Developer API

RageCaptcha exposes a short request/poll JSON REST API for programmatic captcha solving. You submit a task with POST /create-task (returns HTTP 202 with a task_id), then poll POST /check-task every 1–2 seconds until the solve completes. This keeps every HTTP hop short — a slow solve never holds a Cloudflare request open. We currently support the PopularCaptcha family only — Standard and Enterprise variants, proxied or proxyless. Failed solves return HTTP 200 with status: "failed" and are never charged — the solve fee goes straight back to your balance. Balance top-ups are final and non-refundable (see the No Refund Policy), and we do not issue free trial credits.

The same endpoints also run Discord join and boost jobs — see the Handoff API.

Base URL

https://api.ragecaptcha.com

Content-Type

application/json

Auth

clientkey in body / query

Every response includes an X-Request-ID header. Task endpoint responses also send Cache-Control: no-store, no-cache, must-revalidate. Captcha tasks have no application-level rate limit or Retry-After — every accepted task starts its solver request immediately. Handoff jobs can return 429.

Authentication

Authenticate with your client key

Every request is authenticated with a clientkey — a unique secret developer token issued from your dashboard. Treat it like a password, keep it server-side, and rotate immediately if leaked.

Never expose your clientkey in a browser or mobile bundle. Anyone who reads it can spend your balance. Rotate it from the dashboard the moment it's leaked.

Endpoint

POST /create-task

POSThttps://api.ragecaptcha.com/create-task

Submit a captcha task. The API validates, atomically charges your balance, persists the task, and immediately returns HTTP 202 with a task_id. The solver request starts in the background — poll /check-task for the result.

Request body

Name	Type	Required	Description
`clientkey`	string	Required	Your secret developer API access key.
`data.task`	string	Required	Blueprint identifier (e.g. PopularCaptchaTokenProxyless). Must exist in the pricing table.
`data.sitekey`	string	Required	Target site key. Alias: site_key.
`data.siteurl`	string	Required	Full origin URL where the challenge triggers. Aliases: href, site, site_url.
`data.proxy`	string	Conditional	http://user:pass@ip:port. Required for all non-Proxyless blueprints.
`data.rqdata`	string	Optional	Extra request metadata used by high-security targets.

clientkeystringRequired

Your secret developer API access key.

data.taskstringRequired

Blueprint identifier (e.g. PopularCaptchaTokenProxyless). Must exist in the pricing table.

data.sitekeystringRequired

Target site key. Alias: site_key.

data.siteurlstringRequired

Full origin URL where the challenge triggers. Aliases: href, site, site_url.

data.proxystringConditional

http://user:pass@ip:port. Required for all non-Proxyless blueprints.

data.rqdatastringOptional

Extra request metadata used by high-security targets.

Response (HTTP 202)

Name	Type	Required	Description
`task_id`	string		Unique task identifier — use it with /check-task.
`status`	string		Always "processing" on creation.

task_idstring

Unique task identifier — use it with /check-task.

statusstring

Always "processing" on creation.

curl -X POST https://api.ragecaptcha.com/create-task \
  -H "Content-Type: application/json" \
  -d '{
    "clientkey": "your-api-key",
    "data": {
      "task": "PopularCaptchaTokenProxyless",
      "sitekey": "captcha-site-key",
      "siteurl": "https://example.com"
    }
  }'

Enterprise custom pricing: Entries in SpecialPricing can override the price for an exact site URL + sitekey pair, but only for the proxied PopularCaptchaEnterpriseToken task. A matching pair submitted as PopularCaptchaEnterpriseTokenProxyless is rejected, and the proxied task must include data.proxy. Other task types continue to use their default prices.

Custom-priced sites

12 configured targets · Proxied Enterprise task only

Price / 1K

$10.00

Discord

3 sites

https://discord.com/register$10 / 1K

KEYa9b5fb07-92ff-493f-86fe-352a2803b3df

https://discord.com/quest-home$10 / 1K

KEY4bb5aadb-b50f-4f23-b1c2-92b59ba400d5

https://discord.com/channels/@me$10 / 1K

KEY472b4c9f-f2b7-4382-8135-c983f5496eb9

Steam

3 sites

https://store.steampowered.com/join$10 / 1K

KEYe18a349a-46c2-46a0-87a8-74be79345c92

https://help.steampowered.com/en/wizard/HelpWithLoginInfo$10 / 1K

KEY464c5638-2416-4818-8fa8-91e669b4d6a8

https://help.steampowered.com/en/wizard/HelpRequestCantLogin$10 / 1K

KEY20e8e2a6-6908-4840-9814-912e9ea4683c

Epic Games

3 sites

https://www.epicgames.com/id/login$10 / 1K

KEY91e4137f-95af-4bc9-97af-cdcedce21c8c

https://www.epicgames.com/id/register$10 / 1K

KEYb364b1fd-e3d8-4d24-8c41-77a19604b00d

https://www.epicgames.com/id/login/forgot-password$10 / 1K

KEY264d6f74-6d54-4621-ab76-619f2566081c

Riot Games

3 sites

https://authenticate.riotgames.com/$10 / 1K

KEY019f1553-3845-481c-a6f5-5a60ccf6d830

https://recovery.riotgames.com/en/forgot-password$10 / 1K

KEYdb18a187-7b77-4dac-a6cb-6dd5215973cf

https://account.riotgames.com/$10 / 1K

KEYb3c619fc-4b72-4838-9bf2-398888588d62

Each configured entry costs $0.010 per solve. The displayed $10.00 price is calculated as $0.010 × 1,000 solves.

Custom-price matching

URL matching is hostname- and port-aware and path-sensitive. Hostnames are case-insensitive; schemes, query strings, fragments, and trailing slashes are ignored. Sitekeys and URL paths remain case-sensitive. Missing, malformed, or invalid pricing entries are ignored, leaving the default task price in effect. The pricing file is read for every request, so changes do not require an API restart.

Example request

{
  "clientkey": "your-api-key",
  "data": {
    "task": "PopularCaptchaEnterpriseToken",
    "sitekey": "a9b5fb07-92ff-493f-86fe-352a2803b3df",
    "siteurl": "https://discord.com/register",
    "proxy": "host:port:user:password"
  }
}

Endpoint

POST /check-task

POSThttps://api.ragecaptcha.com/check-task

Poll for the result of a task. Prefer POST — it keeps the API key out of URLs and access logs. Poll every 1–2 seconds until status is success or failed. A failed solve returns HTTP 200 with a terminal failure status and the solve fee is returned to your balance. The GET form /check-task?clientkey=...&task_id=... is also accepted.

Request body

clientkeystringRequired

Your secret developer API access key.

task_idstringRequired

The task ID returned by /create-task. Alias: taskId. Max 128 chars.

Response (HTTP 200)

Name	Type	Required	Description
`task_id`	string		Echoes the requested task ID.
`status`	string		"processing", "success", or "failed".
`solution`	string	Success	The signed captcha token. Present only when status is "success".
`error`	string	Failed	Terminal failure reason. Present only when status is "failed".
`cost`	number		Task price in USD. Legacy rows return 0.0.

task_idstring

Echoes the requested task ID.

statusstring

"processing", "success", or "failed".

solutionstringSuccess

The signed captcha token. Present only when status is "success".

errorstringFailed

Terminal failure reason. Present only when status is "failed".

costnumber

Task price in USD. Legacy rows return 0.0.

curl -X POST https://api.ragecaptcha.com/check-task \
  -H "Content-Type: application/json" \
  -d '{
    "clientkey": "your-api-key",
    "task_id": "5d54269e-8cdf-40fb-a94c-912adca99ac8"
  }'

Endpoint

GET /balance

GEThttps://api.ragecaptcha.com/balance

Fetch real-time balance for your account. The alias GET /getBalance returns the same response. Poll before dispatching large batches or wire into your billing alerts.

Query parameters

clientkeystringRequired

Your secret developer API access key.

Response body

Name	Type	Required	Description
`balance`	number		Remaining balance.
`currency`	string		Balance currency — always "USD".

balancenumber

Remaining balance.

currencystring

Balance currency — always "USD".

curl -G https://api.ragecaptcha.com/balance \
  --data-urlencode "clientkey=your-api-key"

Tasks

Task blueprints & pricing

Blueprints are namespaced by captcha family. Today only PopularCaptcha is live — Standard tier handles the everyday token; Enterprise tier targets Enterprise-tier sitekeys. Future families will slot in under their own namespace.

PopularCaptcha

LIVEPopularCaptcha tokens · Standard + Enterprise

Blueprint	Tier	Per 1K	Proxy
PopularCaptchaTokenProxyLess	Standard	$1.00	Optional
PopularCaptchaToken	Standard	$1.00	Required
PopularCaptchaInvisibleToken	Standard	$1.00	Required
PopularCaptchaInvisibleTokenProxyLess	Standard	$1.00	Optional
PopularCaptchaEnterpriseToken	Enterprise	$4.00–$10.00	Required
PopularCaptchaEnterpriseTokenProxyless	Enterprise	$4.00	Optional

Next up

More captcha families will land under their own namespace — same endpoints, same client key.

Errors

Complete response & error reference

Application-level errors use { "error": "..." }. Framework-level 404 / 405 responses use { "detail": "..." }. Every response includes an X-Request-ID header. Failed solves are never charged — the fee is returned to your balance automatically.

POST /create-task

Status	Message	Meaning
202	`task_id + status:"processing"`	Task persisted; solver started immediately.
400	`Missing API key or data`	JSON is malformed, not an object, or missing clientkey / data.
400	`Invalid task: <task_name>`	data.task is not present in the pricing table.
400	`Missing sitekey`	Neither data.sitekey nor data.site_key was supplied.
400	`Missing siteurl or href`	None of href, siteurl, site, or site_url was supplied.
400	`This site requires a proxied Enterprise task`	A custom-pricing pair was submitted as PopularCaptchaEnterpriseTokenProxyless. No balance is deducted.
400	`This site requires a proxy`	A custom-pricing pair used PopularCaptchaEnterpriseToken without data.proxy. No balance is deducted.
402	`Invalid API key`	The API key does not exist.
402	`Not enough balance`	Account cannot cover the task price. Check /balance.
402	`Internal server error`	Account lookup or atomic balance deduction failed. Task not started.
402	`Internal server error`	Initial task record could not be persisted. Any deduction is returned to your balance.
500	`Internal server error`	Unexpected API exception. Logged with the request ID.

POST /check-task (and GET form)

Status	Message	Meaning
200	`status:"processing" + cost`	Solve still running. cost is the task price in USD.
200	`status:"success" + solution + cost`	Solve completed successfully.
200	`status:"failed" + error + cost`	Terminal solver failure. Not charged — stop polling.
400	`Missing API key`	clientkey was not supplied.
400	`Missing task ID`	Neither task_id nor taskId was supplied.
400	`Invalid task ID`	Task ID is not a string or is longer than 128 characters.
404	`Task not found`	No task belongs to that API-key/task-ID pair.
503	`Internal server error`	Task state could not be read from the database. Retry.
500	`Internal server error`	Unexpected API exception.
200	`Solver returned invalid JSON: malformed or unparseable response`	status:"failed" — solver returned unparseable JSON. Not charged.
200	`Service temporarily unavailable`	status:"failed" — solver connection, timeout, HTTP, shutdown, or unexpected request failure. Not charged.
200	`Solver failed to generate solution`	status:"failed" — solver returned no usable token or its own failure value. Not charged.

GET /balance and /getBalance

Status	Message	Meaning
200	`balance + currency`	Balance lookup succeeded.
400	`Missing API key`	clientkey was not supplied.
401	`Invalid API key`	The API key does not exist.
503	`Internal server error`	Account database could not be read.
500	`Internal server error`	Unexpected API exception.

Other routes

Status	Message	Meaning
200	`{"status":"ok"}`	GET /health succeeded.
302	`Redirect to /health`	GET / succeeded.
404	`{"detail":"Not Found"}`	Route does not exist. All old /api/* routes return this.
405	`{"detail":"Method Not Allowed"}`	Route exists, but the HTTP method is not supported.

Handoff API

Discord join & boost jobs

Handoff jobs run a Discord join or boost across a batch of tokens. They use the same base URL, the same clientkey and the same balance as captcha tasks. Send data.tool instead of data.task to POST /create-task, keep the returned job_id, then poll GET /check-task every 10 seconds — for at most 600 seconds — until the job leaves processing.

Tools

boost · join

Poll interval

10 s · max 600 s

Price

$0.01 per successful join

Billing

Charged per successful join at $0.01 per token.
cost in the job response is the total charged for that job.
Nothing is charged when a join fails, for any reason.

Handoff · Endpoint

Create a job

POSThttps://api.ragecaptcha.com/create-task

Start a join or boost job. The response returns immediately with a job_id and status: "processing"; the tokens are worked through in the background.

Request body

Name	Type	Required	Description
`clientkey`	string	Required	Your secret developer API access key.
`data.tool`	string	Required	"boost" or "join".
`data.invite`	string	Required	Discord invite code or full invite URL.
`data.tokens`	string[]	Required	Discord tokens to run the job with.
`data.proxies`	string[]	Required	One proxy per token, as user:pass@host:port. Must be the same length as tokens — tokens[0] uses proxies[0], and so on.
`data.boosts_needed`	integer	Optional	Stop after this many successful joins. 0 processes every token.

clientkeystringRequired

Your secret developer API access key.

data.toolstringRequired

"boost" or "join".

data.invitestringRequired

Discord invite code or full invite URL.

data.tokensstring[]Required

Discord tokens to run the job with.

data.proxiesstring[]Required

One proxy per token, as user:pass@host:port. Must be the same length as tokens — tokens[0] uses proxies[0], and so on.

data.boosts_neededintegerOptional

Stop after this many successful joins. 0 processes every token.

Response

Name	Type	Required	Description
`job_id`	string		Unique job identifier — use it with /check-task.
`status`	string		Always "processing" on creation.

job_idstring

Unique job identifier — use it with /check-task.

statusstring

Always "processing" on creation.

curl -X POST https://api.ragecaptcha.com/create-task \
  -H "Content-Type: application/json" \
  -d '{
    "clientkey": "your-api-key",
    "data": {
      "tool": "boost",
      "invite": "discord.gg/example",
      "tokens": ["TOKEN1", "TOKEN2"],
      "proxies": ["user:pass@1.2.3.4:8080", "user:pass@1.2.3.5:8080"],
      "boosts_needed": 2
    }
  }'

tokens and proxies are paired by position. Send exactly one proxy per token — tokens[0] always runs through proxies[0].

Handoff · Endpoint

Check a job

GEThttps://api.ragecaptcha.com/check-task?job_id={job_id}&clientkey=your-api-key

Poll a job by job_id every 10 seconds and stop after 600 seconds. The status stays processing while the job runs. Once it finishes you get one result per token plus a summary.

Query parameters

Name	Type	Required	Description
`job_id`	string	Required	The job ID returned by /create-task.
`clientkey`	string	Required	Your secret developer API access key.

job_idstringRequired

The job ID returned by /create-task.

clientkeystringRequired

Your secret developer API access key.

Response (HTTP 200)

Name	Type	Required	Description
`job_id`	string		Echoes the requested job ID.
`status`	string		"processing", "completed", "partial", or "failed".
`cost`	number		Total charged for this job, in USD.
`results`	array	Finished	One entry per processed token: token, status (see token statuses) and boosts.
`summary`	object	Finished	Number of tokens per result status, e.g. { "joined": 1, "invalid": 1 }.
`stopped_early`	boolean	Finished	true when the job stopped before processing every token — for example on an invite or server problem.

job_idstring

Echoes the requested job ID.

statusstring

"processing", "completed", "partial", or "failed".

costnumber

Total charged for this job, in USD.

resultsarrayFinished

One entry per processed token: token, status (see token statuses) and boosts.

summaryobjectFinished

Number of tokens per result status, e.g. { "joined": 1, "invalid": 1 }.

stopped_earlybooleanFinished

true when the job stopped before processing every token — for example on an invite or server problem.

curl -G https://api.ragecaptcha.com/check-task \
  --data-urlencode "job_id=0edefe8b-ca72-49d8-a9c7-93ad22eedaef" \
  --data-urlencode "clientkey=your-api-key"

Example responses

{
  "job_id": "0edefe8b-ca72-49d8-a9c7-93ad22eedaef",
  "status": "processing",
  "cost": 0.0
}

Handoff · Reference

Job & token statuses

Job status

Status	Meaning
`processing`	Job is still running.
`completed`	All tokens processed successfully.
`partial`	Some tokens joined, some failed.
`failed`	Nothing joined — retry, or check the invite.

Token result status

Each entry in results carries one of these. Only joined is charged.

Status	Charged	Meaning
`joined`	Yes	Token joined and boosted.
`invalidlocked`	No	Dead token, or the token needs verification.
`bannedunderageserver_limit`	No	This token cannot join this server.
`invites_pausedguild_limited`	No	Server problem — the job stops immediately.
`invalid_inviteinvite_expired`	No	Bad invite — the job stops immediately.
`solve_failedsolver_downfailed`	No	Temporary error — retry.

Handoff · Errors

Handoff error responses

Errors return an HTTP error status with a JSON body of the form { "error": "message here" }.

HTTP	Meaning
400	Bad request — a field is missing or invalid.
401	Invalid API key.
402	Insufficient balance.
429	Rate limited — slow down.
502	Tool server unreachable — try again.
503	Service temporarily unavailable.

Ready to ship

Grab a key and start solving.

Create an account