SDKs overview

Botd provides tools and libraries primarily focused on integrating its bot detection capabilities into web applications and server-side environments. The core of the Botd offering for developers revolves around a client-side JavaScript agent and a server-side API. The JavaScript agent is designed for straightforward integration into web pages, where it collects signals to identify automated traffic. These signals are then processed by Botd's backend, which returns a detection result. Developers can then use these results via the server-side API to implement custom logic for blocking or mitigating bot activity, such as preventing credential stuffing, content scraping, or spam registrations, as described in the Botd official documentation.

The architecture is designed to allow developers to leverage Botd's detection without requiring extensive changes to their existing backend infrastructure. The client-side agent focuses on data collection, while the server-side API provides the mechanism for applications to query detection results and enforce policies. This separation enables flexibility in how bot mitigation strategies are implemented, from simple CAPTCHA challenges to more sophisticated rate-limiting or access control mechanisms. The Botd API reference details the available endpoints and data structures for integration.

Official SDKs by language

Botd's official SDK support is primarily concentrated on JavaScript, which facilitates client-side integration of its detection agent. This agent is instrumental in gathering the necessary telemetry from user browsers to identify automated traffic patterns. While a full server-side SDK in various languages is not explicitly listed as a separate package, the Botd service provides a comprehensive API that can be consumed by any language capable of making HTTP requests. This approach allows developers to integrate Botd's detection signals into their server-side applications using standard HTTP client libraries available in languages like Python, Ruby, Java, Go, and Node.js.

The JavaScript agent is maintained directly by Fingerprint, the company behind Botd, ensuring compatibility and ongoing support. Its primary function is to initialize the bot detection process within a web browser, collect relevant data, and transmit it to the Botd service for analysis. The result of this analysis, including a unique request identifier, can then be used by the developer's server-side application to query the Botd API for detailed bot detection outcomes. This design pattern aligns with common practices for integrating security services that require client-side data collection, similar to how analytics or fraud detection services operate.

Official JavaScript SDK

The official JavaScript SDK for Botd is the primary method for integrating client-side bot detection. It is designed to be easily embedded into web applications, where it operates in the background to identify and report automated behavior. This SDK handles the complexities of browser fingerprinting and signal collection, transmitting data securely to the Botd service. The output of the JavaScript agent is a unique request ID, which is then used to query the Botd Server API for a comprehensive bot detection result.

The following table summarizes the key details of the official Botd JavaScript SDK:

Language Package Name Installation Command Maturity
JavaScript @botd/agent npm install @botd/agent or yarn add @botd/agent Stable

Installation

Installing the Botd JavaScript agent typically involves using a package manager like npm or yarn, or by including it directly via a CDN. The choice of installation method depends on the project's setup and deployment strategy. For modern web development workflows that utilize bundlers like Webpack or Rollup, installing via npm or yarn is the recommended approach, as it allows for better dependency management and tree shaking.

Via npm or yarn

For projects managed with npm or yarn, the Botd agent can be added as a dependency using the following commands:

npm install @botd/agent
# or
yarn add @botd/agent

Once installed, the agent can be imported into your JavaScript modules. This method is suitable for single-page applications (SPAs) and other client-side rendered applications where JavaScript modules are bundled.

Via CDN

Alternatively, for simpler setups or traditional multi-page applications, the Botd agent can be included directly in your HTML using a Content Delivery Network (CDN). This method does not require a build step and can be beneficial for quick integration or environments where a package manager is not used.

<script src="https://cdn.botd.io/botd.min.js"></script>

When using the CDN approach, the Botd global object becomes available in the browser's global scope, allowing for direct initialization and usage within inline scripts or other loaded JavaScript files. The Botd quickstart guide provides examples for both installation methods.

Quickstart example

This quickstart example demonstrates how to integrate the Botd JavaScript agent into a web page and retrieve a bot detection result. The process involves initializing the agent, waiting for it to collect signals, and then using the returned request ID to query the Botd server-side API. This example focuses on the client-side integration and assumes a server-side component will handle the API call using the requestId.

Client-side JavaScript integration

First, ensure the @botd/agent library is installed (via npm/yarn) or included via CDN. The following JavaScript code snippet shows how to initialize the agent and obtain a unique request identifier:

import * as Botd from '@botd/agent';

async function initializeBotd() {
  try {
    const botdAgent = await Botd.load();
    const result = await botdAgent.get();

    console.log('Botd Request ID:', result.requestId);
    console.log('Botd Raw Response:', result.botd);

    // Send the requestId to your server-side endpoint
    // for further processing and API lookup.
    await fetch('/api/check-bot', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ requestId: result.requestId }),
    });

  } catch (error) {
    console.error('Error initializing Botd:', error);
  }
}

initializeBotd();

In this client-side code:

  • Botd.load() asynchronously loads and initializes the Botd agent.
  • botdAgent.get() performs the bot detection, collecting signals and returning a result object.
  • The requestId is a unique identifier for the detection event, which is crucial for server-side lookup.
  • The fetch call demonstrates how to send this requestId to a backend endpoint (e.g., /api/check-bot) for server-side validation.

Server-side API lookup (conceptual)

On your server, you would receive the requestId from the client. You would then use this ID to make a request to the Botd Server API to retrieve the detailed bot detection results. This example illustrates a conceptual Node.js server-side endpoint, but the principle applies to any backend language.

// Example Node.js (Express) server-side endpoint
const express = require('express');
const fetch = require('node-fetch'); // or axios, etc.
const app = express();
app.use(express.json());

app.post('/api/check-bot', async (req, res) => {
  const { requestId } = req.body;

  if (!requestId) {
    return res.status(400).json({ error: 'requestId is required' });
  }

  try {
    // Replace YOUR_BOTD_API_KEY with your actual Botd Secret API Key
    const botdApiKey = process.env.BOTD_API_KEY; 
    const botdApiUrl = `https://api.botd.io/api/v1/results/${requestId}?token=${botdApiKey}`;

    const response = await fetch(botdApiUrl);
    const detectionResult = await response.json();

    if (!response.ok) {
      console.error('Botd API error:', detectionResult);
      return res.status(response.status).json({ error: detectionResult.message });
    }

    console.log('Server-side Botd result:', detectionResult);

    // Implement your blocking logic based on detectionResult
    // For example, if (detectionResult.bot.detected) { /* block or challenge */ }

    res.json({ success: true, botdResult: detectionResult });

  } catch (error) {
    console.error('Server error during Botd lookup:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

This server-side example demonstrates:

  • Receiving the requestId from the client.
  • Constructing a request to the Botd Server API using the requestId and a secret API key.
  • Parsing the response from Botd, which contains detailed information about whether the request originated from a bot.
  • The point where custom logic can be applied to mitigate or block bot traffic based on the detectionResult.

For more detailed API parameters and response structures, refer to the Botd Server API documentation. Implementing robust bot detection often involves combining client-side signals with server-side enforcement, as highlighted by best practices in Cloudflare's bot management strategies.

Community libraries

As of 2026-05-29, the primary focus for Botd integration remains its official JavaScript agent for client-side detection and its well-documented Server API for backend processing. While the Botd ecosystem is relatively new (founded in 2022), the modular nature of its API allows for integration using standard HTTP client libraries available in virtually any programming language. This means that developers can build their own wrappers or helper functions to interact with the Botd API in their preferred language without the need for an official, language-specific SDK.

Currently, there are no widely recognized or officially endorsed community-contributed SDKs or client libraries for Botd beyond the core JavaScript agent. This is common for newer API-first services where the HTTP API itself serves as the universal interface. Developers are encouraged to consult the Botd API reference to implement custom integrations or contribute to the community by sharing their own wrapper libraries. The Botd team primarily focuses on maintaining the core detection engine and the official JavaScript client, which is critical for accurate signal collection from browsers.

The absence of numerous community SDKs does not impede integration, as the API follows standard RESTful principles, making it accessible with common HTTP request libraries. For example, a Python developer might use the requests library, a Java developer might use HttpClient, and a Go developer might use the built-in net/http package to interact with the Botd API. This approach offers flexibility and avoids dependency on third-party community libraries that may not be officially supported or regularly updated.