" %}
# Tags
DataDome tags are extra telemetry posted to /js that raise a session's trust score and reduce blocks. This page shows how to generate tags payloads with our SDKs.
Unlike slider and interstitial, tags will never be served in a challenge or block page. This type is used to send extra telemetry data to DataDome that will increase trust score of the session (resulting in less blocks).\
\
In browser you will see multiple requests to a `/js`endpoint, this is where browser sends the tags data. This is how you can generate this data using our SDKS:
{% tabs %}
{% tab title="Golang" %}
```go
payload, err := session.GenerateDataDomeTags(ctx, &hyper.DataDomeTagsInput{
UserAgent: "", // Your chrome useragent
Cid: "", // Your current datadome cookie
Ddk: "", // sitekey, static for each site. parse it from the /js/ payload request from browser
Referer: "", // The referer visible as the referer header in the payload POST
Type: "", // First time 'ch', second time 'le'
Language: "", // The first language of your accept-language header, defaults to "en-US"
IP: "", // The IP that is used to post the sensor data to the target site. You can use /ip to get the IP from a connection. If you are not using proxies, this will be the IPv4 address of your pc.
})
if err != nil {
// Handle the error
}
// Use the payload to POST to /js
```
{% endtab %}
{% tab title="Python" %}
```python
payload = hyper_session.generate_tags_payload(hyper_sdk.DataDomeTagsInput(
user_agent=USER_AGENT, # Your chrome UserAgent
cid=cid, # Your current datadome cookie
ddk=ddk, # sitekey, static for each site. parse it from the /js/ payload request from browser
referer=referer, # The referer visible as the referer header in the payload POST
tags_type=tags_type, # First time 'ch', second time 'le'
ip=ip, # The IP that is used to post the sensor data to the target site. You can use /ip to get the IP from a connection. If you are not using proxies, this will be the IPv4 address of your pc.
accept_language=accept_language# The accept language header that you use
))
# Use the payload to POST to /js
```
{% endtab %}
{% tab title="JS / TS" %}
```javascript
const payload = await generateTagsPayload(session, {
userAgent: "", // Your chrome UserAgent
cid: cid, // Your current datadome cookie
ddk: ddk, // sitekey, static for each site. parse it from the /js/ payload request from browser
referer: referer, // The referer visible as the referer header in the payload POST
type: type, // First time 'ch', second time 'le'
ip: ip, // The IP that is used to post the sensor data to the target site. You can use /ip to get the IP from a connection. If you are not using proxies, this will be the IPv4 address of your pc.
acceptLanguage: language, // The accept-language header value
});
```
{% endtab %}
{% endtabs %}
You need to POST this payload to the `/js`endpoint same way browser will do it. The endpoint will return a response like this:
```json
{
"status": 200,
"cookie": "datadome=L7HH_UaWyA17TZFa7FNKxtIE9cReX~6bpf~E5A5IetWsibg0KwHgedPMPHee40cm4VqY9r3Yr6ZOCuWL17WB71PDE92lXdBIyyl3M2SZyhOl~7rmkK_XxE0O19hB4q0o; Max-Age=31536000; Domain=.vinted.fr; Path=/; Secure; SameSite=Lax"
}
```
You should update your `datadome`cookie in your cookiejar manually, with the value returned in the response.\
\
Posting tags should be done twice, always retrieving the `datadome`cookie from the first tags POST request. First with type `ch`and the second time with type `le`.
# Slider (captcha)
This page explains the flow of solving the slider challenge of DataDome.
If you already familiar with solving DataDome challenges, you can either install one of our [SDKs](/start-here/readme-1) for easy integration, or head over to our [API Reference](/api-reference/datadome) if you want to handle the implementation yourself. The [DataDome Bypass API](https://hypersolutions.co/products/datadome) overview covers which challenges the endpoints solve and how they are priced.
## Slider
This challenge is served using a 403 status code and a response body that looks as follows:
{% code overflow="wrap" %}
```html
example.com
Please enable JS and disable any ad blocker
```
{% endcode %}
{% hint style="warning" %}
If in the response, `t` is set to `bv`, it means your proxy is hard blocked, solving the challenge will not have any effect.
{% endhint %}
This is almost the same response you would receive with a Interstitial challenge, however the reference to this URL: `https://ct.captcha-delivery.com/c.js` is unique to slider.
### Parsing the HTML
Before we explain how you can manually parse the required values from the HTML posted above, first are shown code snippets of how it can be done easily with our SDKs:
{% tabs %}
{% tab title="Golang" %}
{% code overflow="wrap" %}
```go
// reader is an `io.Reader` which holds the response body of the HTML.
// datadomeCookie is the cookie value of the cookie with name "datadome",
// this cookie is set by the 403 block page.
// referer is the URL that served the 403 block page.
deviceLink, err := datadome.ParseSliderDeviceCheckLink(reader, datadomeCookie, referer)
if err != nil {
// Handle the error
}
// deviceLink will look like: https://geo.captcha-delivery.com/captcha/?...
```
{% endcode %}
{% endtab %}
{% tab title="Python" %}
{% code overflow="wrap" %}
```python
from hyper_sdk.datadome import parse_slider_device_check_link
device_link = parse_slider_device_check_link(html_content, datadome_cookie, referer)
# device_link will look like: https://geo.captcha-delivery.com/captcha/?...
```
{% endcode %}
{% endtab %}
{% tab title="JS / TS" %}
{% code overflow="wrap" %}
```javascript
import {parseSliderDeviceCheckUrl, generateSliderPayload} from "hyper-sdk-js/datadome/slider.js";
const result = parseSliderDeviceCheckUrl(
"", // Block page body
"", // Value of `datadome` cookie
"" // Referer, e.g. URL you are trying to access
);
if (result.isIpBanned) {
// IP address is banned.
// Note: result.url is null if this is true.
return;
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
If you would rather parse the response yourself, you will need to extract the following fields from the `dd` object that can be found in the response body: `cid`, `hsh`, `t`, `s`, `e`.\
\
You also need to store the URL that received the block, it is used as the `referer`, and the `datadome` cookie that is set on this blocked request.\
\
You can now build the URL as follows:
{% code overflow="wrap" %}
```
https://geo.captcha-delivery.com/captcha/?initialCid={cid}&hash={hsh}&cid={datadomeCookie}&t={t}&referer={referer}&s={s}&e={e}&dm=cd
```
{% endcode %}
### Fetching the slider script
After having parsed the deviceLink in the previous step, you need to make a GET request to it. Make sure that you are sending the same headers and in the same order as your browser. Read and save the response body of this request as we need it to submit to the Hyper Solutions API.
### Fetching the slider puzzle
In order for the Hyper Solutions API to solve the slider challenge, it needs access to the images involved. The HTML/JavaScript that we have retrieved in the previous step contains data like this:
{% code overflow="wrap" %}
```javascript
captchaChallengeSeed: '17af5b20aafd238256f5a5d11cf475da',
captchaChallengePath: 'https://dd.prod.captcha-delivery.com/image/2026-01-19/17af5b20aafd238256f5a5d11cf475da.jpg',
```
{% endcode %}
#### Parsing the Image URLs
You need to extract the `captchaChallengePath` value, which gives you the puzzle image URL directly. To get the piece image URL, simply replace `.jpg` with `.frag.png`.
#### Finding the puzzle link (jpg)
You can parse `captchaChallengePath` using this regex:
```regexp
captchaChallengePath:\s*['"]([^'"]+\.jpg)['"]
```
Or if you already have the path extracted:
```regexp
(https:\/\/dd\.prod\.captcha-delivery\.com\/image\/.*?\.jpg)
```
#### Deriving the piece link (frag.png)
Once you have the puzzle URL, derive the piece URL by replacing the extension:
```javascript
const pieceUrl = puzzleUrl.replace('.jpg', '.frag.png');
```
For example:
* **Puzzle URL:** `https://dd.prod.captcha-delivery.com/image/2026-01-19/17af5b20aafd238256f5a5d11cf475da.jpg`
* **Piece URL:** `https://dd.prod.captcha-delivery.com/image/2026-01-19/17af5b20aafd238256f5a5d11cf475da.frag.png`
### Fetching the Images
You need to make a GET request to both URLs and store both responses (base64 encoded):
* The `.jpg` response should be stored as `puzzle`
* The `.frag.png` response should be stored as `piece`
### Fetching the payload from API
Again we have handy SDK functions to help you with these API calls, if you want to implement the API calls yourself, head over to the [API Reference](/api-reference/datadome).\
\
Alongside your usual session values (User-Agent, IP, Accept-Language, and the page URL as `parentUrl`), you need four challenge-specific values:
* deviceLink: The link parsed in the previous sections.
* html: The full response body of the GET request you made to the deviceLink URL.
* puzzle: The base64-encoded bytes of the `.jpg` image.
* piece: The base64-encoded bytes of the `.frag.png` image.
You can then generate the payload with the SDK as follows:
{% tabs %}
{% tab title="Golang" %}
{% code overflow="wrap" %}
```go
checkUrl, headers, err := session.GenerateDataDomeSlider(ctx, &hyper.DataDomeSliderInput{
UserAgent: userAgent,
DeviceLink: deviceLink,
Html: string(html),
Puzzle: base64Puzzle, // base64 of the .jpg
Piece: base64Piece, // base64 of the .frag.png
ParentUrl: pageUrl,
AcceptLanguage: acceptLanguage,
IP: ip,
})
if err != nil {
// Handle the error
}
// GET the checkUrl; replay the returned headers on subsequent requests
```
{% endcode %}
{% endtab %}
{% tab title="Python" %}
{% code overflow="wrap" %}
```python
result = hyper_session.generate_slider_payload(hyper_sdk.DataDomeSliderInput(
user_agent=user_agent,
device_link=device_link,
html=html,
puzzle=base64_puzzle,
piece=base64_piece,
parent_url=page_url,
accept_language=accept_language,
ip=ip,
))
# GET result["payload"] (the check URL); replay result["headers"] when applicable
```
{% endcode %}
{% endtab %}
{% tab title="JS / TS" %}
{% code overflow="wrap" %}
```javascript
const result = await generateSliderPayload(session, {
userAgent: userAgent,
deviceLink: deviceLink,
html: deviceCheckBody,
puzzle: base64Puzzle, // base64 of the .jpg
piece: base64Piece, // base64 of the .frag.png
parentUrl: pageUrl,
acceptLanguage: acceptLanguage,
ip: ip,
});
// GET result.payload (the check URL); replay result.headers when applicable
```
{% endcode %}
{% endtab %}
{% endtabs %}
### Posting payload, solving challenge
Our API returns a simple URL as the result of solving the slider challenge, all that is required is to make a GET request to this URL which looks as follows:
```
https://geo.captcha-delivery.com/captcha/check?cid=...
```
The response of this GET request will be as follows:
{% code overflow="wrap" %}
```json
{
"cookie": "datadome=cookievalue; Max-Age=31536000; Domain=.example.com; Path=/; Secure; SameSite=Lax"
}
```
{% endcode %}
You can parse the JSON response, and update your cookieJar with the `"cookie"` you received from DataDome.\
\
You have now successfully solved DataDome's slider challenge, retrying the request that served this block should not give you a challenge anymore.
# Interstitial
This page explains the flow of solving the interstitial challenge of DataDome.
If you already familiar with solving DataDome challenges, you can either install one of our [SDKs](/start-here/readme-1) for easy integration, or head over to our [API Reference](/api-reference/datadome) if you want to handle the implementation yourself. The [DataDome Bypass API](https://hypersolutions.co/products/datadome) overview covers which challenges the endpoints solve and how they are priced.
## Interstitial
This challenge is served using a 403 status code and a response body that looks as follows:
{% code overflow="wrap" %}
```html
example.com
Please enable JS and disable any ad blocker
```
{% endcode %}
This is almost the same response you would receive with a Slider challenge, however the reference to this URL: `https://ct.captcha-delivery.com/i.js` is unique to interstitial.
### Parsing the HTML
Before we explain how you can manually parse the required values from the HTML posted above, first are shown code snippets of how it can be done easily with our SDKs:
{% tabs %}
{% tab title="Golang" %}
// reader is an `io.Reader` which holds the response body of the HTML.
// datadomeCookie is the cookie value of the cookie with name "datadome",
// this cookie is set by the 403 block page.
// referer is the URL that served the 403 block page.
deviceLink, err := datadome.ParseInterstitialDeviceCheckLink(reader, datadomeCookie, referer)
if err != nil {
// Handle the error
}
// deviceLink will look like: https://geo.captcha-delivery.com/interstitial/?...
{% endtab %}
{% tab title="Python" %}
{% code overflow="wrap" %}
```python
from hyper_sdk.datadome import parse_interstitial_device_check_link
device_link = parse_interstitial_device_check_link(html_content, datadome_cookie, referer)
# device_link will look like: https://geo.captcha-delivery.com/interstitial/?...
```
{% endcode %}
{% endtab %}
{% tab title="JS/TS" %}
{% code overflow="wrap" %}
```javascript
import parseInterstitialDeviceCheckUrl from "hyper-sdk-js/datadome/interstitial.js";
const deviceCheckUrl = parseInterstitialDeviceCheckUrl(
"", // Block page body
"", // Value of `datadome` cookie
"" // Referer, e.g. URL you are trying to access
);
if (deviceCheckUrl === null) {
// deviceCheckUrl will be null if parseInterstitialDeviceCheckUrl failed to parse it.
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
If you would rather parse the response yourself, you will need to extract the following fields from the `dd` object that can be found in the response body: `cid`, `hsh`, `s`, `b`.\
\
You also need to store the URL that received the block, it is used as the `referer`, and the `datadome` cookie that is set on this blocked request.\
\
You can now build the URL as follows:
{% code overflow="wrap" %}
```
https://geo.captcha-delivery.com/interstitial/?initialCid={cid}&hash={hsh}&cid={datadomeCookie}&referer={referer}&s={s}&b={b}&dm=cd
```
{% endcode %}
We will call this URL the deviceLink from now on.
### Fetching the interstitial script
After having parsed the deviceLink in the previous step, you need to make a GET request to it. Make sure that you are sending the same headers and in the same order as your browser. Read and save the response body of this request as we need it to submit to the Hyper Solutions API.
### Fetching the payload from API
Again we have handy SDK functions to help you with these API calls, if you want to implement the API calls yourself, head over to the [API Reference](/api-reference/datadome).\
\
Alongside your usual session values (User-Agent, IP, Accept-Language), you need two challenge-specific values:
* deviceLink: The link parsed in one of the previous sections.
* html: The full response body of the GET request you made to the deviceLink URL.
You can then generate the payload with the SDK as follows:
{% tabs %}
{% tab title="Golang" %}
{% code overflow="wrap" %}
```go
payload, headers, err := session.GenerateDataDomeInterstitial(ctx, &hyper.DataDomeInterstitialInput{
UserAgent: userAgent,
DeviceLink: deviceLink,
Html: string(html),
AcceptLanguage: acceptLanguage,
IP: ip,
})
if err != nil {
// Handle the error
}
// POST the payload; replay the returned headers on subsequent requests
```
{% endcode %}
{% endtab %}
{% tab title="Python" %}
{% code overflow="wrap" %}
```python
result = hyper_session.generate_interstitial_payload(hyper_sdk.DataDomeInterstitialInput(
user_agent=user_agent,
device_link=device_check_link,
html=html_content,
accept_language=accept_language,
ip=ip,
))
# POST result["payload"] to https://geo.captcha-delivery.com/interstitial/
# Replay result["headers"] on subsequent requests when required
```
{% endcode %}
{% endtab %}
{% tab title="JS / TS" %}
{% code overflow="wrap" %}
```javascript
const result = await generateInterstitialPayload(session, {
userAgent: userAgent,
deviceLink: deviceCheckUrl,
html: deviceCheckBody,
ip: ip,
acceptLanguage: acceptLanguage,
});
// POST result.payload to https://geo.captcha-delivery.com/interstitial/
// Replay result.headers on subsequent requests when required
```
{% endcode %}
{% endtab %}
{% endtabs %}
### Posting payload, solving challenge
The payload returned by the HyperSolutions API in the previous step is an already concatenated Form Data string, you can POST this to the following URL:
```
https://geo.captcha-delivery.com/interstitial/
```
And make sure you are matching the headers in the order that your browser used.\
\
The response of this POST request will be as follows:
{% code overflow="wrap" %}
```json
{
"cookie": "datadome=cookievalue; Max-Age=31536000; Domain=.example.com; Path=/; Secure; SameSite=Lax",
"view": "redirect",
"url": "https://www.example.com/path"
}
```
{% endcode %}
You can parse the JSON response, and update your cookieJar with the `"cookie"` you received from DataDome.\
\
You have now successfully solved DataDome's interstitial challenge, retrying the request that served this block should not give you a challenge anymore.
# Getting started
This page covers the different Kasada implementation flows you may encounter.
If you're already familiar with Kasada and wish to implement the API handling yourself, you can skip this and head directly to the [API Reference](/api-reference/kasada). The [Kasada Bypass API](https://hypersolutions.co/products/kasada) overview covers which challenges the endpoints solve and how they are priced.
{% hint style="info" %}
As with any other antibot, make sure you use a working TLS client that mimics the latest version of Google Chrome, match the headers and header-order 1:1 with the browser, and make sure you are using an up-to-date User-Agent. See [Core Requirements](/start-here/core-requirements) for the full list.
{% endhint %}
### Understanding Kasada Flows
Kasada can be implemented in two different ways depending on the website. It's important to identify which flow you're dealing with:
#### Flow 1: Initial Block Page (429 on Homepage)
Some sites, like Hyatt.com, serve a Kasada challenge immediately when you first access the website. You'll receive a **429 status code** with an HTML block page containing a reference to the `ips.js` script.
**Identifying characteristics:**
* First GET request to the website returns 429 status code
* Response body contains: ``
* You must solve the challenge before accessing any content on the site
**When to use this flow:**
* Site blocks you immediately on homepage access
* You see 429 status code with Kasada script reference
* Site reloads after posting `/tl`
[Read the detailed guide →](/k4sada/flow-1-initial-block-page)
#### Flow 2: Fingerprint Endpoint (/fp)
Most sites implement Kasada by having the browser make a request to the `/fp` (fingerprint) endpoint in the background. This is the standard Kasada implementation.
**Identifying characteristics:**
* Browser makes GET request to `/149e9513-01fa-4fb0-aad4-566afd725d1b/2d206a39-8ed7-437e-a3be-862e0f06eea3/fp`
* This request returns 429 with the `ips.js` script reference
* You can often access the site initially, but need to solve Kasada for protected endpoints
* May require `x-kpsdk-cd` header on subsequent requests
**When to use this flow:**
* You can access the homepage but get challenged on specific endpoints
* Browser makes background request to `/fp` endpoint
* You need to maintain `x-kpsdk-ct` token for ongoing requests
[Read the detailed guide →](/k4sada/flow-2-fingerprint-endpoint)
### Next Steps
Choose the appropriate flow based on what you observe:
* **Getting 429 immediately on homepage?** → [Flow 1: Initial Block Page](/k4sada/flow-1-initial-block-page)
* **Browser making /fp requests?** → [Flow 2: Fingerprint Endpoint](/k4sada/flow-2-fingerprint-endpoint)
Both flows share the same core process of fetching the script, generating a payload, and posting to `/tl`. The main difference is when and where the challenge is triggered.
### Related
* [Vercel BotID](/k4sada/vercel-botid): a separate Kasada-powered detection layer that adds an `x-is-human` header, generated on its own endpoint.
* [Supported User Agents](/k4sada/supported-user-agents): the desktop and mobile-app User-Agents Kasada accepts.
### Complete Example
For a full working implementation with proper TLS client setup, header ordering, and cookie handling, see our examples repository:
{% embed url="" %}
# Flow 1: Initial Block Page
This flow applies to websites like Hyatt.com where Kasada blocks you immediately when you first access the site with a 429 status code.
### Overview
When you make your first GET request to the website, you'll receive a **429 status code** with an HTML response containing a Kasada script reference. You must solve this challenge before you can access any content on the site.
### Initial Request
The response will be a 429 status code with HTML that looks like this:
{% code overflow="wrap" %}
```html
```
{% endcode %}
### Step 1: Parse the Script Path
You need to extract the script path from the HTML response. The script URL will look like:
```
/149e9513-01fa-4fb0-aad4-566afd725d1b/2d206a39-8ed7-437e-a3be-862e0f06eea3/ips.js?...
```
You can parse this using our SDKs:
{% tabs %}
{% tab title="Go" %}
{% code overflow="wrap" %}
```go
scriptPath, err := kasada.ParseScriptPath(reader)
if err != nil {
// Handle the error
}
// scriptPath will look like: /149e9513-01fa-4fb0-aad4-566afd725d1b/2d206a39-8ed7-437e-a3be-862e0f06eea3/ips.js?...
```
{% endcode %}
{% endtab %}
{% tab title="Python" %}
```python
from hyper_sdk.kasada import parse_script_path
script_path = parse_script_path(html_content)
# script_path will look like: /149e9513-01fa-4fb0-aad4-566afd725d1b/2d206a39-8ed7-437e-a3be-862e0f06eea3/ips.js?...
```
{% endtab %}
{% tab title="JS / TS" %}
```javascript
import { parseKasadaPath } from 'hyper-sdk-js';
const scriptPath = parseKasadaPath(blockedPageHtml);
```
{% endtab %}
{% endtabs %}
### Step 2: Fetch the ips.js Script
Make a GET request to the script path you parsed. Make sure to:
* Use the full URL: `https://www.example.com{scriptPath}`
* Match browser headers exactly
* Maintain the same header order as Chrome
Save the JavaScript response body as you'll need it for the next step.
### Step 3: Generate Payload via API
Now you'll use the Hyper Solutions API to generate the payload and headers needed for the `/tl` request.
Refer to the [Kasada](/api-reference/kasada) and the SDK documentation for accurate fields.
{% tabs %}
{% tab title="Golang" %}
{% code overflow="wrap" %}
```go
payload, headers, err := session.GenerateKasadaPayload(ctx, &hyper.KasadaPayloadInput{
// Kasada payload configuration
})
if err != nil {
// Handle the error
}
// payload and headers are ready for the /tl request
```
{% endcode %}
{% endtab %}
{% tab title="Python" %}
{% code overflow="wrap" %}
```python
from hyper_sdk import KasadaPayloadInput
payload, headers = session.generate_kasada_payload(KasadaPayloadInput(
# kasada payload input fields
))
```
{% endcode %}
{% endtab %}
{% tab title="JS / TS" %}
{% code overflow="wrap" %}
```javascript
import { KasadaPayloadInput, generateKasadaPayload } from 'hyper-sdk-js';
const result = await generateKasadaPayload(session, new KasadaPayloadInput(
// kasada payload input fields
));
const payload = result.payload;
const headers = result.headers;
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
The payload returned by the API is base64-encoded. You must decode it before posting to `/tl`.
{% endhint %}
### Step 4: POST to /tl Endpoint
POST the decoded payload to the `/tl` endpoint:
```
https://www.example.com/149e9513-01fa-4fb0-aad4-566afd725d1b/2d206a39-8ed7-437e-a3be-862e0f06eea3/tl
```
**Critical requirements:**
* Content-Type must be `application/octet-stream`
* Include all headers returned by the API (`x-kpsdk-im`, `x-kpsdk-ct`, `x-kpsdk-dt`)
* Match browser header order exactly
* POST the decoded (binary) payload
### Step 5: Parse /tl Response
A successful response will return **200 status code** with:
**Response body:**
```json
{
"reload": true
}
```
**Critical response headers to save:**
* `x-kpsdk-ct`: Token for subsequent requests (also in cookies)
* `x-kpsdk-st`: Timestamp value needed for generating POW (`x-kpsdk-cd`) headers
* `set-cookie`: Kasada cookies (e.g., `tkrm_alpekz_s1.3`, `tkrm_alpekz_s1.3-ssn`)
Example response headers:
{% code overflow="wrap" %}
```
x-kpsdk-ct: 02Rrkf95YyBbq2lGyws6SFVp...
x-kpsdk-st: 1759149934586
set-cookie: tkrm_alpekz_s1.3=02Rrkf95YyBbq2lGyws6SFVp...; Max-Age=86400; Path=/; HttpOnly
set-cookie: tkrm_alpekz_s1.3-ssn=02Rrkf95YyBbq2lGyws6SFVp...; Max-Age=86400; Path=/; HttpOnly; Secure; SameSite=None
```
{% endcode %}
{% hint style="info" %}
Store these values in your session:
* Update your cookie jar with the Set-Cookie headers
* Save `x-kpsdk-st` for future POW generation
* Save `x-kpsdk-ct` if you need to include it in request headers (check if browser does)
{% endhint %}
### Step 6: Retry Original Request
Now retry your original request to the website with the Kasada cookies. The site should no longer serve you a 429 block page.
**Make sure to:**
* Include all Kasada cookies in your request
* Maintain proper headers and header order
### Summary
The complete flow:
1. ✅ Initial GET → Receive 429 with block page
2. ✅ Parse script path from HTML
3. ✅ GET request to ips.js script
4. ✅ Generate payload via Hyper Solutions API
5. ✅ POST decoded payload to /tl endpoint
6. ✅ Parse response headers and cookies
7. ✅ Retry original request with cookies
You have now successfully bypassed Kasada's initial block page challenge!
# Flow 2: Fingerprint Endpoint
This is the standard Kasada implementation where the browser makes a background request to the /fp (fingerprint) endpoint. This flow applies to most Kasada-protected websites.
### Overview
Unlike Flow 1, you may be able to access the homepage initially. Kasada is triggered when the browser makes a GET request to:
```
/149e9513-01fa-4fb0-aad4-566afd725d1b/2d206a39-8ed7-437e-a3be-862e0f06eea3/fp
```
This request returns a 429 status code with the Kasada challenge. After solving it, you'll receive tokens and cookies that must be included in subsequent requests to protected endpoints.
### Step 1: Request the /fp Endpoint
Make a GET request to the fingerprint endpoint with query parameter `x-kpsdk-v`:
{% code overflow="wrap" %}
```
https://www.example.com/149e9513-01fa-4fb0-aad4-566afd725d1b/2d206a39-8ed7-437e-a3be-862e0f06eea3/fp?x-kpsdk-v=j-xxx
```
{% endcode %}
The response will be a **429 status code** with HTML that looks like this:
{% code overflow="wrap" %}
```html
```
{% endcode %}
### Step 2: Parse the Script Path
Extract the script path from the HTML response. The script URL will look like:
```
/149e9513-01fa-4fb0-aad4-566afd725d1b/2d206a39-8ed7-437e-a3be-862e0f06eea3/ips.js?...
```
You can parse this using our SDKs:
{% tabs %}
{% tab title="Golang" %}
{% code overflow="wrap" %}
```go
scriptPath, err := kasada.ParseScriptPath(reader)
if err != nil {
// Handle the error
}
// scriptPath will look like: /149e9513-01fa-4fb0-aad4-566afd725d1b/2d206a39-8ed7-437e-a3be-862e0f06eea3/ips.js?...
```
{% endcode %}
{% endtab %}
{% tab title="Python" %}
{% code overflow="wrap" %}
```python
from hyper_sdk.kasada import parse_script_path
script_path = parse_script_path(blocked_page_html)
# Returns: /ips.js?.
```
{% endcode %}
{% endtab %}
{% tab title="JS / TS" %}
{% code overflow="wrap" %}
```javascript
import { parseKasadaPath } from 'hyper-sdk-js';
const scriptPath = parseKasadaPath(blockedPageHtml);
```
{% endcode %}
{% endtab %}
{% endtabs %}
### Step 3: Fetch the ips.js Script
Make a GET request to the script path you parsed. Make sure to:
* Use the full URL: `https://www.example.com{scriptPath}`
* Match browser headers exactly
* Maintain the same header order as Chrome
* Set referer to the `/fp` URL
Save the JavaScript response body as you'll need it for the next step.
### Step 4: Generate Payload via API
Use the Hyper Solutions API to generate the payload and headers needed for the `/tl` request.\
\
Refer to the [Kasada](/api-reference/kasada) and the SDK documentation for accurate fields.
{% tabs %}
{% tab title="Golang" %}
{% code overflow="wrap" %}
```go
payload, headers, err := session.GenerateKasadaPayload(ctx, &hyper.KasadaPayloadInput{
// Fields
})
if err != nil {
// Handle the error
}
// payload and headers are ready for the /tl request
```
{% endcode %}
{% endtab %}
{% tab title="Python" %}
{% code overflow="wrap" %}
```python
from hyper_sdk import KasadaPayloadInput
payload, headers = session.generate_kasada_payload(KasadaPayloadInput(
# kasada payload input fields
))
```
{% endcode %}
{% endtab %}
{% tab title="JS / TS" %}
{% code overflow="wrap" %}
```javascript
import { KasadaPayloadInput, generateKasadaPayload } from 'hyper-sdk-js';
const result = await generateKasadaPayload(session, new KasadaPayloadInput(
// kasada payload input fields
));
const payload = result.payload;
const headers = result.headers;
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
The payload returned by the API is base64-encoded. You must decode it before posting to `/tl`.
{% endhint %}
### Step 5: POST to /tl Endpoint
POST the decoded payload to the `/tl` endpoint:
```
https://www.example.com/149e9513-01fa-4fb0-aad4-566afd725d1b/2d206a39-8ed7-437e-a3be-862e0f06eea3/tl
```
**Critical requirements:**
* Content-Type must be `application/octet-stream`
* Include all headers returned by the API (`x-kpsdk-im`, `x-kpsdk-ct`, `x-kpsdk-dt`)
* Match browser header order exactly
* POST the decoded (binary) payload
* Set referer to the `/fp` URL
### Step 6: Parse /tl Response
A successful response will return **200 status code** with:
**Response body:**
```json
{
"reload": true
}
```
**Critical response headers to save:**
* `x-kpsdk-ct`: Token that must be included in subsequent requests to protected endpoints
* `x-kpsdk-st`: Timestamp value needed for generating POW (`x-kpsdk-cd`) headers
* `set-cookie`: Kasada cookies (e.g., `tkrm_alpekz_s1.3`, `tkrm_alpekz_s1.3-ssn`)
Example response headers:
{% code overflow="wrap" %}
```
x-kpsdk-ct: 02Rrkf95YyBbq2lGyws6SFVp...
x-kpsdk-st: 1759149934586
set-cookie: tkrm_alpekz_s1.3=02Rrkf95YyBbq2lGyws6SFVp...; Max-Age=86400; Path=/; HttpOnly
set-cookie: tkrm_alpekz_s1.3-ssn=02Rrkf95YyBbq2lGyws6SFVp...; Max-Age=86400; Path=/; HttpOnly; Secure; SameSite=None
```
{% endcode %}
{% hint style="info" %}
Store these values in your session:
* Update your cookie jar with the Set-Cookie headers
* Save `x-kpsdk-st` for future POW generation
* Save `x-kpsdk-ct` as you'll need to include it in request headers to protected endpoints
{% endhint %}
### Step 7: Making Requests to Protected Endpoints
Now you can make requests to protected endpoints with the Kasada tokens. **Observe what headers the browser includes** and match them exactly.
#### Headers to include:
1. **Kasada cookies** (always required):
* Include all cookies from the `/tl` response in your Cookie header
2. **x-kpsdk-ct header** (if browser includes it):
* Use the value from the `/tl` response headers, or the one that was last returned from a protected endpoint.
* Some sites require this in the header, others only use cookies
3. **x-kpsdk-cd header** (if browser includes it):
* This is a POW (Proof of Work) that must be freshly generated for **each request**
* See the section below for how to generate it
### Fetch Client Configuration (Optional - /mfc)
Some Kasada implementations require an additional step to fetch client configuration. If you observe the browser making a GET request to the `/mfc` endpoint, you'll need to include this step.
#### When to use /mfc
Check your browser's network logs. If you see a request to:
```
/149e9513-01fa-4fb0-aad4-566afd725d1b/2d206a39-8ed7-437e-a3be-862e0f06eea3/mfc
```
Then you need to perform this step after solving the initial challenge and before making requests to protected endpoints.
#### Requesting /mfc
Make a GET request to the `/mfc` endpoint:
```
https://www.example.com/149e9513-01fa-4fb0-aad4-566afd725d1b/2d206a39-8ed7-437e-a3be-862e0f06eea3/mfc
```
**Important:**
* Include your Kasada cookies from the `/tl` response
* Match browser headers and header order
* The request should return a 200 status code
#### Parse /mfc Response Headers
The response will include these critical headers:
* **x-kpsdk-fc**: Feature configuration value needed for POW generation on sites using `/mfc`
* **x-kpsdk-h**: Header value that may be required on subsequent requests to protected endpoints
Example response headers:
```
x-kpsdk-fc: AH4kT...
x-kpsdk-h: 1-BwVlRFs
```
{% hint style="info" %}
Store both values:
* Save `x-kpsdk-fc` to use when generating POW (`x-kpsdk-cd`) headers
* Save `x-kpsdk-h` and include it in requests to protected endpoints if the browser does
{% endhint %}
{% hint style="warning" %}
If your site doesn't use `/mfc` (you don't see it in browser logs), you can skip this step entirely and omit the `fc` parameter when generating POW.
{% endhint %}
### Generating x-kpsdk-cd for Each Request
If the website requires the `x-kpsdk-cd` header on requests (check browser behavior), you **must** generate a fresh POW for **each and every request**. Never reuse POW values.
{% tabs %}
{% tab title="Golang" %}
{% code overflow="wrap" %}
```go
powPayload, err := session.GenerateKasadaPow(ctx, &hyper.KasadaPowInput{
// POW challenge parameters
})
if err != nil {
// Handle error
}
```
{% endcode %}
{% endtab %}
{% tab title="Python" %}
{% code overflow="wrap" %}
```python
from hyper_sdk import KasadaPowInput
pow_payload = session.generate_kasada_pow(KasadaPowInput(
# kasada pow input fields
))
```
{% endcode %}
{% endtab %}
{% tab title="JS / TS" %}
{% code overflow="wrap" %}
```javascript
import { KasadaPowInput, generateKasadaPow } from 'hyper-sdk-js';
const powPayload = await generateKasadaPow(session, new KasadaPowInput(
// kasada pow input fields
));
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% hint style="danger" %}
**CRITICAL**: The `x-kpsdk-cd` header must be regenerated for every single request. Reusing POW values will cause your requests to fail. Generate a new POW immediately before making each request.
{% endhint %}
{% hint style="warning" %}
**Use the latest `x-kpsdk-ct`, not just the one from `/tl`.** POW generation takes a `ct` value, and that token is refreshed as you go: responses (including from protected endpoints) can return a new `x-kpsdk-ct` header. Each time one does, update your stored `ct` and pass that latest value when generating the next POW. Only the most recent `ct` works, a stale value such as the original `/tl` token will make `/cd` fail. The `st` timestamp stays as returned by `/tl`.
{% endhint %}
### When to Re-solve the Challenge
You may need to re-solve the Kasada challenge (repeat the entire flow) if:
* Your Kasada cookies expire
* You receive a 429 response on protected endpoints
To maintain long-running sessions:
* Proactively refresh tokens before they expire
* Handle 429 responses by triggering a new challenge solve
### Summary
The complete flow:
1. ✅ GET request to `/fp` endpoint → Receive 429 with block page
2. ✅ Parse script path from HTML
3. ✅ GET request to ips.js script
4. ✅ Generate payload via Hyper Solutions API
5. ✅ POST decoded payload to /tl endpoint
6. ✅ Parse response headers and cookies
7. ✅ Make requests to protected endpoints with:
* Kasada cookies (always)
* `x-kpsdk-ct` header (if browser uses it)
* `x-kpsdk-cd` header (if browser uses it - generate fresh for each request)
You have now successfully integrated Kasada's flow!
# Vercel BotID
This flow applies when a site is protected by Kasada through Vercel BotID. You can identify this by the presence of the \`x-is-human\` header on requests to protected endpoints.
#### Overview
Vercel BotID is a bot detection system that can be used alongside Kasada protection. When enabled, protected endpoints require an `x-is-human` header containing a generated token. You can identify sites using Vercel BotID by observing the `x-is-human` header in browser requests to protected endpoints.
#### Step 1: Fetch the c.js Script
Make a GET request to the BotID script. The script path follows this pattern:
{% code overflow="wrap" %}
```
https://www.example.com/149e9513-01fa-4fb0-aad4-566afd725d1b/2d206a39-8ed7-437e-a3be-862e0f06eea3/a-4-a/c.js?i=0&v=3&h=www.example.com
```
{% endcode %}
**Critical requirements:**
* Match browser headers exactly
* Maintain the same header order as Chrome
Save the JavaScript response body as you'll need it for the next step.
#### Step 2: Generate the x-is-human Header via API
Use the Hyper Solutions API to generate the `x-is-human` header value. See the [API Reference](/api-reference/kasada) for the full field list.
{% tabs %}
{% tab title="Golang" %}
{% code overflow="wrap" %}
```go
header, err := session.GenerateBotIDHeader(ctx, &hyper.BotIDHeaderInput{
Script: scriptBody,
UserAgent: "your-user-agent",
IP: "your-proxy-ip",
AcceptLanguage: "en-US,en;q=0.9",
})
if err != nil {
// Handle the error
}
// header is ready to use as x-is-human value
```
{% endcode %}
{% endtab %}
{% tab title="Python" %}
{% code overflow="wrap" %}
```python
from hyper_sdk import BotIDHeaderInput
header = session.generate_botid_header(BotIDHeaderInput(
script=script_body,
user_agent="your-user-agent",
ip="your-proxy-ip",
accept_language="en-US,en;q=0.9",
))
```
{% endcode %}
{% endtab %}
{% tab title="JS / TS" %}
{% code overflow="wrap" %}
```javascript
import { BotIDHeaderInput, generateBotIDHeader } from 'hyper-sdk-js';
const header = await generateBotIDHeader(session, new BotIDHeaderInput({
script: scriptBody,
userAgent: "your-user-agent",
ip: "your-proxy-ip",
acceptLanguage: "en-US,en;q=0.9",
}));
```
{% endcode %}
{% endtab %}
{% endtabs %}
#### Step 3: Making Requests to Protected Endpoints
Include the generated token in the `x-is-human` header on requests to protected endpoints. **Observe what headers the browser includes** and match them exactly.
#### When to Re-generate the Header
You may need to generate a new `x-is-human` header if:
* You receive a 429 response on protected endpoints
* Your proxy IP address changes
#### Summary
The complete flow:
1. ✅ GET request to `c.js` script endpoint
2. ✅ Generate `x-is-human` header via Hyper Solutions API
3. ✅ Make requests to protected endpoints with the `x-is-human` header
You have now successfully integrated Vercel BotID!
# Supported User Agents
This page documents all user agent configurations supported by the Hyper Solutions Kasada API.
### Desktop User Agents
#### Windows Chrome (Recommended)
```
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/{REPLACETHIS}.0.0.0 Safari/537.36
```
Windows remains our recommended default for desktop configurations.
#### macOS Chrome
```
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/{REPLACETHIS}.0.0.0 Safari/537.36
```
macOS support is available for specific use cases where Windows user agents may face temporary restrictions.
### Mobile User Agents
The Kasada API also supports the following mobile app user agents:
```
FootLocker/X.X.X iOS/X.X
ChampsSports/X.X.X iOS/X.X
KidsFootLocker/X.X.X iOS/X.X
FLCA/CFNetwork/Darwin
FLEU/CFNetwork/Darwin
Whatnot vXX.XX.0 (XX), iOS X.X, iPhoneXX,X
SNKRS/X.X.X (prod; XXXXXXXXXX; iOS X.X; iPhoneX,X)
NikeApp/XX.XX.X (prod; XXXXXXXXXX; iOS X.X; iPhoneX,X)
Sephora X.X, iOS XX.X.X, iPhoneXX,X
```
**Note:** The app version (e.g., `X.X.X`) and iOS version (e.g., `iOS X,X`) will change over time. Ensure you are using current versions for the best results.
#### X-Kpsdk-Dv header value for mobile
This value is hardcoded and we can't return it to you for the mobile endpoints. You can use the following strings:
```
QkZWEmcDRUBEDloaAg8GABpSDxVEX1JfXBRZRQF5VRoJFFozUQtXBABQGwEPHA==
QkZWEmcDRUBEDloaAg8GABpRDxVEX1JfXBRZRQF5VRoJFFozUQtXBABRGwEPHA==
```
# Authentication
Authentication can be done in two ways.
## API Key
This is the easiest way to authenticate, simply add the `x-api-key` header with your API Key to your requests.
## API Key + JWT Signing
Using JWT adds a degree of complexity but it is strongly recommended to use when you are going to call this API in client-side applications.\
\
The JWT Token offers an additional layer of security since it will remain in your source code and will not be sent with requests.\
\
You will still need to add the `x-api-key` to your requests and this time also `x-signature`. It can be generated as follows:
{% tabs %}
{% tab title="Go" %}
```go
import (
"github.com/golang-jwt/jwt/v5"
)
func GenerateSignature(apiKey, jwtKey string) (string, error) {
claims := jwt.MapClaims{}
claims["key"] = apiKey
claims["exp"] = time.Now().Add(time.Second * 15).Unix() // this prevents replay attacks
token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
tokenString, err := token.SignedString([]byte(jwtKey))
if err != nil {
return "", err
}
return tokenString, nil
}
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const jwt = require('jsonwebtoken');
function generateSignature(apiKey, jwtKey) {
const claims = {
key: apiKey,
// Set expiration to 15 seconds from now to prevent replay attacks
exp: Math.floor(Date.now() / 1000) + 15,
};
try {
const tokenString = jwt.sign(claims, jwtKey, { algorithm: 'HS256' });
return tokenString;
} catch (err) {
throw err;
}
}
```
{% endtab %}
{% tab title="Python" %}
The following function requires `PyJWT` to be installed.
```
pip install PyJWT
```
```python
import jwt
import time
def generate_signature(api_key, jwt_key):
claims = {
'key': api_key,
# Set expiration to 15 seconds from now to prevent replay attacks
'exp': int(time.time()) + 15,
}
try:
token_string = jwt.encode(claims, jwt_key, algorithm='HS256')
return token_string
except Exception as error:
raise error
```
{% endtab %}
{% endtabs %}
### Organizations
Organization owners can authenticate API requests on behalf of their users by using their App Key and App Secret. These credentials are available in your organization dashboard.
Add the following headers to your requests:
| Header | Description |
| ----------------- | -------------------------------------------------- |
| `x-api-key` | The user's API Key |
| `x-app-key` | Your organization's App Key |
| `x-app-signature` | A signed JWT token generated using your App Secret |
The signature is generated the same way as the standard JWT signing method:
{% tabs %}
{% tab title="Go" %}
```go
import (
"time"
"github.com/golang-jwt/jwt/v5"
)
func generateSignature(appKey string, appSecret []byte) (string, error) {
claims := jwt.MapClaims{
"key": appKey,
"exp": time.Now().Add(time.Minute).Unix(),
}
token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
return token.SignedString(appSecret)
}
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const jwt = require('jsonwebtoken');
function generateSignature(appKey, appSecret) {
const claims = {
key: appKey,
exp: Math.floor(Date.now() / 1000) + 60,
};
return jwt.sign(claims, appSecret, { algorithm: 'HS256' });
}
```
{% endtab %}
{% tab title="Python" %}
```python
import jwt
import time
def generate_signature(app_key: str, app_secret: str) -> str:
claims = {
'key': app_key,
'exp': int(time.time()) + 60,
}
return jwt.encode(claims, app_secret, algorithm='HS256')
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
The `x-app-key` and `x-app-signature` headers are only for organization owners. Individual users should continue using the standard `x-api-key` authentication.
{% endhint %}
# Akamai
API reference for the Hyper Solutions Akamai API: generate sensor data, SBSD payloads and SEC-CPT challenge responses for sites behind Akamai Bot Manager.
{% hint style="info" %}
Tip: Use one of the [SDKs](/start-here/readme-1) instead of directly calling the API.
{% endhint %}
This API generates human-like data based on the most recent chrome browser version on Windows. It is recommended to match the latest TLS and UserAgent of the newest chrome version when using this API on a site.\
\
The latest chrome useragents can be found [here](https://versionhistory.googleapis.com/v1/chrome/platforms/win/channels/stable/versions/). It is perfectly fine to use only one useragent for all your requests.\
\
Note that all request payloads to this API should be sent as `application/json`.\
\
It is advised to use one of the sdks that were written for this API. Feel free to contact me about them.
## Generate sensor data
## Generate sensor data
> Generates sensor data that should be posted in order to acquire valid "\_abck" cookies
```json
{"openapi":"3.0.0","info":{"title":"AKM Sensor Data and Pixel Payload API","version":"1.0.0"},"servers":[{"url":"https://akm.hypersolutions.co","description":"Main server for sensor and pixel endpoints"}],"paths":{"/v2/sensor":{"post":{"summary":"Generate sensor data","description":"Generates sensor data that should be posted in order to acquire valid \"_abck\" cookies","operationId":"generateSensorData","parameters":[{"in":"header","name":"Content-Type","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The Content-Type of the request body"},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"Your API key for authentication"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["abck","bmsz","pageUrl","version","userAgent","script","scriptUrl","ip","acceptLanguage","context"],"properties":{"abck":{"type":"string","description":"The \"_abck\" cookie to generate sensor data with. This should be obtained from your cookie jar. The cookie for the first request should be from doing a GET request to the script endpoint."},"bmsz":{"type":"string","description":"The \"bm_sz\" cookie to generate sensor data with."},"pageUrl":{"type":"string","description":"The page URL to insert into the generated sensor data. This should be the URL of the page you're currently on, like a product page, login page or home page."},"version":{"type":"string","description":"The Akamai version that the site is on. Supported values are \"2\" and \"3\". When using v3 dynamic, set this value to \"3\"."},"userAgent":{"type":"string","description":"The userAgent that you're using for the entire session"},"script":{"type":"string","description":"Script contents as string. Mutually exclusive with context. Should only be sent on first sensor request."},"scriptUrl":{"type":"string","description":"The script URL that you are posting sensor data to."},"ip":{"type":"string","description":"The IP that is used to post the sensor data to the target site. You can use /ip to get the IP from a connection. If you are not using proxies, this will be the IPv4 or IPv6 address of your pc."},"acceptLanguage":{"type":"string","description":"Your accept-language header."},"context":{"type":"string","description":"Leave empty for first sensor, update with context string from response for later sensors."}}}}}},"responses":{"200":{"description":"OK Sensor data successfully generated","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string","description":"The generated sensor data"},"context":{"type":"string","description":"The context value to use for generating the next sensor"}}}}}},"400":{"description":"Bad Request Error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}},"403":{"description":"Forbidden Authentication error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}}}}}}}
```
## Sbsd
Sbsd is a new challenge meant to block scrapings from accessing HTML. You will find it with a blocking page that looks like this:
```html
```
It is important to parse the UUID, this can be done with the following regex:
```regex
v=(.*?)&
```
After parsing the UUID you can make a request to my API with the following API Reference:
## Generate sbsd payload
> Generates sbsd payload that should be posted in order to get around sbsd page
```json
{"openapi":"3.0.0","info":{"title":"AKM Sensor Data and Pixel Payload API","version":"1.0.0"},"servers":[{"url":"https://akm.hypersolutions.co","description":"Main server for sensor and pixel endpoints"}],"paths":{"/sbsd":{"post":{"summary":"Generate sbsd payload","description":"Generates sbsd payload that should be posted in order to get around sbsd page","operationId":"generateSbsdPayload","parameters":[{"in":"header","name":"Content-Type","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The Content-Type of the request body"},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"Your API key for authentication"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["index","pageUrl","uuid","userAgent","o","script","ip","acceptLanguage"],"properties":{"index":{"type":"number","description":"Always set to 0 when solving sbsd challenge with `t` parameter. Otherwise start from 0 and keep incrementing. On some sites, posting 2 sbsd sensors gives much better success rates."},"pageUrl":{"type":"string","description":"This should be the URL of the page you're currently on, like a product page, login page or home page. It's also the referer on the sbsd post request in browser."},"uuid":{"type":"string","description":"The uuid of the sbsd challenge (https://example.com/.well-known/sbsd?v=dcc78710-14fe-3835-cc6e-b9b5ea3b6010). uuid is dcc78710-14fe-3835-cc6e-b9b5ea3b6010 on this url."},"userAgent":{"type":"string","description":"The userAgent that you're using for the entire session"},"o":{"type":"string","description":"The \"sbsd_o\" cookie value, if \"sbsd_o\" is not present, use the cookie value from \"bm_so\"."},"script":{"type":"string","description":"The script body as a string."},"acceptLanguage":{"type":"string","description":"Your accept-language header."},"ip":{"type":"string","description":"The IP that is used to post the sensor data to the target site. You can use /ip to get the IP from a connection. If you are not using proxies, this will be the IPv4 or IPv6 address of your pc."}}}}}},"responses":{"200":{"description":"OK Sbsd payload successfully generated","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string","description":"The generated sbsd payload"}}}}}},"400":{"description":"Bad Request Error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}},"403":{"description":"Forbidden Authentication error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}}}}}}}
```
You can then post the payload string to the following endpoint:
```
https://example.com/.well-known/sbsd
```
Making a new GET request to the same page (make sure that cookies are included in this request) it will show you the full HTML.
## Pixel
Pixel is not required by most sites. Please discuss with support first if you think the site requires it. Your site having the pixel script does not mean it has pixel enforced.
## Generate pixel payload
## Generate pixel payload
> Generates a pixel payload to use to obtain a "ak\_bmsc" cookie. Note that the payload returned is already url-encoded.
```json
{"openapi":"3.0.0","info":{"title":"AKM Sensor Data and Pixel Payload API","version":"1.0.0"},"servers":[{"url":"https://akm.hypersolutions.co","description":"Main server for sensor and pixel endpoints"}],"paths":{"/pixel":{"post":{"summary":"Generate pixel payload","description":"Generates a pixel payload to use to obtain a \"ak_bmsc\" cookie. Note that the payload returned is already url-encoded.","operationId":"generatePixelPayload","parameters":[{"in":"header","name":"Content-Type","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The Content-Type of the request body"},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"Your API key for authentication"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["htmlVar","scriptVar","userAgent","ip","acceptLanguage"],"properties":{"htmlVar":{"type":"string","description":"The bazadebezolkohpepadr value."},"scriptVar":{"type":"string","description":"The u value that gets sent in the payload. It's hidden somewhere in the first array in the pixel script."},"userAgent":{"type":"string","description":"The userAgent that you're using for your whole session."},"acceptLanguage":{"type":"string","description":"Your accept-language header."},"ip":{"type":"string","description":"The IP that is used to post the sensor data to the target site. You can use /ip to get the IP from a connection. If you are not using proxies, this will be the IPv4 or IPv6 address of your pc."}}}}}},"responses":{"200":{"description":"OK Pixel payload successfully generated","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string","description":"The generated pixel payload (url-encoded)"}}}}}},"400":{"description":"Bad Request Error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}},"403":{"description":"Forbidden Authentication error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}}}}}}}
```
# Incapsula
API reference for the Hyper Solutions Incapsula API: generate reese84 sensor payloads and utmvc cookies for sites behind Imperva / Incapsula.
{% hint style="info" %}
Tip: Use one of the [SDKs](/start-here/readme-1) instead of directly calling the API.
{% endhint %}
This API generates human-like data based on the most recent chrome browser version on Windows. It is recommended to match the latest TLS fingerprint and UserAgent of the newest chrome version when using this API on a site.\
\
The latest chrome useragents can be found [here](https://versionhistory.googleapis.com/v1/chrome/platforms/win/channels/stable/versions/). It is perfectly fine to use only one useragent for all your requests.\
\
Note that all request payloads to this API should be sent as `application/json`.
## Generate reese84 sensor
## Generate reese84 sensor
> Generates sensor data that should be posted in order to acquire valid "reese84" cookies
```json
{"openapi":"3.0.0","info":{"title":"Incapsula Reese84 Sensor and UTMVC Cookie API","version":"1.0.0"},"servers":[{"url":"https://incapsula.hypersolutions.co","description":"Server for reese84 and utmvc endpoints"}],"paths":{"/reese84":{"post":{"summary":"Generate reese84 sensor","description":"Generates sensor data that should be posted in order to acquire valid \"reese84\" cookies","operationId":"generateReese84Sensor","parameters":[{"in":"header","name":"Content-Type","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The Content-Type of the request body"},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"Your API key for authentication"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userAgent","pageUrl","script","scriptUrl","acceptLanguage","ip"],"properties":{"userAgent":{"type":"string","description":"The userAgent that you're using for the entire session"},"pageUrl":{"type":"string","description":"Your page URL."},"script":{"type":"string","description":"The script content as a string."},"scriptUrl":{"type":"string","description":"The script url where you got the script contents from."},"ip":{"type":"string","description":"The IP that is used to post the sensor data to the target site. You can use /ip to get the IP from a connection. If you are not using proxies, this will be the IPv4 or IPv6 address of your pc."},"acceptLanguage":{"type":"string","description":"Your accept-language header."},"pow":{"type":"string","description":"The pow string fetched from incapsula resource."}}}}}},"responses":{"200":{"description":"OK Sensor data successfully generated","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string","description":"The generated sensor data"}}}}}},"400":{"description":"Bad Request Error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}},"403":{"description":"Forbidden Authentication error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}}}}}}}
```
## Generate utmvc cookie
{% hint style="success" %}
Since the request body of the requests will be large, it is highly recommended to apply compression to your request body first. We support the following compression methods: "gzip", "br", "deflate", and "zstd".
Don't forget to set the `content-encoding` header.
{% endhint %}
## Generate utmvc cookie
> Generates a utmvc cookie
```json
{"openapi":"3.0.0","info":{"title":"Incapsula Reese84 Sensor and UTMVC Cookie API","version":"1.0.0"},"servers":[{"url":"https://incapsula.hypersolutions.co","description":"Server for reese84 and utmvc endpoints"}],"paths":{"/utmvc":{"post":{"summary":"Generate utmvc cookie","description":"Generates a utmvc cookie","operationId":"generateUtmvcCookie","parameters":[{"in":"header","name":"Content-Type","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The Content-Type of the request body"},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"Your API key for authentication"},{"in":"header","name":"content-encoding","schema":{"type":"string"},"description":"In case you want to improve latency to our APIs, you can apply encoding to your request payload and set the content-encoding header accordingly."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["script","sessionIds","userAgent"],"properties":{"script":{"type":"string","description":"The JavaScript obtained from doing a GET request to the script path."},"sessionIds":{"type":"array","items":{"type":"string"},"description":"The value of each cookie that has a name that starts with incap_ses_."},"userAgent":{"type":"string","description":"The userAgent that you're using for your whole session."}}}}}},"responses":{"200":{"description":"OK Cookie was generated","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string","description":"The generated cookie value"},"swhanedl":{"type":"string","description":"Parameters for /_Incapsula_Resource?SWHANEDL= request"}}}}}},"400":{"description":"Bad Request Error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}},"403":{"description":"Forbidden Authentication error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}}}}}}}
```
# DataDome
This page shows the API Reference for our DataDome API.
{% hint style="info" %}
Tip: Use one of the [SDKs](/start-here/readme-1) instead of directly calling the API.
{% endhint %}
{% hint style="success" %}
Compress your request body, some payloads are large. We support "gzip", "br", "deflate", and "zstd"; set the `content-encoding` header. More info: [Compression](/api-reference/compression).
{% endhint %}
## Interstitial
Generates the payload for the DataDome **interstitial** challenge (the device-check page solved without a captcha). See the [interstitial guide](/datadome/interstitial).
## Solve interstitial
> Solves the interstitial challenge. After getting this payload, make a POST request to \` with it in the payload and you will receive the datadome cookie in the response. Set this cookie in your cookiejar, you have now successfully solved DataDome interstitial.
```json
{"openapi":"3.0.0","info":{"title":"DataDome Captcha Solving API","version":"1.0.0"},"servers":[{"url":"https://datadome.hypersolutions.co","description":"Server for captcha solving endpoint"}],"paths":{"/interstitial":{"post":{"summary":"Solve interstitial","description":"Solves the interstitial challenge. After getting this payload, make a POST request to `https://geo.captcha-delivery.com/interstitial/` with it in the payload and you will receive the datadome cookie in the response. Set this cookie in your cookiejar, you have now successfully solved DataDome interstitial.","operationId":"solveInterstitial","parameters":[{"in":"header","name":"Content-Type","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The Content-Type of the request body"},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"Your API key for authentication"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userAgent","deviceLink","html","ip","acceptLanguage"],"properties":{"userAgent":{"type":"string","description":"Your chrome UserAgent"},"deviceLink":{"type":"string","description":"The deviceLink you constructed"},"html":{"type":"string","description":"The response body of the GET request to the deviceLink"},"ip":{"type":"string","description":"The IP that is used to post the sensor data to the target site. You can use /ip to get the IP from a connection. If you are not using proxies, this will be the IPv4 or IPv6 address of your pc."},"acceptLanguage":{"type":"string","description":"Your accept-language header"}}}}}},"responses":{"200":{"description":"OK Interstitial solved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string","description":"The payload for POST request to /interstitial/"},"headers":{"type":"object","properties":{"sec-ch-device-memory":{"type":"string"},"sec-ch-ua-mobile":{"type":"string"},"sec-ch-ua-arch":{"type":"string"},"sec-ch-ua-platform":{"type":"string"},"sec-ch-ua-model":{"type":"string"},"sec-ch-ua-full-version-list":{"type":"string"}}}}}}}},"400":{"description":"Bad Request Error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}},"403":{"description":"Forbidden Authentication error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}}}}}}}
```
## Slider
Solves the DataDome **slider** captcha from the challenge images and returns the check URL. See the [slider guide](/datadome/slider-captcha).
## Solve captcha
> Solves the captcha challenge. After getting this URL in the payload, make a GET request to it and you will receive the datadome cookie in the response. Set this cookie in your cookiejar, you have now successfully solved DataDome slider.
```json
{"openapi":"3.0.0","info":{"title":"DataDome Captcha Solving API","version":"1.0.0"},"servers":[{"url":"https://datadome.hypersolutions.co","description":"Server for captcha solving endpoint"}],"paths":{"/slider":{"post":{"summary":"Solve captcha","description":"Solves the captcha challenge. After getting this URL in the payload, make a GET request to it and you will receive the datadome cookie in the response. Set this cookie in your cookiejar, you have now successfully solved DataDome slider.","operationId":"solveCaptcha","parameters":[{"in":"header","name":"Content-Type","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The Content-Type of the request body"},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"Your API key for authentication"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userAgent","deviceLink","html","puzzle","piece","parentUrl","ip","acceptLanguage"],"properties":{"userAgent":{"type":"string","description":"Your chrome UserAgent"},"deviceLink":{"type":"string","description":"The deviceLink you constructed"},"parentUrl":{"type":"string","description":"The parentUrl visible in the form fields"},"html":{"type":"string","description":"The response body of the GET request to the deviceLink"},"puzzle":{"type":"string","description":"The response body from the GET request to the `.jpg` image, base64 encoded."},"piece":{"type":"string","description":"The response body from the GET request to the `.frag.png` image, base64 encoded."},"ip":{"type":"string","description":"The IP that is used to post the sensor data to the target site. You can use /ip to get the IP from a connection. If you are not using proxies, this will be the IPv4 or IPv6 address of your pc."},"acceptLanguage":{"type":"string","description":"Your accept-language header"}}}}}},"responses":{"200":{"description":"OK Captcha solved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string","description":"The URL for captcha verification"},"headers":{"type":"object","properties":{"sec-ch-device-memory":{"type":"string"},"sec-ch-ua-mobile":{"type":"string"},"sec-ch-ua-arch":{"type":"string"},"sec-ch-ua-platform":{"type":"string"},"sec-ch-ua-model":{"type":"string"},"sec-ch-ua-full-version-list":{"type":"string"}}}}}}}},"400":{"description":"Bad Request Error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}},"403":{"description":"Forbidden Authentication error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}}}}}}}
```
## Tags
Generates the telemetry ("tags") payload you post to DataDome's collector to raise your session's trust score. See [Tags](/datadome/tags).
## Solve tags
> Solves the tags challenge.
```json
{"openapi":"3.0.0","info":{"title":"DataDome Captcha Solving API","version":"1.0.0"},"servers":[{"url":"https://datadome.hypersolutions.co","description":"Server for captcha solving endpoint"}],"paths":{"/tags":{"post":{"summary":"Solve tags","description":"Solves the tags challenge.","operationId":"solveTags","parameters":[{"in":"header","name":"Content-Type","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The Content-Type of the request body"},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"Your API key for authentication"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userAgent","ddk","referer","type","ip","acceptLanguage","version"],"properties":{"userAgent":{"type":"string","description":"Your chrome UserAgent"},"ddk":{"type":"string","description":"sitekey, static for each site. parse it from the /js/ payload request from browser"},"cid":{"type":"string","description":"Your current datadome cookie"},"referer":{"type":"string","description":"The referer visible as the referer header in the payload POST"},"type":{"type":"string","description":"First time 'ch', second time 'le'"},"ip":{"type":"string","description":"The IP that is used to post the sensor data to the target site. You can use /ip to get the IP from a connection. If you are not using proxies, this will be the IPv4 or IPv6 address of your pc."},"acceptLanguage":{"type":"string","description":"Your accept-language header"},"version":{"type":"string","description":"The value you will find in the ddv form field"}}}}}},"responses":{"200":{"description":"OK Interstitial solved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string","description":"The payload for POST request"}}}}}},"400":{"description":"Bad Request Error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}},"403":{"description":"Forbidden Authentication error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}}}}}}}
```
# Kasada
API reference for the Hyper Solutions Kasada API: generate x-kpsdk-ct challenge tokens, x-kpsdk-cd challenge data and Vercel BotID x-is-human headers.
{% hint style="info" %}
Tip: Use one of the [SDKs](/start-here/readme-1) instead of directly calling the API.
{% endhint %}
{% hint style="success" %}
Since the request body of the requests will be large, it is highly recommended to apply compression to your request body first. We support the following compression methods: "gzip", "br", "deflate", and "zstd".
Don't forget to set the `content-encoding` header. More info here: [Compression](/api-reference/compression)
{% endhint %}
## Generate challenge token (ct)
## Generate Kasada payload
> Generates a payload to be used in the \`/tl\` POST request
```json
{"openapi":"3.0.0","info":{"title":"Kasada Payload API","version":"1.0.0"},"servers":[{"url":"https://kasada.hypersolutions.co","description":"Kasada payload generation server"}],"paths":{"/payload":{"post":{"summary":"Generate Kasada payload","description":"Generates a payload to be used in the `/tl` POST request","operationId":"generateKasadaPayload","parameters":[{"in":"header","name":"Content-Type","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The Content-Type of the request body"},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"Your API key for authentication"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userAgent","script","ipsLink","ip","acceptLanguage"],"properties":{"userAgent":{"type":"string","description":"The User-Agent string of the browser"},"script":{"type":"string","description":"The script content as a string."},"ipsLink":{"type":"string","description":"The IPS link obtained from the Kasada block page"},"acceptLanguage":{"type":"string","description":"Your accept-language header."},"ip":{"type":"string","description":"The IP that is used to post the sensor data to the target site. You can use /ip to get the IP from a connection. If you are not using proxies, this will be the IPv4 or IPv6 address of your pc."}}}}}},"responses":{"200":{"description":"OK Payload successfully generated","content":{"application/json":{"schema":{"type":"object","properties":{"headers":{"type":"object","properties":{}},"payload":{"type":"string","description":"The generated Kasada protection payload"}}}}}},"400":{"description":"Bad Request Error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}},"403":{"description":"Forbidden Authentication error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}}}}}}}
```
## Generate challenge data (cd)
## Get challenge POW
> Retrieves a challenge POW (\`x-kpsdk-cd\`)
```json
{"openapi":"3.0.0","info":{"title":"Kasada Payload API","version":"1.0.0"},"servers":[{"url":"https://kasada.hypersolutions.co","description":"Kasada payload generation server"}],"paths":{"/cd":{"post":{"summary":"Get challenge POW","description":"Retrieves a challenge POW (`x-kpsdk-cd`)","parameters":[{"in":"header","name":"Content-Type","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The Content-Type of the request body"},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"Your API key for authentication"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["st","ct","domain"],"properties":{"st":{"type":"integer","description":"Timestamp retrieved from the `x-kpsdk-st` response header of the `/tl` request"},"ct":{"type":"string","description":"The latest `x-kpsdk-ct` value. It starts as the `x-kpsdk-ct` from the `/tl` response but is refreshed whenever a later response returns a new `x-kpsdk-ct` header. Always send the most recent value, a stale `ct` will fail."},"workTime":{"type":"integer","description":"Custom workTime value if you are generating POWs in advance"},"fc":{"type":"string","description":"Only used on specific sites. Inquire if your site makes a GET request to /mfc."},"domain":{"type":"string","description":"The domain of the p.js url"}}}}}},"responses":{"200":{"description":"OK POW successfully generated","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string","description":"The cd value"}}}}}},"400":{"description":"Bad Request Error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}},"403":{"description":"Forbidden Authentication error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}}}}}}}
```
## Generate Vercel BotID (x-is-human)
## Generate x-is-human header
> Generates a x-is-human header to be used on endpoints protected by Vercel BotID
```json
{"openapi":"3.0.0","info":{"title":"Kasada Payload API","version":"1.0.0"},"servers":[{"url":"https://kasada.hypersolutions.co","description":"Kasada payload generation server"}],"paths":{"/botid":{"post":{"summary":"Generate x-is-human header","description":"Generates a x-is-human header to be used on endpoints protected by Vercel BotID","parameters":[{"in":"header","name":"Content-Type","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The Content-Type of the request body"},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"Your API key for authentication"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userAgent","script","ip","acceptLanguage"],"properties":{"userAgent":{"type":"string","description":"The User-Agent string of the browser"},"script":{"type":"string","description":"The script content as a string."},"acceptLanguage":{"type":"string","description":"Your accept-language header."},"ip":{"type":"string","description":"The IP that is used to interact with the target site. You can use /ip to get the IP from a connection. If you are not using proxies, this will be the IPv4 or IPv6 address of your pc."}}}}}},"responses":{"200":{"description":"OK Payload successfully generated","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string","description":"The generated x-is-human header value"}}}}}},"400":{"description":"Bad Request Error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}},"403":{"description":"Forbidden Authentication error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}}}}}}}
```
# Usage & Status Codes
Check your remaining quota with the Usage API, and understand the HTTP status codes the Hyper Solutions API returns.
### Checking your usage
Use the Usage API to monitor your remaining quota and consumption:
## Get usage statistics
> Retrieves detailed usage statistics for all products and plans associated with the API key
```json
{"openapi":"3.0.0","info":{"title":"JustHyped Usage Statistics API","version":"1.0.0"},"servers":[{"url":"https://api.hypersolutions.co","description":"Main server for usage statistics"}],"paths":{"/usage":{"get":{"summary":"Get usage statistics","description":"Retrieves detailed usage statistics for all products and plans associated with the API key","operationId":"getUsageStatistics","parameters":[{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"Your API key for authentication"}],"responses":{"200":{"description":"OK Usage statistics successfully retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"balanceEuro":{"type":"number","format":"float","description":"Current balance in Euros"},"plans":{"type":"array","description":"List of plans with their usage statistics","items":{"type":"object","properties":{"expiresAt":{"type":"string","format":"date-time","description":"ISO 8601 date when this plan expires"},"requestsUsed":{"type":"integer","description":"Number of requests used from this plan"},"requestsQuota":{"type":"integer","description":"Total number of requests allocated to this plan"},"requestsRemaining":{"type":"integer","description":"Number of requests remaining (quota - used)"},"product":{"type":"string","description":"Name of the product (e.g., \"akamai\", \"datadome\", \"incapsula\")"},"numRequests":{"type":"integer","description":"Total number of requests for this plan"}}}}}}}}},"401":{"description":"Unauthorized - API key is missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}},"403":{"description":"Forbidden - API key is disabled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}}}}}}}
```
### Status codes
These are the responses the Hyper Solutions API itself returns:
| Status | Means | Fix |
| ------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | Payload generated successfully | Replay the returned payload and `headers` object on the target |
| `401` | Missing or invalid API key | Check the `x-api-key` header and your key at [hypersolutions.co/keys](https://hypersolutions.co/keys). See [Authentication](/api-reference/authentication) |
{% hint style="info" %}
Compress your request bodies, some sensor payloads are large. The SDKs auto-compress bodies over 1000 bytes. See [Compression](/api-reference/compression).
{% endhint %}
# Compression
Our API supports multiple compression algorithms to improve performance and reduce bandwidth usage.
### Supported Algorithms
* **gzip** - Widely supported, good general-purpose compression
* **deflate** - Lightweight compression with broad compatibility
* **brotli** - Modern algorithm with excellent compression ratio
* **zstd** - Recommended for best overall performance
### Using Compression
#### Request Compression
Set the `Content-Encoding` header with your chosen algorithm:
```
Content-Encoding: zstd
```
#### Response Compression
Set the `Accept-Encoding` header in your request:
```
Accept-Encoding: zstd, br, gzip
```
### Recommendations
* **Best Performance**: zstd provides the optimal balance of compression ratio and speed
* **Highest Compatibility**: gzip is supported by virtually all HTTP clients
### SDK Support
* **Go SDK (v1.7.2+)**: Uses zstd compression by default
* **Python/JavaScript SDKs**: Use gzip compression by default
### Performance Comparison
| Algorithm | Speed | Compression Ratio | Use Case |
| --------- | ------ | ----------------- | ---------------------------- |
| zstd | Fast | Very good | Recommended for most cases |
| brotli | Slow | Excellent | When bandwidth is limited |
| gzip | Medium | Good | When compatibility is needed |
| deflate | Medium | Fair | Lightweight option |
For implementation help, contact our support team.
# User Agents
This page explains the supported user agent configurations and how to maintain them for optimal performance across all Hyper Solutions APIs.
### Overview
Hyper Solutions APIs support two user agent variants for all bot protection bypass services (Akamai, DataDome, Incapsula, and Kasada).
### Supported User Agents
{% hint style="info" %}
Read "Chrome Version Management" to understand what to replace XXX with in these useragents
{% endhint %}
#### Windows User Agent (Recommended)
```
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/XXX.0.0.0 Safari/537.36
```
**Windows remains our recommended default.**
#### macOS User Agent
```
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/XXX.0.0.0 Safari/537.36
```
macOS user agent support is available for specific use cases where Windows user agents may face temporary restrictions or when targeting sites with macOS-specific requirements.
### Chrome Version Management
#### Current Version
At the time of writing, Chrome stable version is **149** (6/17/2026). Your user agent string must reflect the current stable Chrome version to avoid detection.
#### Monitoring Chrome Releases
Track Chrome stable releases at:
Chrome follows a roughly 4-week release cycle for stable versions. Monitor this schedule to stay informed about upcoming releases.
#### Update Timeline
**Recommended update strategy:**
1. Monitor the Chrome release schedule for new stable versions
2. Wait 3-7 days after the stable release date
3. Update your user agent string to the new version
4. Update all related headers accordingly
**Why wait 3-7 days?**
* Allows time for real users to naturally update their browsers
* Avoids being among the very first to use a new version
* Ensures stability and widespread adoption of the release
#### Required Updates
When updating to a new Chrome version, you must update:
1. **User Agent String**: Update the version number (e.g., `148.0.0.0` → `149.0.0.0`)
2. **sec-ch-ua Header**: Update to match the new version
```
"Google Chrome";v="149", "Chromium";v="149", "Not)A;Brand";v="24"
```
3. **sec-ch-ua-platform Header**:
* Windows: `"Windows"`
* macOS: `"macOS"`
**Critical:** All version numbers must be consistent across your entire request configuration. Mismatched versions are a strong indicator of automated traffic.
### Best Practices
#### Version Consistency
* **Keep header versions consistent**: All Chrome version references in your headers (User Agent, sec-ch-ua, etc.) must match each other. Your TLS fingerprint should also match when possible. See Troubleshooting for the narrow case where a slightly older TLS profile is acceptable.
* **Update completely**: When upgrading, update all headers simultaneously
* **Test after updates**: Verify your configuration works after version changes
#### Platform Consistency
* **Stick to one platform**: Don't switch between Windows and macOS mid-session
* **Match all platform indicators**: Ensure all platform-specific headers align
* **Maintain throughout session**: Use the same configuration for all requests in a session
#### Monitoring and Maintenance
* **Set version alerts**: Create reminders for Chrome release dates
* **Test in advance**: Prepare updated configurations before deploying
* **Monitor success rates**: Track performance after version updates
* **Document your configuration**: Keep records of what works for your use cases
### Troubleshooting
#### Detection Issues After Chrome Update
If you experience increased detection after a Chrome release:
* Verify you've updated all version-dependent headers
* Ensure version numbers are consistent across all headers
* Check that you're not updating too early (wait 3-7 days)
* Confirm your TLS fingerprint matches the Chrome version
#### Platform-Specific Blocks
If one platform gets blocked:
* Consider switching to the alternate platform temporarily
* Contact support for guidance on your specific situation
* Monitor if the block is temporary or permanent
* Ensure all platform-specific headers are correctly configured
#### **TLS Client Missing a Profile for the Latest Chrome**
If your TLS client library doesn't yet ship a fingerprint profile for the current Chrome stable version, you can usually fall back to the most recent available profile (e.g., use a Chrome 147 or 148 TLS profile while sending a Chrome 149 user agent). Chrome's TLS ClientHello does not change on every release, so older profiles often remain viable across several versions.
**This is a fallback, not a recommended steady state.** Use it only when:
* Your TLS library has not yet released a matching profile, and
* You've verified the configuration still passes against your target
**Caveats:**
* Some Chrome releases *do* introduce meaningful TLS changes. After releases like these, an older profile will be detected.
* Test your success rate before and after applying this fallback. If you see a drop, your target is fingerprinting at a level the older profile no longer matches.
* Update to a matching profile as soon as your TLS library publishes one. Don't treat this as a long-term configuration.
# Claude Code plugin
The official Hyper Solutions plugin for Claude Code: integrate the Akamai, Incapsula, DataDome, and Kasada APIs and debug blocked requests with live traffic capture or HAR analysis.
The Hyper Solutions plugin teaches Claude Code how our API actually works, so your agent can integrate the SDKs, generate sensors, cookies, and tokens for all four vendors, and find the fingerprint mistake behind a blocked request, without you copy-pasting documentation into the chat.
### Installation
Run these inside Claude Code:
{% code overflow="wrap" %}
```
/plugin marketplace add Hyper-Solutions/hypersolutions-claude-code
/plugin install hypersolutions@hypersolutions
```
{% endcode %}
### What's included
* **The `hypersolutions` skill**: integration knowledge for Akamai (sensor, sec-cpt, SBSD, pixel), Incapsula (reese84, utmvc), DataDome (interstitial, slider, tags), and Kasada (payload, POW, Vercel BotID), across the Go, Python, and JS/TS SDKs or raw REST. It also knows the non-negotiables: browser-grade TLS clients, exact header order, session consistency, and sticky proxies.
* **The powhttp MCP server**: reads live captures from [powhttp](/request-based-basics/installing-powhttp): true header order, TLS fingerprint, and HTTP/2 stream details from the requests your code really sent. Install powhttp and start it under **Settings → MCP Server**. For a full walkthrough of capturing and debugging with powhttp, see the [powhttp guide](https://hypersolutions.co/blog/how-to-use-powhttp-web-scraping).
* **The har-analyzer MCP server**: analyzes an exported HAR against our maintained rule set: header order and casing, `sec-ch-ua` and Chrome version mismatches, duplicate cookies, pseudo-header order, and per-vendor mistakes.
### Authentication
* The **har-analyzer** signs in with your Hyper Solutions account via OAuth. Run `/mcp` in Claude Code and authenticate in the browser on first use.
* Actually calling the Hyper Solutions API requires an [API key](https://hypersolutions.co/keys). See [Authentication](/api-reference/authentication).
{% hint style="info" %}
To record a HAR file for analysis, see [Recording HAR files](/request-based-basics/recording-har-files-for-harvey).
{% endhint %}
### Example prompts
* "Help me set up the Akamai sensor flow in Python with tls-client."
* "My DataDome slider solve returns 403. Capture my script with powhttp and tell me what's wrong."
* "Analyze this HAR and find why I'm getting blocked."
* "Why is my `_abck` cookie never becoming valid?"
{% hint style="info" %}
Watch the plugin build a full request-based scraper from a single prompt in [One prompt, a full airline scraper](https://hypersolutions.co/blog/claude-code-plugin-ai-scraping).
{% endhint %}
{% embed url="" %}
# Codex plugin
The official Hyper Solutions plugin for OpenAI Codex: integrate the Akamai, Incapsula, DataDome, and Kasada APIs and debug blocked requests with live traffic capture or HAR analysis.
The Hyper Solutions plugin teaches Codex how our API actually works, so your agent can integrate the SDKs, generate sensors, cookies, and tokens for all four vendors, and find the fingerprint mistake behind a blocked request, without you copy-pasting documentation into the chat.
### Installation
With the [Codex CLI](https://github.com/openai/codex) installed:
{% code overflow="wrap" %}
```
codex plugin marketplace add Hyper-Solutions/hypersolutions-codex
codex plugin add hypersolutions@hypersolutions
codex mcp login har-analyzer
```
{% endcode %}
The last command signs the HAR analyzer in against your Hyper Solutions account (also available under **Settings → MCP servers → From plugins → Authenticate**).
### What's included
* **The `hypersolutions` skill**: integration knowledge for Akamai (sensor, sec-cpt, SBSD, pixel), Incapsula (reese84, utmvc), DataDome (interstitial, slider, tags), and Kasada (payload, POW, Vercel BotID), across the Go, Python, and JS/TS SDKs or raw REST. It also knows the non-negotiables: browser-grade TLS clients, exact header order, session consistency, and sticky proxies.
* **The powhttp MCP server**: reads live captures from [powhttp](/request-based-basics/installing-powhttp): true header order, TLS fingerprint, and HTTP/2 stream details from the requests your code really sent. Install powhttp and start it under **Settings → MCP Server**. For a full walkthrough of capturing and debugging with powhttp, see the [powhttp guide](https://hypersolutions.co/blog/how-to-use-powhttp-web-scraping).
* **The har-analyzer MCP server**: analyzes an exported HAR against our maintained rule set: header order and casing, `sec-ch-ua` and Chrome version mismatches, duplicate cookies, pseudo-header order, and per-vendor mistakes.
### Authentication
* The **har-analyzer** signs in with your Hyper Solutions account via OAuth (`codex mcp login har-analyzer`).
* Actually calling the Hyper Solutions API requires an [API key](https://hypersolutions.co/keys). See [Authentication](/api-reference/authentication).
{% hint style="info" %}
To record a HAR file for analysis, see [Recording HAR files](/request-based-basics/recording-har-files-for-harvey).
{% endhint %}
### Example prompts
* "Help me set up the Akamai sensor flow in Python with tls-client."
* "My DataDome slider solve returns 403. Capture my script with powhttp and tell me what's wrong."
* "Analyze this HAR and find why I'm getting blocked."
* "Why is my `_abck` cookie never becoming valid?"
{% embed url="" %}