PRODUCT TEST WORKSPACE

Cloudflare Turnstile

Captcha verification product

CLOUDFLARE_TURNSTILE

02 / REQUEST

Request preview

POST /api/validator/create.cgi

{
  "productCode" : "CLOUDFLARE_TURNSTILE",
  "adapter" : {
    "websiteURL" : "https://example.com/register",
    "websiteKey" : "YOUR_WEBSITEKEY"
  }
}

03 / RESULT

Response example

EXAMPLE

Task ID —

{
  "code" : 0,
  "msg" : "Success",
  "data" : {
    "taskId" : "11111111-1111-4111-8111-111111111111",
    "productCode" : "CLOUDFLARE_TURNSTILE",
    "state" : "SUCCEEDED",
    "solution" : {
      "token" : "EXAMPLE_TOKEN",
      "userAgent" : "EXAMPLE_USERAGENT"
    }
  }
}

Illustrative response; not a live task result. Replace all request placeholders before submitting.

Read data.solution after state becomes SUCCEEDED. The solution fields depend on the product; other states may return an empty object.

04 / API REFERENCE

Cloudflare Turnstile · API

For task creation and queries, send the API key in the apiKey HTTP header. JSON request bodies contain business parameters only.

Content-Type: application/json
apiKey: YOUR_API_KEY

Result and application

TOKEN

Use solution.token through the original widget response field or callback and honor solution.userAgent for challenge pages. Tokens are single-use and valid for 300 seconds after generation; the target must validate them. SUCCEEDED does not verify target acceptance or produce a generic cf_clearance cookie.

Conditional workflows

HTTP submission HTTP_SUBMIT
Apply a result in the browser BROWSER_RESULT

Requirements

Prefer the product-specific (native) CAPTCHA integration over generic GRID. Identify the actual product/version and read its schema/guide before choosing. Use HTTP_SUBMIT when the target supports it, otherwise BROWSER_RESULT when the browser can apply the native result. Image grids on screen do not by themselves mean the product is GRID. Collect real inputs; missing inputs are a blocker, not permission to guess.
Apply a native result through the matching target integration: fill the expected token response field/callback, or use the returned challenge identifier and proof/answer fields together where that product requires them. Preserve the target session and bindings. Do not mix old and new challenge fields, replace only a picture, or assume the solver issues an unrelated transferable challenge/answer pair.
First distinguish a standalone widget from a Cloudflare challenge page. URL and sitekey remain sufficient inputs for a basic standalone widget. Challenge pages additionally require their current action, cData (data) and chlPageData (pagedata), not guessed values. action/data alone do not establish challenge-page mode. Optional proxy fields select TurnstileTask; omitting them retains TurnstileTaskProxyless.
PROVIDER_UNAVAILABLE means an upstream transport/availability problem, not proof of an unsolvable CAPTCHA. A short create cooldown may reject new requests without contacting the upstream after HTTP 429/502/503/504. A request with unknown upstream receipt is never automatically recreated. Inspect the failure before starting another paid task; do not switch to GRID or reuse expired challenge materials.
Collect fresh values from the same target/challenge. Respect product-specific hostname, action, challenge/session, IP, User-Agent and expiry requirements; these are not universally interchangeable. Apply returned cookies only to their matching domains.
Examples are placeholders, not runnable challenges. Documented result fields are not proof of target acceptance or a live availability test. Do not send unsupported fields.
SUCCEEDED means a solver result is available. Separately confirm that the target accepts the challenge and that the requested business operation completes. The solver cannot observe those two outcomes.

Input sources

Field	Input sources
`websiteURL`	Full URL of the page hosting this widget, from the same target session.
`websiteKey`	Actual sitekey of this Turnstile widget. Do not use a key from another site.
`action`	Actual render action. Required with challenge-page pagedata; standalone widgets may also set action without pagedata.
`data`	Actual render cData, sent upstream as data. cData is accepted as an alias; conflicting values are rejected before billing.
`pagedata`	Fresh render chlPageData for a Cloudflare challenge page, sent upstream as pagedata. When supplied, action and data must also be present. Not universally required for standalone widgets.
`cData`	Compatibility alias of data. Prefer data; omit the alias when data is supplied.
`chlPageData`	Compatibility alias of pagedata. Prefer pagedata; omit the alias when pagedata is supplied.
`userAgent`	Actual browser User-Agent, when available. Preserve the returned solution.userAgent; do not assume the upstream will return the supplied value.
`proxyType`	Optional proxy protocol: http, socks4 or socks5. Supplying any proxy field requires proxyType, proxyAddress and proxyPort together. Omit all proxy fields to retain proxyless mode.
`proxyAddress`	Proxy host or IP without scheme, port or credentials. Use the appropriate target-session egress.
`proxyPort`	Proxy TCP port: integer from 1 to 65535. Required only when using a proxy.
`proxyLogin`	Proxy username only if this proxy requires authentication.
`proxyPassword`	Proxy password only if this proxy requires authentication.

Request example

POST /api/validator/create.cgi · JSONC

{
"productCode": "CLOUDFLARE_TURNSTILE", // Product code matching the adapter parameters.
"adapter": { // Product-specific parameter object.
"websiteURL": "https://example.com/register", // Full URL of the page hosting this widget, from the same target session.
"websiteKey": "YOUR_WEBSITEKEY", // Actual sitekey of this Turnstile widget. Do not use a key from another site.
"action": "YOUR_ACTION", // Actual render action. Required with challenge-page pagedata; standalone widgets may also set action without pagedata.
"data": "CURRENT_CDATA", // Actual render cData, sent upstream as data. cData is accepted as an alias; conflicting values are rejected before billing.
"pagedata": "CURRENT_CHL_PAGE_DATA", // Fresh render chlPageData for a Cloudflare challenge page, sent upstream as pagedata. When supplied, action and data must also be present. Not universally required for standalone widgets.
"cData": "CURRENT_CDATA", // Compatibility alias of data. Prefer data; omit the alias when data is supplied.
"chlPageData": "CURRENT_CHL_PAGE_DATA", // Compatibility alias of pagedata. Prefer pagedata; omit the alias when pagedata is supplied.
"userAgent": "YOUR_BROWSER_USER_AGENT", // Actual browser User-Agent, when available. Preserve the returned solution.userAgent; do not assume the upstream will return the supplied value.
"proxyType": "http", // Optional proxy protocol: http, socks4 or socks5. Supplying any proxy field requires proxyType, proxyAddress and proxyPort together. Omit all proxy fields to retain proxyless mode.
"proxyAddress": "YOUR_PROXY_HOST", // Proxy host or IP without scheme, port or credentials. Use the appropriate target-session egress.
"proxyPort": 8080, // Proxy TCP port: integer from 1 to 65535. Required only when using a proxy.
"proxyLogin": "YOUR_PROXYLOGIN", // Proxy username only if this proxy requires authentication.
"proxyPassword": "YOUR_PROXYPASSWORD" // Proxy password only if this proxy requires authentication.
}
}

Request headers: apiKey: YOUR_API_KEY

Comments explain the fields. Copy produces valid JSON without comments.

Response example

POST /api/validator/query.cgi · JSONC

{
  "code": 0, // Business result code: 0 means success; other values indicate an error.
  "msg": "Success", // Result message; may be empty on success.
  "data": { // Response data; may be null on an error.
    "taskId": "11111111-1111-4111-8111-111111111111", // Task ID returned by task creation.
    "productCode": "CLOUDFLARE_TURNSTILE", // Product code matching the adapter parameters.
    "state": "SUCCEEDED", // Task state: CREATED, SUBMITTING, PROCESSING, SUCCEEDED, FAILED or EXPIRED.
    "solution": { // Product answer when SUCCEEDED; empty while processing or on failure.
      "token": "EXAMPLE_TOKEN", // Verification token to submit to the target website.
      "userAgent": "EXAMPLE_USERAGENT" // Browser User-Agent used to obtain the answer.
    }
  }
}

Creating a task returns its ID and initial state. Query the result or use WebSocket to receive the completed answer shown below.

Request parameters

Field	Type	Required	Description
`productCode`	string	Yes	Product code matching the adapter parameters.
`adapter`	object	Yes	Product-specific parameter object.
`adapter.websiteURL`	string	Yes	Full URL of the page hosting this widget, from the same target session.
`adapter.websiteKey`	string	Yes	Actual sitekey of this Turnstile widget. Do not use a key from another site.
`adapter.action`	string	No	Actual render action. Required with challenge-page pagedata; standalone widgets may also set action without pagedata.
`adapter.data`	string	No	Actual render cData, sent upstream as data. cData is accepted as an alias; conflicting values are rejected before billing.
`adapter.pagedata`	string	No	Fresh render chlPageData for a Cloudflare challenge page, sent upstream as pagedata. When supplied, action and data must also be present. Not universally required for standalone widgets.
`adapter.cData`	string	No	Compatibility alias of data. Prefer data; omit the alias when data is supplied.
`adapter.chlPageData`	string	No	Compatibility alias of pagedata. Prefer pagedata; omit the alias when pagedata is supplied.
`adapter.userAgent`	string	No	Actual browser User-Agent, when available. Preserve the returned solution.userAgent; do not assume the upstream will return the supplied value.
`adapter.proxyType`	string	No	Optional proxy protocol: http, socks4 or socks5. Supplying any proxy field requires proxyType, proxyAddress and proxyPort together. Omit all proxy fields to retain proxyless mode.
`adapter.proxyAddress`	string	No	Proxy host or IP without scheme, port or credentials. Use the appropriate target-session egress.
`adapter.proxyPort`	integer	No	Proxy TCP port: integer from 1 to 65535. Required only when using a proxy.
`adapter.proxyLogin`	string	No	Proxy username only if this proxy requires authentication.
`adapter.proxyPassword`	string	No	Proxy password only if this proxy requires authentication.

Response parameters

Field	Type	Description
`code`	integer	Business result code: 0 means success; other values indicate an error.
`msg`	string	Result message; may be empty on success.
`data`	object \| null	Response data; may be null on an error.
`data.taskId`	string	Task ID returned by task creation.
`data.productCode`	string	Product code matching the adapter parameters.
`data.state`	string	Task state: CREATED, SUBMITTING, PROCESSING, SUCCEEDED, FAILED or EXPIRED.
`data.solution`	object	Product answer when SUCCEEDED; empty while processing or on failure.
`data.failure`	object \| omitted	Public diagnosis for FAILED/EXPIRED only; no raw provider messages. Follow the failure handling guide.
`data.failure.code`	string	Failure code
`data.failure.nextAction`	string	Next action
`data.solution.token`	string	Verification token to submit to the target website.
`data.solution.userAgent`	string	Browser User-Agent used to obtain the answer.

Responses

HTTP business responses contain code, msg and data; code 0 means success. WebSocket uses a separate message structure.

-1317: Invalid API key.
-1100 / -1101: Invalid or missing request parameters.
-1401: Insufficient balance. Add funds before creating a task.
-1400 / -1001: System or task creation error.

API documentation

Cloudflare Turnstile

Create task

Request preview

Response example

Cloudflare Turnstile · API

Request example

Response example

Request parameters

Response parameters

Responses