Cloudflare Turnstile API Reference

Solve Cloudflare Turnstile widgets and submit the token as cf-turnstile-response.

The Captcha.fun Cloudflare Turnstile API accepts kind, url, siteKey and returns cf-turnstile-response token. Send the API_KEY header, create a solve with POST /v1/request, then poll GET /v2/response/{id} until ready is true.

What you’ll need

Your API key
The URL of the page where the challenge appears
The site key from the page
Optional: action, turnstileMetadata
A proxy, if the result must come from your own IP (turnstile_proxy)

Use kind

Good to Know

Supports managed, non-interactive, and invisible widgets. Pass the widget's action and cData values when set. After siteverify succeeds, your server must compare the returned action and cdata with its expected values before accepting the request.

Send the Challenge

Create Solve · POST /v1/request

Send the page details with your API key. You get a solve id back right away.

POSThttps://api.captcha.fun/v1/request

curl -X POST https://api.captcha.fun/v1/request \
  -H "API_KEY: CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "kind": "turnstile",
  "url": "https://your-domain.example/login",
  "siteKey": "YOUR_TURNSTILE_SITE_KEY",
  "action": "login"
}'

import requests

response = requests.post(
    "https://api.captcha.fun/v1/request",
    headers={
        "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={"kind": "turnstile", "url": "https://your-domain.example/login", "siteKey": "YOUR_TURNSTILE_SITE_KEY", "action": "login"},
)

print(response.status_code, response.json())

const response = await fetch("https://api.captcha.fun/v1/request", {
  method: "POST",
  headers: {
    "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
  "kind": "turnstile",
  "url": "https://your-domain.example/login",
  "siteKey": "YOUR_TURNSTILE_SITE_KEY",
  "action": "login"
})
});

console.log(response.status, await response.json());

Response

Returns the solve id. Use it to get the result.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Started Solving"
}

{
  "message": "invalid kind"
}

Request fields7 body fields · 3 required

Headers

Name	Type	Required	Description
API_KEY	string	Yes	Your API key
Content-Type	string	Yes	`application/json`
APP_ID	string	No	Optional app ID for request tracking

Body

Name	Type	Required	Description
kind	string	Yes	One of `turnstile`, `turnstile_proxy`
url	string	Yes	Page URL where the challenge appears
siteKey	string	Yes	Site key of the challenge
action	string	No	Widget `action`, if set. Your server must compare the `action` returned by `siteverify` with the expected value
turnstileMetadata	object	No	Widget metadata, e.g. `{ "cData": "..." }`. Passed to the widget as-is
proxy	string	No	For `_proxy` kinds: `host:port` or `host:port:username:password`
platform	string	No	Requested platform label: `windows` (default) or `mac`

Wait for the Result

Get Solve · GET /v2/response/{id}

Use the solve id to fetch the result.

GEThttps://api.captcha.fun/v2/response/{id}

Poll every second until ready is true.

GEThttps://api.captcha.fun/v1/response/{id}

Long polling: the request stays open until the solve finishes or times out. Send it once and wait.

Example

curl -X GET https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000 \
  -H "API_KEY: CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000",
    headers={
        "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "Accept": "application/json"
    }
)

print(response.status_code, response.json())

const response = await fetch(
  "https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000",
  {
    method: "GET",
    headers: {
      "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "Accept": "application/json"
    }
  }
);

const data = await response.json();
console.log(response.status, data);

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000", nil)
    req.Header.Set("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
    req.Header.Set("Accept", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(resp.StatusCode, result)
}

import java.net.http.*;
import java.net.URI;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000"))
            .header("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
            .header("Accept", "application/json")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
client.DefaultRequestHeaders.Add("Accept", "application/json");

var response = await client.GetAsync("https://api.captcha.fun/v2/response/550e8400-e29b-41d4-a716-446655440000");
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine($"{(int)response.StatusCode} {result}");

Response

{
  "ready": true,
  "status": "SUCCESS",
  "success": true,
  "userAgent": "RETURNED_USER_AGENT",
  "secUa": "RETURNED_SEC_CH_UA",
  "token": "0.ABCdEFGhIJKlMNoPQrSTUvWxYz0123456..."
}

{
  "message": "API_KEY Header Missing"
}

Example

curl -X GET https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000 \
  -H "API_KEY: CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000",
    headers={
        "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "Accept": "application/json"
    }
)

print(response.status_code, response.json())

const response = await fetch(
  "https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000",
  {
    method: "GET",
    headers: {
      "API_KEY": "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "Accept": "application/json"
    }
  }
);

const data = await response.json();
console.log(response.status, data);

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000", nil)
    req.Header.Set("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
    req.Header.Set("Accept", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(resp.StatusCode, result)
}

import java.net.http.*;
import java.net.URI;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000"))
            .header("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
            .header("Accept", "application/json")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("API_KEY", "CAPFUN-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
client.DefaultRequestHeaders.Add("Accept", "application/json");

var response = await client.GetAsync("https://api.captcha.fun/v1/response/550e8400-e29b-41d4-a716-446655440000");
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine($"{(int)response.StatusCode} {result}");

Response

{
  "status": "SUCCESS",
  "success": true,
  "userAgent": "RETURNED_USER_AGENT",
  "secUa": "RETURNED_SEC_CH_UA",
  "token": "0.ABCdEFGhIJKlMNoPQrSTUvWxYz0123456..."
}

{
  "message": "API_KEY Header Missing"
}

Request and response fields7 response fields

Request

Name	Type	Required	Description
id	string (UUID)	Yes	Path parameter. The `id` from Create Solve
API_KEY	string	Yes	Header. Your API key

Response Fields

Name	Type	Required	Description
ready	boolean	—	`true` when the solve is finished (v2 only)
status	string	—	`PENDING` while solving, then `SUCCESS` or `FAILURE`
success	boolean	—	Whether the solve succeeded
userAgent	string	—	Value to send as `User-Agent` when using the result. Preserve it exactly
secUa	string	—	Value to send as `Sec-CH-UA` when using the result
token	string	—	Solved token. Submit it as `cf-turnstile-response`
message	string	—	Failure reason. Omitted on success

Submit the Token

cf-turnstile-response token

Submit the token as cf-turnstile-response and verify it with Cloudflare's siteverify endpoint and your secret key. Require a successful response and compare the returned action and cdata with your expected values when set.
Tokens are single-use and short-lived. Submit right away.

When using a successful result, preserve the returned userAgent as User-Agent and secUa as Sec-CH-UA.

Wrong or rejected result? Report the failed solve.

What you’ll need

Good to Know

Send the Challenge

Response

Headers

Body

Wait for the Result

Example

Response

Example

Response

Request

Response Fields

Submit the Token

More from Cloudflare