Authentication

All requests require an X-API-Key header.

X-API-Key: your-api-key

Relay Request

Sends an HTTP request through a proxy with the correct mobile TLS fingerprint. The TLS fingerprint is automatically selected based on the target URL's hostname. Sessions are managed automatically — a persistent TLS connection is created on the first request and reused for subsequent requests with the same hostname + proxy combination. Sessions are automatically destroyed after 1 minute of inactivity.

Request Body

Response Body

Success Response (200)

json{
  "status": 200,
  "headers": {
    "content-type": "application/json",
    "server": "nginx"
  },
  "body": "{\"data\": \"response from target\"}"
}

Error Responses

Examples

Node.js

javascriptconst TLS_URL = "https://ctls.botpulse.io";
const API_KEY = "your-api-key";
const PROXY = "protocol://[user:pass@]host:port";

// GET request
const response = await fetch(`${TLS_URL}/relay`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    proxy: PROXY,
    method: "GET",
    url: "https://api.footlocker.com/v4/search",
    headers: {
      "User-Agent": "Footlocker/9.3.3 okhttp/4.12.0 Android/16",
      "Accept": "application/json",
    },
  }),
});

const { status, headers, body } = await response.json();
console.log(`Target responded with ${status}`);

// POST request (same session is reused automatically)
const response2 = await fetch(`${TLS_URL}/relay`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    proxy: PROXY,
    method: "POST",
    url: "https://api.footlocker.com/v4/cart",
    headers: {
      "User-Agent": "Footlocker/9.3.3 okhttp/4.12.0 Android/16",
      "Content-Type": "application/json",
      "Accept": "application/json",
    },
    body: JSON.stringify({ sku: "12345", size: "10" }),
  }),
});

Go

gopackage main

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

func main() {
    tlsURL := "https://ctls.botpulse.io"
    apiKey := "your-api-key"
    proxy := "protocol://[user:pass@]host:port"

    payload, _ := json.Marshal(map[string]interface{}{
        "proxy":  proxy,
        "method": "GET",
        "url":    "https://api.footlocker.com/v4/search",
        "headers": map[string]string{
            "User-Agent": "Footlocker/9.3.3 okhttp/4.12.0 Android/16",
            "Accept":     "application/json",
        },
    })

    req, _ := http.NewRequest("POST", tlsURL+"/relay", bytes.NewReader(payload))
    req.Header.Set("X-API-Key", apiKey)
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var result struct {
        Status  int               `json:"status"`
        Headers map[string]string `json:"headers"`
        Body    string            `json:"body"`
    }
    json.NewDecoder(resp.Body).Decode(&result)

    fmt.Printf("Target responded with %d\n", result.Status)
}

Notes

• Automatic sessions. You don't need to manage sessions. The service automatically creates a persistent TLS connection on the first request for a given hostname + proxy combination and reuses it for subsequent requests. Sessions are destroyed after 1 minute of inactivity.
• TLS fingerprinting. The correct mobile app TLS fingerprint is automatically selected based on the target URL's hostname. You don't need to configure anything.
• Header ordering. Headers you pass in the headers field will be sent in the wire order configured for the target domain, not alphabetically. Just pass the headers you need.
• Proxy ports. Our infrastructure has firewall rules for standard proxy provider ports (Bright Data, etc.). If you use a proxy with a non-standard port, please let us know in advance so we can whitelist it.

Authentication

All requests (except GET /ping) require an API key via the X-API-Key header:

X-API-Key: your-api-key

Requests without a valid key receive a 401 Unauthorized response.

Solve Challenge

Request

Send a JSON body with the target URL and proxy:

bashcurl -X POST https://api.botpulse.io/f \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"input": {"url": "https://example.com/search?q=test", "proxy": "http://user:pass@proxy.example.com:8080"}}'

json{
  "input": {
    "url": "https://example.com/search?q=test",
    "proxy": "http://user:pass@proxy.example.com:8080"
  }
}

Fields

Response

Success (HTTP 200)

json{
  "status": "succeeded",
  "result": {
    "cookies": [
      "_fs_ch_session=abc123",
      "_fs_ch_exp=1760394626"
    ]
  }
}

Failure (HTTP 400)

json{
  "status": "failed",
  "error": "Could not find Fastly script ID in initial page"
}

Unauthorized (HTTP 401)

json{
  "status": "failed",
  "error": "Unauthorized"
}

Returned when the X-API-Key header is missing or invalid.

Using the cookies

Attach the returned cookies to subsequent requests to the target site using the Cookie header:

Cookie: _fs_ch_session=abc123; _fs_ch_exp=1760394626

cURL

bash# Step 1: Solve the challenge
RESPONSE=$(curl -s -X POST https://api.botpulse.io/f \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"input": {"url": "https://example.com/search?q=test", "proxy": "http://user:pass@proxy.example.com:8080"}}')

# Step 2: Extract cookies (requires jq)
COOKIES=$(echo "$RESPONSE" | jq -r '.result.cookies | join("; ")')

# Step 3: Make a request with the cookies
curl -s "https://example.com/search?q=test" \
  -H "Cookie: $COOKIES"

Python

pythonimport requests

# Step 1: Solve the challenge
response = requests.post(
    "https://api.botpulse.io/f",
    headers={"X-API-Key": "your-api-key"},
    json={
        "input": {
            "url": "https://example.com/search?q=test",
            "proxy": "http://user:pass@proxy.example.com:8080",
        }
    },
)
data = response.json()

# Step 2: Use the cookies
cookies = {}
for cookie in data["result"]["cookies"]:
    name, value = cookie.split("=", 1)
    cookies[name] = value

# Step 3: Make a request with the cookies
page = requests.get("https://example.com/search?q=test", cookies=cookies)
print(page.text)

Node.js

javascript// Step 1: Solve the challenge
const response = await fetch("https://api.botpulse.io/f", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key",
  },
  body: JSON.stringify({
    input: {
      url: "https://example.com/search?q=test",
      proxy: "http://user:pass@proxy.example.com:8080",
    },
  }),
});
const data = await response.json();

// Step 2: Use the cookies
const cookieHeader = data.result.cookies.join("; ");

// Step 3: Make a request with the cookies
const page = await fetch("https://example.com/search?q=test", {
  headers: { Cookie: cookieHeader },
});

Error cases

The error field contains a specific message describing what failed: