> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roolink.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate challenge payload

> Builds the body and headers for the Kasada `/tl` request from the challenge script (`ips.js`)
your session fetched. Roolink selects a real browser profile that matches `userAgent` and
`language`, so send the exact User-Agent and Accept-Language your session uses on the site.

`referer` is the page URL for both Kasada flows. For versioned fingerprint scripts Roolink
derives the `/fp` frame URL from `ipsUrl`; for initial-block scripts `referer` is the
top-level page. Both must be absolute HTTP(S) URLs without credentials.

Post `payload` (base64-decoded) to the site's `/tl` endpoint with the returned `headers`.
Counts against your Kasada plan.




## OpenAPI

````yaml api-reference/openapi/kasada.yaml POST /api/v1/payload
openapi: 3.1.0
info:
  title: Roolink Kasada API
  version: 1.0.0
  description: >
    Generates the payloads Kasada expects from a browser: the challenge payload
    and `x-kpsdk-*`

    headers for the `/tl` request, a fresh `x-kpsdk-cd` proof of work for each
    protected request,

    and the `x-is-human` header for endpoints protected by Vercel BotID.


    Every request is `POST` with a JSON body and returns JSON. Errors carry
    `{"code", "error"}`.
servers:
  - url: https://ksd.roolink.io
security:
  - ApiKey: []
paths:
  /api/v1/payload:
    post:
      summary: Generate challenge payload
      description: >
        Builds the body and headers for the Kasada `/tl` request from the
        challenge script (`ips.js`)

        your session fetched. Roolink selects a real browser profile that
        matches `userAgent` and

        `language`, so send the exact User-Agent and Accept-Language your
        session uses on the site.


        `referer` is the page URL for both Kasada flows. For versioned
        fingerprint scripts Roolink

        derives the `/fp` frame URL from `ipsUrl`; for initial-block scripts
        `referer` is the

        top-level page. Both must be absolute HTTP(S) URLs without credentials.


        Post `payload` (base64-decoded) to the site's `/tl` endpoint with the
        returned `headers`.

        Counts against your Kasada plan.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - script
                - ipsUrl
                - language
                - referer
                - userAgent
              properties:
                script:
                  type: string
                  description: >-
                    Contents of the `ips.js` challenge script, exactly as
                    fetched.
                ipsUrl:
                  type: string
                  format: uri
                  description: >-
                    Absolute URL the script was fetched from, including its
                    query string.
                language:
                  type: string
                  description: Your `Accept-Language`, for example `en-US`.
                referer:
                  type: string
                  format: uri
                  description: Absolute URL of the page that loaded the script.
                userAgent:
                  type: string
                  description: The exact User-Agent your session sends to the site.
            example:
              script: (function(){ ... })();
              ipsUrl: >-
                https://www.example.com/7c1e4a2b-93d0-4f6e-8b21-5a0c9d3e7f14/b58f0c61-2e7a-4d93-9c05-e1a47b8d2f60/ips.js?x-kpsdk-v=j-1.1.0
              language: en-US
              referer: https://www.example.com/
              userAgent: >-
                Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
                (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36
      responses:
        '200':
          description: >-
            Payload generated. Decode `payload` from base64 and post it to `/tl`
            with `headers`.
          content:
            application/json:
              schema:
                type: object
                required:
                  - headers
                  - payload
                properties:
                  headers:
                    type: object
                    additionalProperties:
                      type: string
                    description: >-
                      Headers to send with the `/tl` request, including
                      `x-kpsdk-ct`, `x-kpsdk-v` and any other `x-kpsdk-*` the
                      script expects.
                  payload:
                    type: string
                    contentEncoding: base64
                    description: The request body for `/tl`, base64-encoded.
        '400':
          $ref: '#/components/responses/InvalidJson'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/TooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMedia'
        '422':
          description: >
            `invalid_request` (a required field is missing or a URL is not
            absolute), `device_not_found` or

            `invalid_device` (no browser profile for this User-Agent),
            `unsupported_fields` or

            `invalid_script` (Roolink cannot build a payload for this challenge
            script).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/Quota'
        '503':
          $ref: '#/components/responses/Overloaded'
components:
  responses:
    InvalidJson:
      description: >-
        `invalid_json`: the body is not one JSON object, or contains a field
        this endpoint does not accept.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: The `x-api-key` header is missing or the key is invalid.
    TooLarge:
      description: '`body_too_large`: the request body exceeds 8 MiB.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnsupportedMedia:
      description: '`unsupported_media_type`: `Content-Type` must be `application/json`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Quota:
      description: Kasada is not enabled on this key or its quota is exhausted.
    Overloaded:
      description: >-
        `overloaded`: the service is at capacity. Retry after the `Retry-After`
        delay.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
        - code
        - error
      properties:
        code:
          type: string
          description: Machine-readable error code.
        error:
          type: string
          description: Human-readable message.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.