Skip to main content
Use 2Captcha through Corsair: one client, typed API calls. 2Captcha is a paid captcha-solving service: you send it a captcha from a page your own automation works on, its workers solve it, and you get back a token or text to submit. Copy your API key from the 2Captcha dashboard (https://2captcha.com/enterpage); the plugin sends it as clientKey to API v2 at api.2captcha.com. Things to know:
  • Every answer is an envelope. 2Captcha returns HTTP 200 for almost everything and reports the outcome in errorId: 0 is success, anything else comes with an errorCode such as ERROR_ZERO_BALANCE. The plugin throws TwoCaptchaAPIError with that code, so a resolved promise means the call worked.
  • Creating a task costs money. tasks.create charges the account per task, so it is destructive. What happens depends on the permissions mode (Permissions): cautious needs an approval first (with a database Corsair records the request and the call throws until it is approved; without one the call is refused), strict and readonly refuse it, and open or no mode runs it. It is not replayed after a 5xx, since the task may already exist; a 429 or ERROR_NO_SLOT_AVAILABLE, where nothing was created, is retried. With no funds it answers ERROR_ZERO_BALANCE.
  • Poll for the result. tasks.result answers status: "processing" while workers solve the task; poll every 5-10 seconds until status is ready, then read solution (its fields depend on the captcha kind) and cost.
  • Report outcomes. account.reportCorrect and account.reportIncorrect take the task id. A rejected answer is reviewed by 2Captcha, which may refund it; the task is not solved again, and a report cannot be taken back.
  • Captcha kinds. tasks.create takes a type such as RecaptchaV2TaskProxyless, TurnstileTaskProxyless or ImageToTextTask, and the fields that kind needs in task (see https://2captcha.com/api-docs). Kinds without “Proxyless” take your proxy fields.
  • Retries. ERROR_NO_SLOT_AVAILABLE (queue full, nothing created) is retried with backoff. Other codes are permanent. A 5xx is retried for tasks.result and account.balance only.
  • No callbacks in this plugin. 2Captcha can POST a result to a registered URL, but this plugin does not receive that delivery; poll tasks.result instead.
What you get:
  • 5 typed API operations

Setup

1

Install

2

Add the plugin

corsair.ts
With multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.
3

Choose authentication

4

Connect a tenant

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.

Example API calls

Read the account balance
Create a captcha task for a page
See the full list on the API page.

What’s next

API reference

Every twocaptcha.api.* operation with input and output types.

Connect / OAuth

createLink, Hub delivery, and tenant connect flows.

Use with agents

Expose this plugin’s operations as MCP tools.