Skip to content
clearance.rest

Solve a captcha

POST
/captchas/resolve
curl --request POST \
  --url https://api.clearance.rest/captchas/resolve \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "type": "recaptcha_v2", "website_url": "example", "website_key": "example", "proxy": "example", "user_agent": "example", "cookies": "example", "invisible": true, "enterprise": true, "enterprise_payload": { "additionalProperty": "example" }, "data_s": "example", "page_action": "example", "api_domain": "example" }'

Solves a captcha and waits for the result. The body is type plus the fields of that type (see GET /captchas/types); unknown fields are rejected. Only a solved captcha is charged; the amount is held up front. Add mode: 'browser' (hcaptcha) to solve in a real browser; it fails with 503 provider_unavailable when no browser worker is connected.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
X-Service-Timeout
integer
>= 1

Maximum time to wait in milliseconds (positive integer). Without it the request waits at most 10 minutes. When the time is up the response has status ‘timeout’.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
One of: discriminator: type

Request of type recaptcha_v2: Google reCAPTCHA v2 (checkbox, invisible and enterprise).

object
type
required

Captcha type.

string
Allowed value: recaptcha_v2
website_url
required

URL of the page that shows the captcha.

string
>= 1 characters
website_key
required

Site key of the captcha widget.

string
>= 1 characters
proxy

Proxy to solve through: scheme://[user:pass@]host:port (http, https, socks4 or socks5). Without a proxy the captcha is solved from the solver’s own network.

string
>= 1 characters
user_agent

User agent of the browser that will submit the solution.

string
>= 1 characters
cookies

Cookies of the page as ‘name=value; name2=value2’.

string
>= 1 characters
invisible

True for invisible reCAPTCHA.

boolean
enterprise

True for the enterprise edition of the captcha.

boolean
enterprise_payload

Extra enterprise parameters of the widget (for example the ‘s’ value). Requires enterprise: true.

object
key
additional properties
data_s

Value of the data-s attribute of the widget.

string
>= 1 characters
page_action

Action name passed to the reCAPTCHA execute call.

string
>= 1 characters
api_domain

Domain the reCAPTCHA script is loaded from (google.com or recaptcha.net).

string
>= 1 characters

Responses

Section titled “Responses”

200

Section titled “200”

Default Response

Media typeapplication/json
One of: discriminator: type

Result of a request of type recaptcha_v2; solution is a TokenSolution.

object
success
required
boolean
job_id
required

Job id.

string
type
required

Captcha type of the request; solution has the shape of this type.

string
Allowed value: recaptcha_v2
mode
required
Any of:

Set to ‘browser’ to solve in a real browser. The request fails with 503 provider_unavailable when no browser worker is connected.

string
Allowed values: browser
status
required

Solved: a solution is attached. failed: the captcha could not be solved (nothing is charged). timeout: no solution within the time limit (nothing is charged).

string
Allowed values: solved failed timeout
solution

Token solution (reCAPTCHA, Turnstile, MTCaptcha, FunCaptcha).

object
token
required
string
user_agent
string
key
additional properties
error

Present when status is failed.

object
code
required

Failure code (snake_case).

string
message
required

Human-readable reason.

string
waited_ms
required

Milliseconds spent on the request.

number
price
required

Amount charged for this request in USD (0 unless the captcha was solved).

number
balance
required

Available team balance after the request in USD.

number
Example
{
  "success": true,
  "type": "recaptcha_v2",
  "mode": "browser",
  "status": "solved"
}

400

Section titled “400”

Default Response

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
Allowed values: validation_error invalid_service_timeout unsupported_request
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false,
  "error": {
    "code": "validation_error"
  }
}

401

Section titled “401”

Default Response

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
Allowed values: missing_api_key invalid_api_key
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false,
  "error": {
    "code": "missing_api_key"
  }
}

402

Section titled “402”

Default Response

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
Allowed values: insufficient_balance spend_limit_exceeded
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false,
  "error": {
    "code": "insufficient_balance"
  }
}

403

Section titled “403”

Default Response

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
Allowed values: team_suspended email_not_verified invalid_mcp_token
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false,
  "error": {
    "code": "team_suspended"
  }
}

500

Section titled “500”

Default Response

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
Allowed values: internal_error price_unavailable
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false,
  "error": {
    "code": "internal_error"
  }
}

503

Section titled “503”

Default Response

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
Allowed values: provider_unavailable
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false,
  "error": {
    "code": "provider_unavailable"
  }
}