Introduction

Botect scores every visitor session for bot-likelihood from behavioral, JS, and heuristic signals — then tells your backend whether to allow, challenge, or block, in under 50 ms.

Botect is a bot-detection API. A lightweight browser SDK streams privacy-safe interaction signals to Botect; Botect scores each session for how human it looks; and your backend reads a single verdict — allow, challenge, or block — from the edge of every request you care about.

There are two halves to the API:

The data plane — high-volume, latency-critical, and never rate-limited. Your SDK posts signals to POST /v1/events; your backend reads decisions from GET /v1/sessions/{token}/verdict.
The control plane — owner-facing configuration. Enable scoring on a project, tune toggles and the bot threshold, and compose custom rules.

Key features

Session scoring

A 1–99 bot-likelihood score per session from three independent engines, combined by strongest evidence.

Behavioral signals

Mouse entropy, scroll velocity, visibility, and input timing — the core differentiator, not just headers.

Fast verdicts

Redis-cached reads under 50 ms p99. Your site never blocks on a Botect lookup — the verdict fails open.

Observe first

Enforcement is off by default. Watch real traffic, then opt into challenge or block when you're ready.

Custom rules

A safe, composable expression grammar over every signal field. Compiled to an AST, never eval'd.

Verified bots

Real search and AI crawlers are recognized and allowed — never blocked for looking automated.

How it works

Enable scoring

Turn scoring on for a project and receive a site key (pk_…) and a private key (sk_…).

Collect signals

The browser SDK posts interaction batches to POST /v1/events with your site key. Ingest never waits on scoring.

Score asynchronously

Botect combines heuristic, JS-detection, and behavioral signals into a score, band, and reasons — off the request path.

Read the verdict

Your backend calls GET /v1/sessions/{token}/verdict with your private key and gets an action: allow, challenge, or block.

Decide

Toggles and your custom rules resolve the action. Unknown or not-yet-scored sessions fail open to allow.

Conventions

Base URL: https://api.botect.ai/v1
Data-plane auth: site key for ingest (X-Botect-Site-Key: pk_…), private key for verdicts (Authorization: Bearer sk_…)
Control-plane auth: an account API token (Authorization: Bearer <token>)
Format: JSON in, JSON out (Content-Type: application/json on POST/PUT bodies)
HTTPS only: plain HTTP is not accepted
Versioning: the URL prefix is v1. Breaking changes ship behind a new version
No client rate limiting on the data plane — volume is governed by your monthly quota, not by 429s

Explore Botect

Quickstart

Enable scoring and read your first verdict in a few minutes.

Authentication

The three credential types and where each one is used.

How scoring works

Engines, the combiner, detection IDs, and reasons.

Rules

Compose decisions over signal fields with a safe grammar.

API Reference

Full reference for every endpoint, parameter, and response.

Release notes

What's new and what changed.

Was this page helpful?