Edge API Request Parameters

Overview

This document outlines how to make POST requests to the Arkose Labs Edge API, including endpoint structure, required headers, and request body format.

API Access Methods

Edge API can be accessed via a direct HTTP request.

Request URL format:

https://client-api.arkoselabs.com/api/edge/v1/<public_key>

Example using curl:

curl https://client-api.arkoselabs.com/api/edge/v1/<public_key> \
    -H "Content-Type: application/json" \
    -d '{"private_key": "<private_key>", "ip_address": "1.2.3.4"}'

Request Body Parameters

FieldsSub-FieldsTypeRequiredDescription
private_keystringYesThe private key issued by Arkose Labs along with the public key used for the client-side API.
ip_addressstringYesIP address of the client making the request.
osstringNoOperating system name (e.g., "OS X", "Windows").
os_versionstringNoVersion of the OS (e.g., "10.15").
platformstringNoPlatform (e.g., "MacIntel", "Win32").
ja3stringNoJA3 fingerprint of the TLS Client Hello.
ja4stringNoJA4 fingerprint (includes more TLS details).
email_addressstringNoEmail address from the request, if applicable.
headersobjectNoHTTP headers from the client request (key-value pairs).
headers.additionalPropertiesstringNoAdditional properties for headers.
requestobjectNoRequest details.
request.methodstringNoHTTP method used by the client (e.g., GET, POST).
request.urlstringNoOriginating/Use case URL.
tlsobjectNoTLS details.
tls.cipherstringNoTLS cipher suite used (e.g., "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384").
tls.protocolstringNoTLS protocol version (e.g., "TLSv1.3").

Request Schema with Example

The POST request should include a JSON body structure as shown below:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "The edge-api request body schema",
  "type": "object",
  "properties": {
    "private_key": {
      "type": "string"
    },
    "ip_address": {
      "type": "string"
    },
    "os": {
      "type": "string"
    },
    "os_version": {
      "type": "string"
    },
    "platform": {
      "type": "string"
    },
    "ja3": {
      "type": "string"
    },
    "ja4": {
      "type": "string"
    },
    "email_address": {
      "type": "string"
    },
    "headers": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "request": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string"
        },
        "url": {
          "type": "string"
        }
      }
    },
    "tls": {
      "type": "object",
      "properties": {
        "cipher": {
          "type": "string"
        },
        "protocol": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "private_key",
    "ip_address"
  ]
}
{
  "private_key": "B4DFA9BC-XXXX-XXXX-XXXX-D24DD4C8C27D",
  "ip_address": "11.22.33.44",
  "os": "OS X",
  "os_version": "10.15",
  "platform": "MacIntel",
  "ja3": "e7d705a3286e19ea42f587b344ee6865",
  "ja4": "t13d1516h2_8daaf6152771a5b3",
  "email_address": "[email protected]",
  "headers": {
    "Accept": "*/*",
    "Accept-Language": "en-GB,en-US;q=0.9,en;q=0.8",
    "cache-control": "no-cache",
    "content-type": "application/x-www-form-urlencoded; charset=UTF-8",
    "Cookie": "sessionid=abc123; user_preference=something; visitcount=42; auth_token=xyzsometoken",
    "Origin": "https://test-cases.arkoselabs.com",
    "pragma": "no-cache",
    "priority": "u=1, i",
    "Referer": "https://test-cases.arkoselabs.com/",
    "Sec-Ch-Ua": "\"Chromium\";v=\"128\", \"Not;A=Brand\";v=\"24\", \"Google Chrome\";v=\"128\"",
    "SEC-CH-UA-MOBILE": "?0",
    "sec-ch-ua-platform": "\"macOS\"",
    "sec-fetch-dest": "empty",
    "sec-fetch-mode": "cors",
    "sec-fetch-site": "cross-site",
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
  },
  "request": {
    "method": "POST",
    "path": "https://sample-website.com/sample-path"
  },
  "tls": {
    "cipher": "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
    "protocol": "TLSv1.3"
  }
}