hCaptcha

Summary

Property	Value
v1 type	hcaptcha
Compatibility names	HCaptchaTask, HCaptchaTaskProxyless
Proxy	optional (Proxies)
Deadline	120 seconds (starting value). A task not solved by then fails with timeout and is not charged.
2captcha legacy API	method=hcaptcha (details)

Parameters

The params object of POST /v1/tasks. Unknown fields are rejected with 422 invalid_params.

Field	Type	Description
website_url required	string	Full URL of the page that shows the captcha (http or https). format: uri · pattern: ^[Hh][Tt][Tt][Pp][Ss]?:// · min length 8 · max length 4,096
website_key required	string	The site key of the captcha widget. min length 1 · max length 512
is_invisible optional	boolean	true for the invisible hCaptcha.
enterprise_payload optional	object	Extra enterprise parameters passed to the widget as is, e.g. {"s": "..."} for reCAPTCHA Enterprise or {"rqdata": "..."} for hCaptcha. max 32 keys
user_agent optional	string	Browser User-Agent. min length 1 · max length 1,024
proxy optional	object	Proxy the solver must use. login and password are used in memory only and are never stored or logged.
proxy.type required	enum	one of "http", "https", "socks4", "socks5"
proxy.host required	string	IP address or host name. Private and loopback addresses are rejected. min length 1 · max length 253
proxy.port required	integer	≥ 1 · ≤ 65535
proxy.login optional	string	max length 256
proxy.password optional	string	max length 256

Solution

The solution object of a solved task.

Field	Type	Description
token required	string	Token to submit to the target site. Single use. min length 1
user_agent optional	string	User-Agent the token was obtained with; use it when submitting the token. min length 1 · max length 1,024
resp_key optional	string	Value some sites require together with the token (respKey).

Example: native API (v1)

Runs as is with a test key (nop_test_…) in the sandbox; use a live key for real tasks.

POST /v1/tasks

{
  "type": "hcaptcha",
  "params": {
    "website_url": "https://accounts.hcaptcha.com/demo",
    "website_key": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}

curl

export NOPTCHA_KEY=nop_test_...  # your test or live key

# waits up to 60 s; 200 = finished (solved or failed), 202 = still processing
IDEMPOTENCY_KEY=$(uuidgen)  # one key per task you want; a retry of the same request reuses it
curl -s -X POST "https://api.noptcha.com/v1/tasks" \
  -H "Authorization: Bearer $NOPTCHA_KEY" \
  -H 'Prefer: wait=60' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  -d @- <<EOF
{
  "type": "hcaptcha",
  "params": {
    "website_url": "https://accounts.hcaptcha.com/demo",
    "website_key": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}
EOF

# on 202: long-poll with the "id" from the response
TASK_ID=...
curl -s "https://api.noptcha.com/v1/tasks/$TASK_ID?wait=60" \
  -H "Authorization: Bearer $NOPTCHA_KEY"

Python

import os
import time
import uuid

import requests

API = "https://api.noptcha.com"
HEADERS = {"Authorization": f"Bearer {os.environ['NOPTCHA_KEY']}"}  # a nop_test_ key runs in the sandbox

# One Idempotency-Key per task you want. If you retry this request after a network error, send the same key and
# the same body bytes: you get the same task back, not a second one (see Idempotency on the Tasks page).
idempotency_key = str(uuid.uuid4())
r = requests.post(
    f"{API}/v1/tasks",
    headers={**HEADERS, "Prefer": "wait=60", "Idempotency-Key": idempotency_key},
    json={
        "type": "hcaptcha",
        "params": {
            "website_url": "https://accounts.hcaptcha.com/demo",
            "website_key": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
        },
    },
    timeout=100,
)
task = r.json()
if r.status_code >= 400:
    raise RuntimeError(f"{task['code']}: {task.get('detail', '')}")
while task["status"] == "processing":  # 202: not finished within the wait
    time.sleep(1)  # a long poll can return early (for example when wait slots are full)
    r = requests.get(f"{API}/v1/tasks/{task['id']}", params={"wait": 60}, headers=HEADERS, timeout=100)
    task = r.json()
    if r.status_code >= 400:
        raise RuntimeError(f"{task['code']}: {task.get('detail', '')}")

if task["status"] == "solved":
    print(task["solution"])
else:
    print("failed:", task["error"]["code"], task["error"]["message"])

Node.js

import { randomUUID } from 'node:crypto';

const API = 'https://api.noptcha.com';
const HEADERS = { Authorization: `Bearer ${process.env.NOPTCHA_KEY}` }; // a nop_test_ key runs in the sandbox

async function v1(path, init = {}) {
  const res = await fetch(`${API}${path}`, { ...init, headers: { ...HEADERS, ...init.headers } });
  const data = await res.json();
  if (!res.ok) throw new Error(`${data.code}: ${data.detail ?? ''}`);
  return data;
}

// One Idempotency-Key per task you want. If you retry this request after a network error, send the same key and
// the same body bytes: you get the same task back, not a second one (see Idempotency on the Tasks page).
const idempotencyKey = randomUUID();
let task = await v1('/v1/tasks', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Prefer: 'wait=60', 'Idempotency-Key': idempotencyKey },
  body: JSON.stringify({
    type: "hcaptcha",
    params: {
      website_url: "https://accounts.hcaptcha.com/demo",
      website_key: "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
    },
  }),
});
while (task.status === 'processing') {
  await new Promise((r) => setTimeout(r, 1000)); // a long poll can return early (for example when wait slots are full)
  task = await v1(`/v1/tasks/${task.id}?wait=60`); // long poll
}
if (task.status === 'solved') console.log(task.solution);
else console.log('failed:', task.error.code, task.error.message);

In the sandbox the task is solved at once and solution is:

{
  "token": "NOPTCHA_TEST_TOKEN_7259140378796032",
  "user_agent": "Mozilla/5.0 (Noptcha test)"
}

Compatibility API

Name	Proxy	Notes
HCaptchaTask	required
HCaptchaTaskProxyless	ignored

Task fields (in task, next to type) and the v1 parameter each one becomes:

Compatibility field	v1 parameter
enterprisePayload	enterprise_payload
isInvisible	is_invisible
rqdata	enterprise_payload.rqdata
userAgent	user_agent
websiteKey	website_key
websiteURL	website_url
proxyType, proxyAddress, proxyPort, proxyLogin, proxyPassword	proxy (Proxies)

Solution fields in getTaskResult:

Compatibility field	v1 solution field
gRecaptchaResponse	token
userAgent	user_agent
respKey	resp_key

Example: compatibility API

POST /createTask

{
  "clientKey": "nop_test_…",
  "task": {
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}

curl

export NOPTCHA_KEY=nop_test_...  # your test or live key

# 1. create the task
curl -s -X POST "https://api.noptcha.com/createTask" \
  -H 'Content-Type: application/json' \
  -d @- <<EOF
{
  "clientKey": "$NOPTCHA_KEY",
  "task": {
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}
EOF

# 2. poll with the taskId from step 1 every few seconds until "status" is "ready"
TASK_ID=...
curl -s -X POST "https://api.noptcha.com/getTaskResult" \
  -H 'Content-Type: application/json' \
  -d @- <<EOF
{
  "clientKey": "$NOPTCHA_KEY",
  "taskId": $TASK_ID
}
EOF

Python

import os
import time

import requests

API = "https://api.noptcha.com"
KEY = os.environ["NOPTCHA_KEY"]  # a nop_test_ key runs in the sandbox: free, fixed answers


def call(method, payload):
    r = requests.post(f"{API}/{method}", json={"clientKey": KEY, **payload}, timeout=30)
    r.raise_for_status()
    data = r.json()
    if data["errorId"]:
        raise RuntimeError(f"{data['errorCode']}: {data.get('errorDescription', '')}")
    return data


created = call("createTask", {"task": {
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
}})
result = created  # some types are solved at once and come back with "status": "ready"
deadline = time.time() + 300
while result.get("status") != "ready":
    if time.time() > deadline:
        raise TimeoutError(created["taskId"])
    time.sleep(3)
    result = call("getTaskResult", {"taskId": created["taskId"]})
print(result["solution"])

Node.js

const API = 'https://api.noptcha.com';
const KEY = process.env.NOPTCHA_KEY; // a nop_test_ key runs in the sandbox: free, fixed answers

async function call(method, payload) {
  const res = await fetch(`${API}/${method}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ clientKey: KEY, ...payload }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const data = await res.json();
  if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription ?? ''}`);
  return data;
}

const created = await call('createTask', { task: {
  type: "HCaptchaTaskProxyless",
  websiteURL: "https://accounts.hcaptcha.com/demo",
  websiteKey: "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
} });
let result = created; // some types are solved at once and come back with status "ready"
const deadline = Date.now() + 300_000;
while (result.status !== 'ready') {
  if (Date.now() > deadline) throw new Error(`timed out: ${created.taskId}`);
  await new Promise((r) => setTimeout(r, 3000));
  result = await call('getTaskResult', { taskId: created.taskId });
}
console.log(result.solution);

In the sandbox getTaskResult returns "status": "ready" and solution:

{
  "gRecaptchaResponse": "NOPTCHA_TEST_TOKEN_7259140378796032",
  "userAgent": "Mozilla/5.0 (Noptcha test)"
}