Scarnox · Blog

Captcha solver API: how it works and how to call it

A captcha solver API is a web service you call over HTTP. You send it the details of a captcha, which are the task type, the page's sitekey and the page URL, and it returns a token that the target site accepts as proof that the challenge was passed. The Scarnox endpoint works this way and it is synchronous, so one request gives you the answer.

This guide covers the request, the response, the error shape and the details that decide whether an integration holds up in production. If you want a runnable script first, start with How to solve PopularCaptcha in Python.

What the API does and does not do

Your code finds the captcha on a page, reads its sitekey and sends it to the solver. The solver returns a token. Your code writes that token into the form field the site expects and submits the form.

The solver does not load your page, does not click anything and does not submit your form. It only produces the token. Keeping that boundary in mind makes the rest of the integration easier to reason about: everything about your session, cookies and request timing stays in your code.

Today the only live task type is PopularCaptcha, proxyless, which is PopularCaptchaTaskProxyless. Other captcha types are on the roadmap. The types of captcha guide lists which is which.

The endpoint

Send a POST request to:

POST https://api.scarnox.com/api/tasks/create
Authorization: Bearer scarnox_YOURAPIKEY
Content-Type: application/json

The body describes the task:

{
  "captcha_type": "PopularCaptchaTaskProxyless",
  "site_key": "10000000-ffff-ffff-ffff-000000000001",
  "site_url": "https://example.com/signup"
}

The three required fields are:

captcha_type: the task type. For live solves today this is PopularCaptchaTaskProxyless.
site_key: the sitekey read from the page. PopularCaptcha sitekeys are UUIDs.
site_url: the URL of the page where the captcha appears. Use the real page, not the home page, because the token is bound to the page that displayed the widget.

Three optional fields exist. proxy takes a value in the form http://user:pass@host:port and is used with the proxy task types. rqdata and is_invisible are for specific widget variants. The full list of task types and field details is in the API reference.

Synchronous means no polling

The call blocks until the token is ready. You do not poll, and there is no second "get result" request in this flow. Set your HTTP client timeout to about 185 seconds so a slow solve does not look like a network failure.

In Python with the requests library, that looks like this:

import requests

r = requests.post(
    "https://api.scarnox.com/api/tasks/create",
    headers={"Authorization": "Bearer scarnox_YOURAPIKEY"},
    json={
        "captcha_type": "PopularCaptchaTaskProxyless",
        "site_key": "10000000-ffff-ffff-ffff-000000000001",
        "site_url": "https://example.com/signup",
    },
    timeout=185,
)
data = r.json()

Read the key from an environment variable rather than writing it into the script. Anyone who can read the source should not be able to use your balance.

Reading the response

A successful solve returns an errorId of 0, the token inside solution, and a cost field:

{"errorId": 0, "solution": {"token": "..."}, "cost": ...}

A failed solve returns an errorId other than 0, plus a machine-readable errorCode and a human-readable errorDescription:

{"errorId": 1, "errorCode": "...", "errorDescription": "..."}

Check errorId in the body on every call. Do not assume that a completed HTTP request means you have a token. The rule that matters most is this: you are charged only when errorId is 0. Failed solves are free. For current rates, see the pricing page.

Token lifetime

PopularCaptcha tokens expire within about two minutes. Submit the token as soon as you receive it. Do not cache tokens for later use, and do not solve in advance of the form submission. If your code does several steps between getting the token and posting the form, move the solve to the last moment.

Putting the token in the form

Most sites read PopularCaptcha's response from a form field called h-captcha-response. Many also accept g-recaptcha-response with the same value, so sending both is a common safe choice:

requests.post("https://example.com/signup", data={
    "email": "you@example.com",
    "h-captcha-response": token,
    "g-recaptcha-response": token,
})

If the form does not accept the token, the cause is usually a sitekey or page URL that does not match the page the widget was actually on. Double-check the values before you blame the solver.

Error handling

A production integration needs a short list of habits:

Check errorId and log errorCode every time. The code is what support will ask for first.
Retry failed solves with a small backoff. Because failed solves are free, a retry does not cost you a solve, but a tight loop still wastes time and can hit your own rate limits.
Set a client timeout of about 185 seconds, and treat a timeout as an error to retry, not a success.
Keep the token and the form submission close together in time, since the token expires quickly.

The retries and error handling guide goes deeper on each of these.

Getting started

Create an account and you can start with free trial credit, no card needed. Then run the request above against a test page you control, and check that the form accepts the token before you connect it to anything that matters.