> For the complete documentation index, see [llms.txt](https://docs.hypersolutions.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hypersolutions.co/api-reference/kasada.md).

# Kasada API Reference

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.md) 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".<br>

Don't forget to set the `content-encoding` header. More info here: [Compression](/api-reference/compression.md)
{% 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."},"strict":{"type":"boolean","default":false,"description":"Optional. When true, a script with a signal the API cannot identify yet is refused with a 500 \"Unidentified signals in script; refusing payload because strict was set\" instead of returning a payload with that signal filled in."}}}}}},"responses":{"200":{"description":"OK Payload successfully generated","content":{"application/json":{"schema":{"type":"object","properties":{"headers":{"type":"object","description":"The x-kpsdk-* headers to send on the protected request.","properties":{}},"payload":{"type":"string","description":"The generated Kasada protection payload"},"clientHints":{"description":"The client hints for the device the payload describes. Kasada returns them under clientHints because headers holds the x-kpsdk-* headers. Omitted for mobile user agents.","allOf":[{"$ref":"#/components/schemas/ClientHints"}]}}}}}},"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"}}}}}}}}}},"components":{"schemas":{"ClientHints":{"type":"object","description":"The Accept-CH client hints for the device the payload was generated for. Keys are lowercase header names, values are ready to send verbatim (already quoted where the header needs it). Send sec-ch-ua, sec-ch-ua-mobile and sec-ch-ua-platform on every request; send any other hint only if the origin's Accept-CH header lists it. Brands and full versions come from your userAgent, everything else from the device. See the Client Hints page for the full rules.","properties":{"sec-ch-ua":{"type":"string"},"sec-ch-ua-mobile":{"type":"string"},"sec-ch-ua-platform":{"type":"string"},"sec-ch-ua-arch":{"type":"string"},"sec-ch-ua-bitness":{"type":"string"},"sec-ch-ua-model":{"type":"string"},"sec-ch-ua-platform-version":{"type":"string"},"sec-ch-ua-full-version":{"type":"string"},"sec-ch-ua-full-version-list":{"type":"string"},"sec-ch-ua-wow64":{"type":"string"},"sec-ch-ua-form-factors":{"type":"string"},"sec-ch-device-memory":{"type":"string"},"sec-ch-dpr":{"type":"string"},"sec-ch-viewport-width":{"type":"string"},"sec-ch-viewport-height":{"type":"string"},"device-memory":{"type":"string"},"dpr":{"type":"string"},"viewport-width":{"type":"string"},"ect":{"type":"string"},"rtt":{"type":"string"},"downlink":{"type":"string"},"sec-ch-prefers-color-scheme":{"type":"string"},"sec-ch-prefers-reduced-motion":{"type":"string"},"sec-ch-prefers-reduced-transparency":{"type":"string"}}}}}}
```

### The strict field

`/payload` accepts an optional boolean `strict` (default `false`).

Kasada changes the signals its `ips.js` script collects. When a script contains a signal the API cannot identify yet, the API normally fills that slot with the script's own literal value and returns the payload. With `"strict": true` it refuses instead, with HTTP `500` and:

```json
{"error": "Unidentified signals in script; refusing payload because strict was set"}
```

Use it when you would rather retry later or fall back to another route than post a payload with a slot the API could not read. The SDKs only send the field when it is set: Go `KasadaPayloadInput.Strict` (`v4.0.0`), Python `KasadaPayloadInput(strict=True)` (`4.0.0`), JS / TS the last `KasadaPayloadInput` argument (`5.0.0`).

### Mobile device header (dv)

For the iOS app flow the request accepts an optional `dv` string: the `x-kpsdk-dv` header you send to the site, exactly as sent. The payload is then generated on a device with the screen of the model it names and the iOS version it names. It is ignored for a desktop user-agent, and a value that does not decode fails with `invalid dv`. See [Mobile User-Agent](/k4sada/mobile-user-agent.md#the-x-kpsdk-dv-header).

### Client hints

Next to `payload` and the `x-kpsdk-*` values in `headers`, `/payload` returns a `clientHints` object with the Accept-CH client hints for the device. Unlike the `x-kpsdk-*` headers, send only the hints the site asks for. See [Client Hints](/start-here/client-hints.md).

## Get the x-kpsdk-v value

Reads the `x-kpsdk-v` value from a site's `p.js`, for the `/fp` request and the `x-kpsdk-v` header. Send `pageUrl` (the page that loaded `p.js`) and `script` (the `p.js` body). This request does not count towards your usage. See [Flow 2: Fingerprint Endpoint](/k4sada/flow-2-fingerprint-endpoint.md).

## Get the x-kpsdk-v value

> Reads the x-kpsdk-v value from a site's p.js. Send the returned value verbatim on the \`/fp\` request and in the \`x-kpsdk-v\` header. This request does not count towards your usage.

```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":{"/version":{"post":{"summary":"Get the x-kpsdk-v value","description":"Reads the x-kpsdk-v value from a site's p.js. Send the returned value verbatim on the `/fp` request and in the `x-kpsdk-v` header. This request does not count towards your usage.","operationId":"getKasadaVersion","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":["pageUrl","script"],"properties":{"pageUrl":{"type":"string","description":"The URL of the page that loaded p.js."},"script":{"type":"string","description":"The p.js script body, fetched with the same client and headers you use for the site."}}}}}},"responses":{"200":{"description":"OK Version successfully read","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string","description":"The x-kpsdk-v value, for example j-1.2.797"}}}}}},"400":{"description":"Bad Request Error occurred, for example a script that does not parse (such as ips.js instead of p.js)","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"}}}}}},"500":{"description":"Internal Server Error, for example a p.js the API cannot read a version from","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"}}}}}}}}}}}
```
