API integration recipes

Transport setup and task lifecycle instructions for the easycaptcha API. These are product documentation, separate from our use-case solution articles.

• Async hCaptcha tasks with Python and httpx

  Use the native async Python client to wait for hCaptcha jobs without blocking an event loop, with explicit polling and client cleanup.

• Read hCaptcha API balance and budget in microcents

  Use exact integer balance units, account for recognition groups and task modes, and handle admission-time credit errors even after a balance read.

• Build a bounded queue for hCaptcha jobs

  Coordinate task admission, weighted concurrency, pending observations, and recovery without using unlimited parallel submissions.

• Add burst and fast to paid hCaptcha task requests

  Choose extra weighted concurrency, higher queue priority, or both, and account for their distinct prices and limits.

• Submit and retrieve hCaptcha tasks with curl

  Inspect the raw customer API with curl, keep credentials in headers, and distinguish pending jobs, task failures, and HTTP problems.

• Attribute hCaptcha requests with a developer tag

  Send a developer tag per task request, preserve customer authentication, and report eligible paid usage separately from referrals and free-plan work.

• Prepare hCaptcha enterprise token requests

  Confirm enterprise access and supply the correct sitekey, URL, and rqdata rather than treating a regular token job as an enterprise equivalent.

• Download and verify an extension through the SDK

  Retrieve a published Chromium package, verify its size and SHA-256 through the SDK helper, and configure manifest defaults before installation.

• Call the hCaptcha task API from Go

  Use net/http with a request deadline, JSON encoding, Bearer authentication, and explicit task-state handling before reading a token.

• Use AxiosClient for hCaptcha job requests

  Choose the axios SDK backend, optionally inject an axios instance, and preserve raw responses and task-creation retry behavior.

• Use native fetch with the easycaptcha JavaScript SDK

  Integrate FetchClient in Node.js, supply an optional fetch implementation, and keep task status and transport errors separate.

• hCaptcha solver API for JavaScript and TypeScript

  Use the typed easycaptcha JavaScript SDK with fetch, axios, ky, or XHR. Create token jobs, wait for completion, and keep API credentials on the server.

• Use the ky transport for hCaptcha tasks

  Integrate KyClient while retaining SDK-controlled response handling, deadlines, and the distinction between creation and lookup retries.

• Use hold and long polling for hCaptcha tasks

  Choose server wait intervals and HTTP deadlines that reduce lookup traffic while keeping creation, pending work, and cancellation behavior explicit.

• Keep extension settings in a dedicated browser profile

  Use a persistent profile for an authorized browser workflow, configure the extension through its popup, and avoid sharing one profile across running processes.

• Use curl_cffi as an easycaptcha SDK transport

  Integrate the curl_cffi backend without changing public SDK methods, and keep API transport settings separate from token-worker proxy settings.

• hCaptcha solver API for Python

  Create hCaptcha token tasks in Python with the easycaptcha SDK. Choose sync or async clients, poll results, and handle failures without duplicate submissions.

• Configure httpx clients for the hCaptcha API

  Use sync or native async httpx transports with the easycaptcha SDK and manage owned sessions, timeouts, and response states deliberately.

• Use the easycaptcha Python SDK with requests

  Choose the requests transport, reuse sessions, preserve SDK error handling, and avoid treating a failed POST as permission to submit again.

• Call the hCaptcha API with the standard-library Python backend

  Use the urllib SDK backend without an optional HTTP dependency, and understand its synchronous and threaded async behavior.

• Integrate hCaptcha area-selection recognition

  Submit area-selection challenges with stable image identifiers, then map returned coordinate data to the correct original image and UI scale.

• Submit binary hCaptcha image-recognition jobs

  Preserve image task keys and question data when submitting a binary challenge, then read keyed answers rather than assuming a positional token result.

• Integrate hCaptcha drag-and-drop recognition

  Preserve movable entity identities, source geometry, and image keys in drag-and-drop jobs, then interpret placement results without losing their mapping.

• Send hCaptcha task feedback after observing the outcome

  Report accepted and rejected results through the SDK feedback methods, and separate actual failures from local timeouts or unknown outcomes.

• Recover hCaptcha jobs after timeouts and worker restarts

  Persist task IDs, separate unknown submissions from rejected jobs, and resume lookups without creating duplicate paid tasks.

• Configure a proxy for hCaptcha token workers

  Use the token request proxy object, keep worker and API transport proxies distinct, and redact network credentials from diagnostics.

• Type hCaptcha job requests and results in TypeScript

  Use discriminated job request types to separate recognition, token, and enterprise tasks, then narrow terminal results before reading them.