PerimeterX API Reference

Solve PerimeterX (HUMAN) block pages and replay the _px cookies.

The Captcha.fun PerimeterX API accepts kind, url, challengeHtml and returns _px* clearance cookie. 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
challengeHtml — Captured block-page HTML that loads the PX sensor (init.js)
A proxy, if the result must come from your own IP (perimeterx_proxy)

Use kind

Good to Know

Send the captured block-page HTML (the page that loads the PX sensor, init.js). Returns the _px cookie family.

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": "perimeterx",
  "url": "https://your-domain.example",
  "challengeHtml": "<CAPTURED_PERIMETERX_BLOCK_PAGE_HTML>"
}'

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": "perimeterx", "url": "https://your-domain.example", "challengeHtml": "<CAPTURED_PERIMETERX_BLOCK_PAGE_HTML>"},
)

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": "perimeterx",
  "url": "https://your-domain.example",
  "challengeHtml": "<CAPTURED_PERIMETERX_BLOCK_PAGE_HTML>"
})
});

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 fields5 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 `perimeterx`, `perimeterx_proxy`
url	string	Yes	Page URL where the challenge appears
challengeHtml	string	Yes	Captured block-page HTML that loads the PX sensor (`init.js`)
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": "d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8...",
  "cookies": {
    "_px3": "d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8...",
    "_pxhd": "pxhd-sibling..."
  },
  "cookieHeader": "_px3=d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8...; _pxhd=pxhd-sibling..."
}

{
  "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": "d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8...",
  "cookies": {
    "_px3": "d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8...",
    "_pxhd": "pxhd-sibling..."
  },
  "cookieHeader": "_px3=d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8...; _pxhd=pxhd-sibling..."
}

{
  "message": "API_KEY Header Missing"
}

Request and response fields9 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	—	The _px3 clearance cookie value minted by solving the challenge
cookies	object	—	The defense cookie family, cookie name to value
cookieHeader	string	—	The solving session's full Cookie header value, verbatim — replay it with the returned userAgent from the same egress IP
message	string	—	Failure reason. Omitted on success

Send the Cookies

_px* clearance cookie

Replay cookieHeader as the Cookie header on outbound requests to the protected origin, with the returned userAgent as your User-Agent header, from the same egress IP as the solve.

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

Send the Cookies

More from PerimeterX