Schemas

Every schema of the OpenAPI description. Task parameter and solution schemas are explained on the task type pages.

Amount

string · pattern: ^-?[0-9]+\.[0-9]{6}$

Decimal US dollars with 6 places.

Balance

object

Field	Type	Description
`available` required	`Amount`	What new tasks can use: cash + promo + credit limit − held.
`cash` required	`Amount`	Decimal US dollars with 6 places.
`credit_limit` required	`Amount`	Decimal US dollars with 6 places.
`currency` required	`const "USD"`
`held` required	`Amount`	Reserved for tasks in flight.
`promo` required	`Amount`	Promotional credit.

CallbackUrl

string | null · max length 2,048

Where to POST the task's final result (a task.solved or task.failed event, see Webhooks). http or https, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. null or "": no callback.

Catalog

object

Field	Type	Description
`currency` required	`const "USD"`
`data` required	`array of TypeInfo`	Every public task type with a list price, ordered by `type`.
`data.[item]` optional	`TypeInfo`
`placeholder` required	`boolean`	`true` when the prices are placeholders, not real prices (test deployments only).
`price_version` required	`integer`	Version of the price list the prices come from.

CloudflareChallengeParams

Task type page: /docs/task-types/cloudflare-challenge/

object

Field	Type	Description
`block_image` optional	`boolean`	Do not load images of the target page (saves proxy traffic).
`post_data` optional	`object`	If set, submitted to website_url as an HTML form POST. max 64 keys
`post_data.<any key>` optional	`string \| number \| boolean`
`proxy` required	`Proxy`	Proxy the solver must use. login and password are used in memory only and are never stored or logged.
`required_cookies` optional	`array of string`	Cookie names that must all be obtained for the task to succeed, e.g. ["cf_clearance"]. max items 32 · unique items
`user_agent` optional	`UserAgent`	Usually omit it. The User-Agent actually used is returned in the solution.
`wait_load` optional	`boolean`	Wait for the page's network activity to settle before returning.
`website_url` required	`WebsiteUrl`	Full URL of the page that shows the captcha (http or https).

CloudflareChallengeSolution

Task type page: /docs/task-types/cloudflare-challenge/

object

Field	Type	Description
`content` optional	`string`	HTML of the target page after passing the challenge.
`cookies` required	`object`	Cookies after passing the challenge, name to value; usually includes cf_clearance.
`cookies.<any key>` optional	`string`
`headers` optional	`object`	Response headers of the target page.
`headers.<any key>` optional	`string`
`request_headers` optional	`object`	Request headers of the browser's last request to the target page.
`request_headers.<any key>` optional	`string`
`user_agent` required	`UserAgent`	User-Agent the cookies are bound to; use it for every follow-up request.

CompatBalance

object

Field	Type	Description
`balance` required	`number`	Available balance in US dollars.
`errorId` required	`const 0`

CompatCallback

one of

The compatibility API's callback body: the getTaskResult response for the final result, plus taskId. Callbacks for sandbox tasks (created with a test key) also carry "sandbox": true; treat such a callback as a test, never as a real result.

One of:

object
object

CompatCreateTaskRequest

object

Field	Type	Description
`clientKey` required	`string`	Your key (`nop_live_…` or `nop_test_…`).
`appId` optional	`integer \| string`	Same as `softId`.
`callbackUrl` optional	`string`	Where to POST the final result (the `getTaskResult` response plus `taskId`, see the `compatCallback` webhook). Same rules as v1 `callback_url`; an invalid URL is `ERROR_INCORRECT_SESSION_DATA`. Empty: no callback. max length 2,048
`softId` optional	`integer \| string`	Developer programme ID (digits); recorded with the task.
`task` required	`CompatTask`	The task in anti-captcha's format: `type` (see `CompatTaskType`) plus that type's fields (`websiteURL`, `websiteKey`, `body`, …; the field map per name is in `CompatTaskType`). Unknown fields are ignored. Parameters are validated against the canonical type's schema (see `CreateTaskRequest`). Proxy names (`…Task`, without `Proxyless`) need a proxy: `proxyType` (`http`, `https`, `socks4`, `socks5`), `proxyAddress`, `proxyPort`, optional `proxyLogin` and `proxyPassword`; or `proxy` as a URL string `http://user:pass@host:port`. Proxyless names ignore proxy fields.

CompatCreateTaskResult

object

Field	Type	Description
`cost` optional	`string`	Only when solved synchronously. pattern: ^[0-9]+\.[0-9]{6}$
`errorId` required	`const 0`
`solution` optional	`CompatSolution`	The answer in anti-captcha's field names for the task type name used to create the task (for example `gRecaptchaResponse` and `userAgent` for reCAPTCHA, `token` for Turnstile, `text` for images). The mapping from the canonical solution is listed per name in `CompatTaskType` (`solution`). Tasks created through v1 use the first compatible name of their type and variant.
`status` optional	`const "ready"`	Only when solved synchronously.
`taskId` required	`integer`	Task ID (53-bit integer, safe in JavaScript). format: int64

CompatError

object

A request or task error. errorCode values (anti-captcha's codes; new ones may be added):

errorCode	when
`ERROR_KEY_DOES_NOT_EXIST`	key malformed, unknown, revoked or expired; or the key lacks the scope this endpoint needs
`ERROR_ZERO_BALANCE`	balance too low, or the key's budget is used up
`ERROR_IP_NOT_ALLOWED`	client IP not in the key's allowlist
`ERROR_IP_BLOCKED`	too many invalid keys from this IP
`ERROR_ACCOUNT_SUSPENDED`	the organization is suspended
`ERROR_NO_SLOT_AVAILABLE`	no capacity, concurrency limit, create rate limit (also sandbox limits), temporary or internal error; retry later
`ERROR_TASK_NOT_SUPPORTED`	unknown task type name, or type not allowed for the key
`ERROR_TASK_ABSENT`	`task` missing or not an object (or the body could not be read)
`ERROR_NO_SUCH_CAPCHA_ID`	`taskId` missing, unknown, expired or of another organization; report for an unsolved task
`ERROR_INCORRECT_SESSION_DATA`	a parameter does not match the schema (`errorDescription` names it), or `callbackUrl` is not allowed
`ERROR_RECAPTCHA_INVALID_SITEKEY`	the site key is invalid (parameter check or solver)
`ERROR_RECAPTCHA_INVALID_DOMAIN`	the website URL, API domain or subdomain is invalid or not allowed
`ERROR_ZERO_CAPTCHA_FILESIZE`	the image is missing or empty
`ERROR_TOO_BIG_CAPTCHA_FILESIZE`	the image (characters or pixels) or the request body is too large
`ERROR_IMAGE_TYPE_NOT_SUPPORTED`	the image is not valid base64, not a PNG, JPEG, GIF, WebP or BMP image, or malformed or truncated (checked when the task is created); or the solver could not read it (task failed)
`ERROR_CAPTCHA_UNSOLVABLE`	the task failed: unsolvable, timed out, or no solver accepts these parameters
`ERROR_PROXY_CONNECT_REFUSED`, `ERROR_PROXY_CONNECT_TIMEOUT`, `ERROR_PROXY_READ_TIMEOUT`, `ERROR_PROXY_BANNED`, `ERROR_PROXY_TRANSPARENT`, `ERROR_PROXY_HAS_NO_IMAGE_SUPPORT`, `ERROR_PROXY_INCOMPATIBLE_HTTP_VERSION`	the proxy could not be used (task failed)
`ERROR_TOKEN_EXPIRED`	the solver reported the token expired (task failed)

Field	Type	Description
`errorCode` required	`string`
`errorDescription` required	`string`
`errorId` required	`const 1`

CompatKeyRequest

object

Field	Type	Description
`clientKey` required	`string`	Your key (`nop_live_…` or `nop_test_…`).

CompatReportResult

object

Field	Type	Description
`errorId` required	`const 0`
`status` required	`const "success"`

CompatSolution

object

The answer in anti-captcha's field names for the task type name used to create the task (for example gRecaptchaResponse and userAgent for reCAPTCHA, token for Turnstile, text for images). The mapping from the canonical solution is listed per name in CompatTaskType (solution). Tasks created through v1 use the first compatible name of their type and variant.

CompatTask

object

The task in anti-captcha's format: type (see CompatTaskType) plus that type's fields (websiteURL, websiteKey, body, …; the field map per name is in CompatTaskType). Unknown fields are ignored. Parameters are validated against the canonical type's schema (see CreateTaskRequest).

Proxy names (…Task, without Proxyless) need a proxy: proxyType (http, https, socks4, socks5), proxyAddress, proxyPort, optional proxyLogin and proxyPassword; or proxy as a URL string http://user:pass@host:port. Proxyless names ignore proxy fields.

Field Type Description

proxyAddress
optional string

proxyLogin
optional string

proxyPassword
optional string

proxyPort
optional integer | string

proxyType
optional enum one of "http", "https", "socks4", "socks5"

type
required

CompatTaskType

Task type name in the compatibility API (case-insensitive). Each name maps to a canonical type and variant (see CreateTaskRequest for the parameters). Names ending in Proxyless ignore proxy fields; the others require a proxy. Unknown names: ERROR_TASK_NOT_SUPPORTED.

x-noptcha-aliases lists, per name, fields (compatibility field → canonical parameter; null: accepted but not passed on; to_array: a single value is wrapped in an array) and solution (canonical solution field → compatibility field; index_bools: selected indexes become one boolean per image or tile).

Name	Canonical type	Variant	Notes
`FunCaptchaClassification`	`image.funcaptcha`	proxyless
`FunCaptchaTask`	`funcaptcha`	proxy
`FunCaptchaTaskProxyless`	`funcaptcha`	proxyless
`HCaptchaClassification`	`image.grid.hcaptcha`	proxyless
`HCaptchaTask`	`hcaptcha`	proxy
`HCaptchaTaskProxyless`	`hcaptcha`	proxyless
`ImageToTextTask`	`image.text`	proxyless
`NoCaptchaTask`	`recaptcha.v2`	proxy
`NoCaptchaTaskProxyless`	`recaptcha.v2`	proxyless
`ReCaptchaV2Classification`	`image.grid.recaptcha`	proxyless
`RecaptchaV2EnterpriseTask`	`recaptcha.v2.enterprise`	proxy
`RecaptchaV2EnterpriseTaskProxyless`	`recaptcha.v2.enterprise`	proxyless
`RecaptchaV2Task`	`recaptcha.v2`	proxy
`RecaptchaV2TaskProxyless`	`recaptcha.v2`	proxyless
`RecaptchaV3EnterpriseTask`	`recaptcha.v3.enterprise`	proxyless
`RecaptchaV3TaskProxyless`	`recaptcha.v3`	proxyless	`isEnterprise: true` → `recaptcha.v3.enterprise`
`TurnstileTask`	`turnstile`	proxy
`TurnstileTaskProxyless`	`turnstile`	proxyless

CompatTaskProcessing

object

Field	Type	Description
`errorId` required	`const 0`
`status` required	`const "processing"`

CompatTaskReady

object

Field	Type	Description
`cost` required	`string`	US dollars, e.g. `"0.001000"`. pattern: ^[0-9]+\.[0-9]{6}$
`createTime` required	`integer`	Unix seconds.
`endTime` required	`integer`	Unix seconds.
`errorId` required	`const 0`
`ip` required	`string`	Client IP that created the task (empty for sandbox tasks).
`solution` required	`CompatSolution`	The answer in anti-captcha's field names for the task type name used to create the task (for example `gRecaptchaResponse` and `userAgent` for reCAPTCHA, `token` for Turnstile, `text` for images). The mapping from the canonical solution is listed per name in `CompatTaskType` (`solution`). Tasks created through v1 use the first compatible name of their type and variant.
`solveCount` required	`integer`	Solver attempts. ≥ 1
`status` required	`const "ready"`

CompatTaskRequest

object

Field	Type	Description
`clientKey` required	`string`	Your key (`nop_live_…` or `nop_test_…`).
`taskId` required	`one of`	The task ID, as a number or a string of digits. one of: `integer`, `string`

CompatTaskType

string

Name	Canonical type	Variant	Notes
`FunCaptchaClassification`	`image.funcaptcha`	proxyless
`FunCaptchaTask`	`funcaptcha`	proxy
`FunCaptchaTaskProxyless`	`funcaptcha`	proxyless
`HCaptchaClassification`	`image.grid.hcaptcha`	proxyless
`HCaptchaTask`	`hcaptcha`	proxy
`HCaptchaTaskProxyless`	`hcaptcha`	proxyless
`ImageToTextTask`	`image.text`	proxyless
`NoCaptchaTask`	`recaptcha.v2`	proxy
`NoCaptchaTaskProxyless`	`recaptcha.v2`	proxyless
`ReCaptchaV2Classification`	`image.grid.recaptcha`	proxyless
`RecaptchaV2EnterpriseTask`	`recaptcha.v2.enterprise`	proxy
`RecaptchaV2EnterpriseTaskProxyless`	`recaptcha.v2.enterprise`	proxyless
`RecaptchaV2Task`	`recaptcha.v2`	proxy
`RecaptchaV2TaskProxyless`	`recaptcha.v2`	proxyless
`RecaptchaV3EnterpriseTask`	`recaptcha.v3.enterprise`	proxyless
`RecaptchaV3TaskProxyless`	`recaptcha.v3`	proxyless	`isEnterprise: true` → `recaptcha.v3.enterprise`
`TurnstileTask`	`turnstile`	proxy
`TurnstileTaskProxyless`	`turnstile`	proxyless

Confidences

array of number · max items 64

CreateCloudflareChallengeTaskRequest

Task type page: /docs/task-types/cloudflare-challenge/

object

Cloudflare challenge page (cloudflare.challenge, family cloudflare, active). Variants: proxy (params.proxy is required). Tasks not solved within 120 seconds fail with timeout.

Field	Type	Description
`callback_url` optional	`CallbackUrl`	Where to POST the task's final result (a `task.solved` or `task.failed` event, see Webhooks). `http` or `https`, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. `null` or `""`: no callback.
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`CloudflareChallengeParams`
`type` required	`const "cloudflare.challenge"`

CreateFuncaptchaTaskRequest

Task type page: /docs/task-types/funcaptcha/

object

FunCaptcha (Arkose Labs) (funcaptcha, family arkose, beta). Variants: proxyless, proxy (the proxy variant when params.proxy is given). Tasks not solved within 180 seconds fail with timeout.

Compatibility API names: FunCaptchaTask (proxy), FunCaptchaTaskProxyless (proxyless).

Field	Type	Description
`callback_url` optional	`CallbackUrl`	Where to POST the task's final result (a `task.solved` or `task.failed` event, see Webhooks). `http` or `https`, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. `null` or `""`: no callback.
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`FuncaptchaParams`
`type` required	`const "funcaptcha"`

CreateHcaptchaTaskRequest

Task type page: /docs/task-types/hcaptcha/

object

hCaptcha (hcaptcha, family hcaptcha, active). Variants: proxyless, proxy (the proxy variant when params.proxy is given). Tasks not solved within 120 seconds fail with timeout.

Compatibility API names: HCaptchaTask (proxy), HCaptchaTaskProxyless (proxyless).

Field	Type	Description
`callback_url` optional	`CallbackUrl`	Where to POST the task's final result (a `task.solved` or `task.failed` event, see Webhooks). `http` or `https`, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. `null` or `""`: no callback.
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`HcaptchaParams`
`type` required	`const "hcaptcha"`

CreateImageFuncaptchaTaskRequest

Task type page: /docs/task-types/image-funcaptcha/

object

FunCaptcha image (image.funcaptcha, family image, beta). Variants: proxyless. Tasks not solved within 60 seconds fail with timeout.

Compatibility API names: FunCaptchaClassification (proxyless).

Field	Type	Description
`callback_url` optional	`CallbackUrl`	Where to POST the task's final result (a `task.solved` or `task.failed` event, see Webhooks). `http` or `https`, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. `null` or `""`: no callback.
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`ImageFuncaptchaParams`
`type` required	`const "image.funcaptcha"`

CreateImageGridAwsTaskRequest

Task type page: /docs/task-types/image-grid-aws/

object

AWS WAF image grid (image.grid.aws, family image, beta). Variants: proxyless. Tasks not solved within 60 seconds fail with timeout.

Field	Type	Description
`callback_url` optional	`CallbackUrl`	Where to POST the task's final result (a `task.solved` or `task.failed` event, see Webhooks). `http` or `https`, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. `null` or `""`: no callback.
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`ImageGridAwsParams`
`type` required	`const "image.grid.aws"`

CreateImageGridHcaptchaTaskRequest

Task type page: /docs/task-types/image-grid-hcaptcha/

object

hCaptcha image grid (image.grid.hcaptcha, family image, active). Variants: proxyless. Tasks not solved within 60 seconds fail with timeout.

Compatibility API names: HCaptchaClassification (proxyless).

Field	Type	Description
`callback_url` optional	`CallbackUrl`	Where to POST the task's final result (a `task.solved` or `task.failed` event, see Webhooks). `http` or `https`, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. `null` or `""`: no callback.
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`ImageGridHcaptchaParams`
`type` required	`const "image.grid.hcaptcha"`

CreateImageGridRecaptchaTaskRequest

Task type page: /docs/task-types/image-grid-recaptcha/

object

reCAPTCHA image grid (image.grid.recaptcha, family image, active). Variants: proxyless. Tasks not solved within 60 seconds fail with timeout.

Compatibility API names: ReCaptchaV2Classification (proxyless).

Field	Type	Description
`callback_url` optional	`CallbackUrl`	Where to POST the task's final result (a `task.solved` or `task.failed` event, see Webhooks). `http` or `https`, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. `null` or `""`: no callback.
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`ImageGridRecaptchaParams`
`type` required	`const "image.grid.recaptcha"`

CreateImageTextTaskRequest

Task type page: /docs/task-types/image-to-text/

object

Image to text (image.text, family image, active). Variants: proxyless. Tasks not solved within 60 seconds fail with timeout.

Compatibility API names: ImageToTextTask (proxyless).

Field	Type	Description
`callback_url` optional	`CallbackUrl`	Where to POST the task's final result (a `task.solved` or `task.failed` event, see Webhooks). `http` or `https`, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. `null` or `""`: no callback.
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`ImageTextParams`
`type` required	`const "image.text"`

CreateRecaptchaV2EnterpriseTaskRequest

Task type page: /docs/task-types/recaptcha-v2-enterprise/

object

reCAPTCHA v2 Enterprise (recaptcha.v2.enterprise, family recaptcha, active). Variants: proxyless, proxy (the proxy variant when params.proxy is given). Tasks not solved within 120 seconds fail with timeout.

Compatibility API names: RecaptchaV2EnterpriseTask (proxy), RecaptchaV2EnterpriseTaskProxyless (proxyless).

Field	Type	Description
`callback_url` optional	`CallbackUrl`	Where to POST the task's final result (a `task.solved` or `task.failed` event, see Webhooks). `http` or `https`, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. `null` or `""`: no callback.
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`RecaptchaV2EnterpriseParams`
`type` required	`const "recaptcha.v2.enterprise"`

CreateRecaptchaV2TaskRequest

Task type page: /docs/task-types/recaptcha-v2/

object

reCAPTCHA v2 (recaptcha.v2, family recaptcha, active). Variants: proxyless, proxy (the proxy variant when params.proxy is given). Tasks not solved within 120 seconds fail with timeout.

Compatibility API names: NoCaptchaTask (proxy), NoCaptchaTaskProxyless (proxyless), RecaptchaV2Task (proxy), RecaptchaV2TaskProxyless (proxyless).

Field	Type	Description
`callback_url` optional	`CallbackUrl`	Where to POST the task's final result (a `task.solved` or `task.failed` event, see Webhooks). `http` or `https`, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. `null` or `""`: no callback.
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`RecaptchaV2Params`
`type` required	`const "recaptcha.v2"`

CreateRecaptchaV3EnterpriseTaskRequest

Task type page: /docs/task-types/recaptcha-v3-enterprise/

object

reCAPTCHA v3 Enterprise (recaptcha.v3.enterprise, family recaptcha, active). Variants: proxyless. Tasks not solved within 120 seconds fail with timeout.

Compatibility API names: RecaptchaV3EnterpriseTask (proxyless), RecaptchaV3TaskProxyless (proxyless, with isEnterprise: true).

Field	Type	Description
`callback_url` optional	`CallbackUrl`	Where to POST the task's final result (a `task.solved` or `task.failed` event, see Webhooks). `http` or `https`, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. `null` or `""`: no callback.
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`RecaptchaV3EnterpriseParams`
`type` required	`const "recaptcha.v3.enterprise"`

CreateRecaptchaV3TaskRequest

Task type page: /docs/task-types/recaptcha-v3/

object

reCAPTCHA v3 (recaptcha.v3, family recaptcha, active). Variants: proxyless. Tasks not solved within 120 seconds fail with timeout.

Compatibility API names: RecaptchaV3TaskProxyless (proxyless).

Field	Type	Description
`callback_url` optional	`CallbackUrl`	Where to POST the task's final result (a `task.solved` or `task.failed` event, see Webhooks). `http` or `https`, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. `null` or `""`: no callback.
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`RecaptchaV3Params`
`type` required	`const "recaptcha.v3"`

CreateTaskRequest

one of

A task: type selects the parameters schema. New types may be added.

`type`	Name	Family	Variants	Timeout	Status
`cloudflare.challenge`	Cloudflare challenge page	`cloudflare`	`proxy`	120 s	active
`funcaptcha`	FunCaptcha (Arkose Labs)	`arkose`	`proxyless`, `proxy`	180 s	beta
`hcaptcha`	hCaptcha	`hcaptcha`	`proxyless`, `proxy`	120 s	active
`image.funcaptcha`	FunCaptcha image	`image`	`proxyless`	60 s	beta
`image.grid.aws`	AWS WAF image grid	`image`	`proxyless`	60 s	beta
`image.grid.hcaptcha`	hCaptcha image grid	`image`	`proxyless`	60 s	active
`image.grid.recaptcha`	reCAPTCHA image grid	`image`	`proxyless`	60 s	active
`image.text`	Image to text	`image`	`proxyless`	60 s	active
`recaptcha.v2`	reCAPTCHA v2	`recaptcha`	`proxyless`, `proxy`	120 s	active
`recaptcha.v2.enterprise`	reCAPTCHA v2 Enterprise	`recaptcha`	`proxyless`, `proxy`	120 s	active
`recaptcha.v3`	reCAPTCHA v3	`recaptcha`	`proxyless`	120 s	active
`recaptcha.v3.enterprise`	reCAPTCHA v3 Enterprise	`recaptcha`	`proxyless`	120 s	active
`turnstile`	Cloudflare Turnstile	`cloudflare`	`proxyless`, `proxy`	120 s	active

One of (selected by type):

CreateCloudflareChallengeTaskRequest — Cloudflare challenge page (cloudflare.challenge, family cloudflare, active). Variants: proxy (params.proxy is required). Tasks not solved within 120 seconds fail with timeout.
CreateFuncaptchaTaskRequest — FunCaptcha (Arkose Labs) (funcaptcha, family arkose, beta). Variants: proxyless, proxy (the proxy variant when params.proxy is given). Tasks not solved within 180 seconds fail with timeout.
CreateHcaptchaTaskRequest — hCaptcha (hcaptcha, family hcaptcha, active). Variants: proxyless, proxy (the proxy variant when params.proxy is given). Tasks not solved within 120 seconds fail with timeout.
CreateImageFuncaptchaTaskRequest — FunCaptcha image (image.funcaptcha, family image, beta). Variants: proxyless. Tasks not solved within 60 seconds fail with timeout.
CreateImageGridAwsTaskRequest — AWS WAF image grid (image.grid.aws, family image, beta). Variants: proxyless. Tasks not solved within 60 seconds fail with timeout.
CreateImageGridHcaptchaTaskRequest — hCaptcha image grid (image.grid.hcaptcha, family image, active). Variants: proxyless. Tasks not solved within 60 seconds fail with timeout.
CreateImageGridRecaptchaTaskRequest — reCAPTCHA image grid (image.grid.recaptcha, family image, active). Variants: proxyless. Tasks not solved within 60 seconds fail with timeout.
CreateImageTextTaskRequest — Image to text (image.text, family image, active). Variants: proxyless. Tasks not solved within 60 seconds fail with timeout.
CreateRecaptchaV2TaskRequest — reCAPTCHA v2 (recaptcha.v2, family recaptcha, active). Variants: proxyless, proxy (the proxy variant when params.proxy is given). Tasks not solved within 120 seconds fail with timeout.
CreateRecaptchaV2EnterpriseTaskRequest — reCAPTCHA v2 Enterprise (recaptcha.v2.enterprise, family recaptcha, active). Variants: proxyless, proxy (the proxy variant when params.proxy is given). Tasks not solved within 120 seconds fail with timeout.
CreateRecaptchaV3TaskRequest — reCAPTCHA v3 (recaptcha.v3, family recaptcha, active). Variants: proxyless. Tasks not solved within 120 seconds fail with timeout.
CreateRecaptchaV3EnterpriseTaskRequest — reCAPTCHA v3 Enterprise (recaptcha.v3.enterprise, family recaptcha, active). Variants: proxyless. Tasks not solved within 120 seconds fail with timeout.
CreateTurnstileTaskRequest — Cloudflare Turnstile (turnstile, family cloudflare, active). Variants: proxyless, proxy (the proxy variant when params.proxy is given). Tasks not solved within 120 seconds fail with timeout.

CreateTurnstileTaskRequest

Task type page: /docs/task-types/turnstile/

object

Cloudflare Turnstile (turnstile, family cloudflare, active). Variants: proxyless, proxy (the proxy variant when params.proxy is given). Tasks not solved within 120 seconds fail with timeout.

Compatibility API names: TurnstileTask (proxy), TurnstileTaskProxyless (proxyless).

Field	Type	Description
`callback_url` optional	`CallbackUrl`	Where to POST the task's final result (a `task.solved` or `task.failed` event, see Webhooks). `http` or `https`, port 80, 443, 8080 or 8443, no user info or fragment, public hosts only. `null` or `""`: no callback.
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`TurnstileParams`
`type` required	`const "turnstile"`

EnterprisePayload

object · max 32 keys

Extra enterprise parameters passed to the widget as is, e.g. {"s": "..."} for reCAPTCHA Enterprise or {"rqdata": "..."} for hCaptcha.

FeedbackRequest

object

Field	Type	Description
`correct` required	`boolean`	Whether the answer was accepted by the target site.
`reason` optional	`string`	Optional free text; not stored.

FeedbackResult

object

Field	Type	Description
`accepted` required	`const true`
`id` required	`string`	pattern: ^[0-9]+$

FieldError

object

Field	Type	Description
`message` required	`string`
`pointer` required	`string`	JSON Pointer (RFC 6901) to the offending value, from the root of the request body: `/params/website_key`, `/params/proxy/port`, `/params` for the parameters object itself, `/metadata/order`, `/metadata` for the metadata object itself.
`reason` optional	`enum`	Machine-readable kind, present for image problems: `image_too_large` (over 1,000,000 characters, the pixel or frame limits, or the images of the task together over the per-task limit; the pointer is the image that went over), `image_empty`, `image_base64` (not valid base64), `image_format` (not a PNG, JPEG, GIF, WebP or BMP image, a multi-picture JPEG, or malformed or truncated). New values may be added. one of "image_too_large", "image_empty", "image_base64", "image_format"

FuncaptchaParams

Task type page: /docs/task-types/funcaptcha/

object

Field	Type	Description
`api_subdomain` optional	`Hostname`	Subdomain that serves the widget, e.g. client-api.arkoselabs.com.
`data` optional	`string`	Extra blob data as a JSON string, e.g. {"blob":"..."}. min length 1 · max length 16,384
`proxy` optional	`Proxy`	Proxy the solver must use. login and password are used in memory only and are never stored or logged.
`user_agent` optional	`UserAgent`	Browser User-Agent.
`website_public_key` required	`string`	The public key (data-pkey). min length 1 · max length 128
`website_url` required	`WebsiteUrl`	Full URL of the page that shows the captcha (http or https).

FuncaptchaSolution

Task type page: /docs/task-types/funcaptcha/

object

Field	Type	Description
`token` required	`Token`	Token to submit to the target site. Single use.

HcaptchaParams

Task type page: /docs/task-types/hcaptcha/

object

Field	Type	Description
`enterprise_payload` optional	`EnterprisePayload`	Extra enterprise parameters passed to the widget as is, e.g. {"s": "..."} for reCAPTCHA Enterprise or {"rqdata": "..."} for hCaptcha.
`is_invisible` optional	`boolean`	true for the invisible hCaptcha.
`proxy` optional	`Proxy`	Proxy the solver must use. login and password are used in memory only and are never stored or logged.
`user_agent` optional	`UserAgent`	Browser User-Agent.
`website_key` required	`WebsiteKey`	The site key of the captcha widget.
`website_url` required	`WebsiteUrl`	Full URL of the page that shows the captcha (http or https).

HcaptchaSolution

Task type page: /docs/task-types/hcaptcha/

object

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

Hostname

string · format: hostname · min length 1 · max length 253

Image

string · min length 1 · max length 1,000,000

Base64-encoded PNG, JPEG, GIF, WebP or BMP image (standard or URL-safe alphabet; a data:image/...;base64, prefix, line breaks and missing padding are accepted). At most 1,000,000 characters, 8192 pixels per side and 8,388,608 pixels in total; animated images at most 1000 frames and 8,388,608 pixels for frames x width x height; multi-picture JPEG (MPO), JPEG with more than 100 scans, malformed or truncated images are rejected.

ImageFuncaptchaParams

Task type page: /docs/task-types/image-funcaptcha/

object

Field	Type	Description
`images` required	`array of Image`	Base64 of each challenge image (at most 20). min items 1 · max items 20
`images.[item]` optional	`Image`	Base64-encoded PNG, JPEG, GIF, WebP or BMP image (standard or URL-safe alphabet; a data:image/...;base64, prefix, line breaks and missing padding are accepted). At most 1,000,000 characters, 8192 pixels per side and 8,388,608 pixels in total; animated images at most 1000 frames and 8,388,608 pixels for frames x width x height; multi-picture JPEG (MPO), JPEG with more than 100 scans, malformed or truncated images are rejected.
`question` required	`Question`	The question in English, e.g. Pick the image that is the correct way up.

ImageFuncaptchaSolution

Task type page: /docs/task-types/image-funcaptcha/

object

Field	Type	Description
`objects` required	`Indexes`	Zero-based indexes of the images or tiles to select, left to right, top to bottom.

ImageGridAwsParams

Task type page: /docs/task-types/image-grid-aws/

object

Field	Type	Description
`image` required	`Image`	Base64 of the whole 3x3 grid image.
`question` optional	`Question`	The full question as shown on the page, e.g. Select all hats.

ImageGridAwsSolution

Task type page: /docs/task-types/image-grid-aws/

object

Field	Type	Description
`confidences` optional	`Confidences`
`objects` required	`Indexes`	Zero-based indexes of the images or tiles to select, left to right, top to bottom.

ImageGridHcaptchaParams

Task type page: /docs/task-types/image-grid-hcaptcha/

object

Give at least one of question, anchors.

Field	Type	Description
`anchors` optional	`array of Image`	Base64 of the example images shown next to the question. min items 1 · max items 10
`anchors.[item]` optional	`Image`	Base64-encoded PNG, JPEG, GIF, WebP or BMP image (standard or URL-safe alphabet; a data:image/...;base64, prefix, line breaks and missing padding are accepted). At most 1,000,000 characters, 8192 pixels per side and 8,388,608 pixels in total; animated images at most 1000 frames and 8,388,608 pixels for frames x width x height; multi-picture JPEG (MPO), JPEG with more than 100 scans, malformed or truncated images are rejected.
`images` required	`array of Image`	Base64 of each challenge image in page order. min items 1 · max items 20
`images.[item]` optional	`Image`	Base64-encoded PNG, JPEG, GIF, WebP or BMP image (standard or URL-safe alphabet; a data:image/...;base64, prefix, line breaks and missing padding are accepted). At most 1,000,000 characters, 8192 pixels per side and 8,388,608 pixels in total; animated images at most 1000 frames and 8,388,608 pixels for frames x width x height; multi-picture JPEG (MPO), JPEG with more than 100 scans, malformed or truncated images are rejected.
`question` optional	`Question`	The full question as shown on the page.

ImageGridHcaptchaSolution

Task type page: /docs/task-types/image-grid-hcaptcha/

object

Field	Type	Description
`confidences` optional	`Confidences`
`objects` required	`Indexes`	Zero-based indexes of the images or tiles to select, left to right, top to bottom.

ImageGridRecaptchaParams

Task type page: /docs/task-types/image-grid-recaptcha/

object

Field	Type	Description
`confidence` optional	`number`	3x3 only: return every tile scoring above this threshold instead of the top 3. ≥ 0 · ≤ 1
`grid` optional	`enum`	Grid shape. Inferred from the image size when omitted. one of "1x1", "3x3", "4x4"
`image` required	`Image`	Base64 of the whole challenge image (3x3 or 4x4 grid) or of a single 1x1 tile.
`question` required	`Question`	Question ID such as /m/0k4j.

ImageGridRecaptchaSolution

Task type page: /docs/task-types/image-grid-recaptcha/

object

Give at least one of objects, has_object.

Field	Type	Description
`confidences` optional	`Confidences`
`has_object` optional	`boolean`	1x1 tile: whether the tile contains the target.
`objects` optional	`Indexes`	Zero-based indexes of the images or tiles to select, left to right, top to bottom.

ImageTextParams

Task type page: /docs/task-types/image-to-text/

object

Field	Type	Description
`case_sensitive` optional	`boolean`	The answer is case-sensitive.
`image` required	`Image`	Base64-encoded PNG, JPEG, GIF, WebP or BMP image (standard or URL-safe alphabet; a data:image/...;base64, prefix, line breaks and missing padding are accepted). At most 1,000,000 characters, 8192 pixels per side and 8,388,608 pixels in total; animated images at most 1000 frames and 8,388,608 pixels for frames x width x height; multi-picture JPEG (MPO), JPEG with more than 100 scans, malformed or truncated images are rejected.
`math` optional	`boolean`	The image is an arithmetic expression; the answer is its result.
`max_length` optional	`integer`	Maximum answer length; 0 means no limit. ≥ 0 · ≤ 100
`min_length` optional	`integer`	Minimum answer length; 0 means no limit. ≥ 0 · ≤ 100
`numeric` optional	`enum`	0 no requirement; 1 digits only; 2 no digits. one of 0, 1, 2
`phrase` optional	`boolean`	The answer contains at least one space.

ImageTextSolution

Task type page: /docs/task-types/image-to-text/

object

Field	Type	Description
`text` required	`string`	Recognized text. min length 1 · max length 1,024

Indexes

array of integer · max items 64 · unique items

Zero-based indexes of the images or tiles to select, left to right, top to bottom.

Me

object

Field	Type	Description
`budget` required	`one of \| null`	The key's spending budget; `null` when unlimited. one of: `object`
`key` required	`object`
`key.allow_cidrs` required	`array \| null`	Client IP ranges this key may be used from; `null` = any.
`key.allowed_types` required	`array \| null`	Task types this key may use; `null` = all.
`key.expires_at` required	`string \| null`	format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`key.id` required	`string`
`key.last4` required	`string`
`key.mode` required	`enum`	one of "live", "test"
`key.name` required	`string`
`key.prefix` required	`string`
`key.revoke_at` required	`string \| null`	When a rotated key stops working. format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`key.scopes` required	`array of string`
`limits` required	`object`
`limits.concurrency_by_family` required	`object`	Tasks in flight allowed for this organization, per captcha family (`recaptcha`, `hcaptcha`, …). Every public family is listed. Creating a task beyond the limit returns 429 `concurrency_limited`. Contact support to raise it.
`limits.concurrency_by_family.<any key>` optional	`integer`
`limits.concurrency_per_family` required	`integer`	Default number of tasks in flight per captcha family. Your organization may have a different limit for some families; `concurrency_by_family` has the limit that actually applies.
`limits.create_tasks` required	`one of \| null`	Tasks this key may create per window; `null` when disabled. one of: `RatePolicy`
`limits.sandbox` optional	`object`	Present for test keys.
`limits.sandbox.create_tasks_per_org` required	`one of \| null`	one of: `RatePolicy`
`limits.sandbox.in_flight_per_org` required	`integer`
`limits.sandbox.waits_per_org_per_process` required	`integer`
`limits.task_polls` required	`one of \| null`	Polls per task per window (including bursts); `null` when disabled. one of: `RatePolicy`
`limits.wait_max_seconds` required	`integer`	Longest synchronous wait.
`organization` required	`object`
`organization.id` required	`string`
`organization.name` required	`string`
`organization.status` required	`string`

Metadata

object · max 16 keys

Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is 422 invalid_params with pointer /metadata/<key>.

Field	Type	Description
`<any key>` optional	`string`	max length 256

Money

object

Field	Type	Description
`amount` required	`string`	Decimal US dollars with 6 places. pattern: ^-?[0-9]+\.[0-9]{6}$
`currency` required	`const "USD"`

Problem

object

An error, as RFC 9457 problem details (application/problem+json). Use code in programs; type is https://noptcha.com/docs/errors/<code>. New codes may be added.

code	HTTP	when
`invalid_request`	400	malformed body, missing field, bad parameter, `callback_url` not a string
`unsupported_type`	400	unknown or unavailable task type
`unauthorized`	401	invalid, revoked or expired key
`insufficient_balance`	402	balance too low for the task's price
`budget_exceeded`	402	the key's budget for the period is used up
`forbidden`	403	missing scope, IP not allowed, type not allowed, organization suspended
`not_found`	404	unknown endpoint or method; unknown, expired or foreign task; expired idempotent task
`idempotency_conflict`	409	same `Idempotency-Key` with another body, or still in progress
`task_not_solved`	409	feedback for a task that is still processing or failed
`request_too_large`	413	body over the limit
`invalid_params`	422	`params` or `metadata` do not match the schema, or `callback_url` is not allowed
`rate_limited`	429	over a rate limit, or IP blocked after invalid keys
`concurrency_limited`	429	too many tasks in flight
`internal`	500	our error
`service_unavailable`	503	no capacity or a dependency is down

Field	Type	Description
`code` required	`string`	Machine-readable error code (see the table).
`detail` optional	`string`	Human-readable explanation of this occurrence.
`request_id` required	`string`	Same as the `Noptcha-Request-Id` header.
`status` required	`integer`	The HTTP status code.
`title` required	`string`
`type` required	`string`	format: uri

Proxy

object

Proxy the solver must use. login and password are used in memory only and are never stored or logged.

Field	Type	Description
`host` required	`string`	IP address or host name. Private and loopback addresses are rejected. min length 1 · max length 253
`login` optional	`string`	max length 256
`password` optional	`string`	max length 256
`port` required	`integer`	≥ 1 · ≤ 65535
`type` required	`enum`	one of "http", "https", "socks4", "socks5"

Question

string · min length 1 · max length 1,024

RatePolicy

object

Field	Type	Description
`limit` required	`integer`
`window_seconds` required	`integer`

RecaptchaV2EnterpriseParams

Task type page: /docs/task-types/recaptcha-v2-enterprise/

object

Field	Type	Description
`api_domain` optional	`Hostname`	Domain the widget is loaded from, e.g. www.recaptcha.net. Omit for the default.
`cookies` optional	`string`	Cookies for the target site, as in a Cookie header: name1=value1; name2=value2. max length 8,192
`enterprise_payload` optional	`EnterprisePayload`	Extra enterprise parameters passed to the widget as is, e.g. {"s": "..."} for reCAPTCHA Enterprise or {"rqdata": "..."} for hCaptcha.
`is_invisible` optional	`boolean`	true for the invisible reCAPTCHA.
`proxy` optional	`Proxy`	Proxy the solver must use. login and password are used in memory only and are never stored or logged.
`user_agent` optional	`UserAgent`	Browser User-Agent.
`website_key` required	`WebsiteKey`	The site key of the captcha widget.
`website_url` required	`WebsiteUrl`	Full URL of the page that shows the captcha (http or https).

RecaptchaV2EnterpriseSolution

Task type page: /docs/task-types/recaptcha-v2-enterprise/

object

Field	Type	Description
`token` required	`Token`	Token to submit to the target site. Single use.
`user_agent` optional	`UserAgent`	User-Agent the token was obtained with; use it when submitting the token.

RecaptchaV2Params

Task type page: /docs/task-types/recaptcha-v2/

object

Field	Type	Description
`api_domain` optional	`Hostname`	Domain the widget is loaded from, e.g. www.recaptcha.net. Omit for the default.
`cookies` optional	`string`	Cookies for the target site, as in a Cookie header: name1=value1; name2=value2. max length 8,192
`is_invisible` optional	`boolean`	true for the invisible reCAPTCHA.
`proxy` optional	`Proxy`	Proxy the solver must use. login and password are used in memory only and are never stored or logged.
`user_agent` optional	`UserAgent`	Browser User-Agent.
`website_key` required	`WebsiteKey`	The site key of the captcha widget.
`website_url` required	`WebsiteUrl`	Full URL of the page that shows the captcha (http or https).

RecaptchaV2Solution

Task type page: /docs/task-types/recaptcha-v2/

object

Field	Type	Description
`token` required	`Token`	Token to submit to the target site. Single use.
`user_agent` optional	`UserAgent`	User-Agent the token was obtained with; use it when submitting the token.

RecaptchaV3EnterpriseParams

Task type page: /docs/task-types/recaptcha-v3-enterprise/

object

Field	Type	Description
`api_domain` optional	`Hostname`	Domain the widget is loaded from, e.g. www.recaptcha.net. Omit for the default.
`cookies` optional	`string`	Cookies for the target site, as in a Cookie header: name1=value1; name2=value2. max length 8,192
`enterprise_payload` optional	`EnterprisePayload`	Extra enterprise parameters passed to the widget as is, e.g. {"s": "..."} for reCAPTCHA Enterprise or {"rqdata": "..."} for hCaptcha.
`min_score` optional	`number`	Minimum score the token should reach (0.1 to 0.9). ≥ 0.1 · ≤ 0.9
`page_action` optional	`string`	The action passed to grecaptcha.execute. min length 1 · max length 256
`user_agent` optional	`UserAgent`	Browser User-Agent.
`website_key` required	`WebsiteKey`	The site key of the captcha widget.
`website_url` required	`WebsiteUrl`	Full URL of the page that shows the captcha (http or https).

RecaptchaV3EnterpriseSolution

Task type page: /docs/task-types/recaptcha-v3-enterprise/

object

Field	Type	Description
`token` required	`Token`	Token to submit to the target site. Single use.
`user_agent` optional	`UserAgent`	User-Agent the token was obtained with; use it when submitting the token.

RecaptchaV3Params

Task type page: /docs/task-types/recaptcha-v3/

object

Field	Type	Description
`api_domain` optional	`Hostname`	Domain the widget is loaded from, e.g. www.recaptcha.net. Omit for the default.
`cookies` optional	`string`	Cookies for the target site, as in a Cookie header: name1=value1; name2=value2. max length 8,192
`min_score` optional	`number`	Minimum score the token should reach (0.1 to 0.9). ≥ 0.1 · ≤ 0.9
`page_action` optional	`string`	The action passed to grecaptcha.execute. min length 1 · max length 256
`user_agent` optional	`UserAgent`	Browser User-Agent.
`website_key` required	`WebsiteKey`	The site key of the captcha widget.
`website_url` required	`WebsiteUrl`	Full URL of the page that shows the captcha (http or https).

RecaptchaV3Solution

Task type page: /docs/task-types/recaptcha-v3/

object

Field	Type	Description
`token` required	`Token`	Token to submit to the target site. Single use.
`user_agent` optional	`UserAgent`	User-Agent the token was obtained with; use it when submitting the token.

Solution

object

A task's answer. Its shape is the solution schema of the task's type (<Type>Solution, e.g. RecaptchaV2Solution for recaptcha.v2).

Any of:

Task

object

Field	Type	Description
`completed_at` optional	`string`	When the task became final; absent while processing. format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`cost` required	`Money`	What the task cost (zero unless solved and charged).
`created_at` required	`string`	format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`error` required	`one of \| null`	Why the task failed when `status` is `failed`, else `null`. one of: `TaskError`
`id` required	`string`	Task ID (a 53-bit integer as a string). pattern: ^[0-9]+$
`metadata` optional	`Metadata`	Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.
`params` required	`object \| null`	The task's parameters with secrets removed (proxy login and password, cookies where the type marks them sensitive) and strings longer than 256 bytes (images) replaced by `"[N bytes]"`. `null` when not available.
`sandbox` optional	`const true`	Present (true) on tasks created with a test key.
`solution` required	`one of \| null`	The answer when `status` is `solved`, else `null`. Its shape depends on `type`. one of: `Solution`
`status` required	`enum`	one of "processing", "solved", "failed"
`type` required	`string`	Canonical task type, e.g. `recaptcha.v2` (see `CreateTaskRequest`).

TaskError

object

code	meaning
`unsolvable`	the captcha could not be solved (also when no solver accepts these parameters)
`timeout`	not solved before the type's deadline
`proxy_error`	the proxy could not be used
`invalid_site`	the site key or domain is invalid
`invalid_image`	the image is empty, too big or unreadable
`cancelled`	the task was cancelled

New codes may be added.

Field	Type	Description
`code` required	`string`
`message` required	`string`

Token

string · min length 1

Token to submit to the target site. Single use.

TurnstileParams

Task type page: /docs/task-types/turnstile/

object

Field	Type	Description
`action` optional	`string`	The action option of the widget (data-action). min length 1 · max length 256
`cdata` optional	`string`	The cData option of the widget (data-cdata). min length 1 · max length 1,024
`page_data` optional	`string`	The chlPageData value of a challenge page widget. min length 1 · max length 8,192
`proxy` optional	`Proxy`	Proxy the solver must use. login and password are used in memory only and are never stored or logged.
`user_agent` optional	`UserAgent`	Browser User-Agent.
`website_key` required	`WebsiteKey`	The site key of the captcha widget.
`website_url` required	`WebsiteUrl`	Full URL of the page that shows the captcha (http or https).

TurnstileSolution

Task type page: /docs/task-types/turnstile/

object

Field	Type	Description
`token` required	`Token`	Token to submit to the target site. Single use.
`user_agent` optional	`UserAgent`	User-Agent the token was obtained with; use it when submitting the token.

TypeInfo

object

Field	Type	Description
`family` required	`string`	Captcha family (concurrency is limited per family), e.g. `recaptcha`, `hcaptcha`, `cloudflare`, `arkose`, `image`.
`name` required	`string`
`status` required	`string`	`active` or `beta`.
`timeout_seconds` required	`integer`	Deadline after which an unsolved task fails with `timeout`.
`type` required	`string`
`variants` required	`array of object`
`variants.[item]` optional	`object`
`variants.[item].price` required	`Money`
`variants.[item].variant` required	`string`	`proxyless` or `proxy` (the task has `params.proxy`).

TypeList

object

Field	Type	Description
`data` required	`array of TypeInfo`
`data.[item]` optional	`TypeInfo`
`price_version` required	`integer`	Version of the price list the prices come from.

Usage

object

Field	Type	Description
`currency` required	`const "USD"`
`data` required	`array of UsageRow`
`data.[item]` optional	`UsageRow`	One period and type (`group_by=type`) or key (`group_by=key`).
`from` required	`string`	Effective start (after rounding and the 90-day limit of `group_by=key`). format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`granularity` required	`enum`	one of "hour", "day"
`group_by` required	`enum`	one of "type", "key"
`object` required	`const "usage"`
`sandbox` required	`boolean`	True for test keys (always an empty report).
`to` required	`string`	Effective end (exclusive). format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`totals` required	`UsageCounts`

UsageCounts

object

Field	Type	Description
`amount` required	`Amount`	cash + promo.
`billed` required	`integer`	Tasks charged.
`cash` required	`Amount`	Decimal US dollars with 6 places.
`promo` required	`Amount`	Decimal US dollars with 6 places.
`unbilled` required	`integer`	Tasks not charged (unsolvable, timed out, cancelled).

UsageRow

object

One period and type (group_by=type) or key (group_by=key).

Field	Type	Description
`amount` required	`Amount`	cash + promo.
`billed` required	`integer`	Tasks charged.
`cash` required	`Amount`	Decimal US dollars with 6 places.
`promo` required	`Amount`	Decimal US dollars with 6 places.
`unbilled` required	`integer`	Tasks not charged (unsolvable, timed out, cancelled).
`end` required	`string`	format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`key` optional	`one of \| null`	With `group_by=key`. `null` is the unattributed remainder (the difference between the ledger and the per-key task log; usually zero, briefly non-zero while events are being processed). one of: `object`
`start` required	`string`	format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`type` optional	`string`	With `group_by=type`.
`variant` optional	`string`	With `group_by=type`.

UserAgent

string · min length 1 · max length 1,024

Browser User-Agent.

ValidationProblem

object

invalid_params, with one entry per problem (at most 50, sorted by pointer).

Field	Type	Description
`code` required	`string`	Machine-readable error code (see the table).
`detail` optional	`string`	Human-readable explanation of this occurrence.
`request_id` required	`string`	Same as the `Noptcha-Request-Id` header.
`status` required	`integer`	The HTTP status code.
`title` required	`string`
`type` required	`string`	format: uri
`errors` required	`array of FieldError`	One entry per problem, sorted by `pointer`. At most 50 entries; when there are more, `detail` ends with "and N more errors". max items 50
`errors.[item]` optional	`FieldError`

WebhookBalanceLowEvent

object

Field	Type	Description
`data` required	`object`
`data.balance` required	`Amount`	Cash + promotional credit when the balance was checked.
`data.currency` required	`const "USD"`
`data.threshold` required	`Amount`	The alert threshold set in the console.
`timestamp` required	`string`	When the balance was checked (just after a charge). format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`type` required	`const "balance.low"`

WebhookKeyExpiringEvent

object

Field	Type	Description
`data` required	`object`
`data.expires_at` required	`string`	format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`data.id` required	`string`	API key ID (as in the console). pattern: ^[0-9]+$
`data.last4` required	`string`
`data.mode` required	`enum`	one of "live", "test"
`data.name` required	`string`
`data.prefix` required	`string`	The first characters of the key, as shown in the console.
`timestamp` required	`string`	When the upcoming expiry was noticed. format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`type` required	`const "key.expiring"`

WebhookPaymentDisputedEvent

object

Field	Type	Description
`data` required	`object`
`data.amount` required	`Amount`	Amount in dispute.
`data.currency` required	`const "USD"`
`data.id` required	`string`	Dispute ID. pattern: ^[0-9]+$
`data.opened_at` required	`string`	format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`data.payment_id` required	`string`	The disputed payment (top-up), `tp_…`.
`timestamp` required	`string`	When the dispute was opened. format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`type` required	`const "payment.disputed"`

WebhookPaymentRefundedEvent

object

Field	Type	Description
`data` required	`object`
`data.amount` required	`Amount`	Amount refunded.
`data.currency` required	`const "USD"`
`data.id` required	`string`	Refund ID. pattern: ^[0-9]+$
`data.payment_id` required	`string`	The refunded payment (top-up), `tp_…`.
`data.refunded_at` required	`string`	When the refund first succeeded (does not change afterwards). format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`timestamp` required	`string`	When the refund succeeded. format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`type` required	`const "payment.refunded"`

WebhookPaymentSucceededEvent

object

Field	Type	Description
`data` required	`object`
`data.amount` required	`Amount`	Amount added to the balance.
`data.created_at` required	`string`	format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`data.credited_at` required	`string`	format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`data.currency` required	`const "USD"`
`data.id` required	`string`	The payment (top-up) ID shown in the console, `tp_…`.
`timestamp` required	`string`	When the top-up was credited. format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`type` required	`const "payment.succeeded"`

WebhookTaskEvent

object

A task event (task.solved or task.failed), Standard Webhooks' recommended envelope.

Field	Type	Description
`data` required	`Task`
`timestamp` required	`string`	When the task became final. format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`type` required	`enum`	one of "task.solved", "task.failed"

WebhookTestEvent

object

Field	Type	Description
`data` required	`object`
`data.endpoint_id` required	`string`
`data.message` required	`string`
`timestamp` required	`string`	format: date-time · pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
`type` required	`const "webhook.test"`

WebsiteKey

string · min length 1 · max length 512

The site key of the captcha widget.

WebsiteUrl

string · format: uri · pattern: ^[Hh][Tt][Tt][Pp][Ss]?:// · min length 8 · max length 4,096

Full URL of the page that shows the captcha (http or https).