Release notes

Tell Botect when a visitor signs in

• POST /v1/sessions/{session_token}/logged-in — assert, from your server, that a session authenticated in your application. See Assert logged in.

Botect stores a timestamp and nothing else. The endpoint accepts no request body and no query string, so a user id or email cannot reach it even by accident — we learn that a session signed in, never who did.

What it buys. A new per-project setting, logged_in_policy, decides what an assertion is worth at enforcement time: observe (the default — record only), never_block, never_challenge, or whitelist. No policy shelters the definite or confident_automated bands: a credential-stuffing bot logs in by definition, so hard evidence outranks the claim. At the Cloudflare edge the assertion moves an address from the block list to the challenge list rather than removing it, since one login must not unblock everyone behind a shared address.

Assert on every login. The window is 24 hours from the most recent call, and re-asserting restarts it. Repeats are idempotent and free. The session token lives in browser storage and outlives a logout, so an assertion that never expired would be a transferable pass.

Why we want it. Scoring weights are learned by comparing bot traffic against human traffic, and our stand-in for "human" has always been behavioral — which cannot measure the worth of behavioral signals without measuring itself. An authenticated session is a human label that owes nothing to observed behavior, so it breaks that circle and lets us count our own false positives for the first time. The assertion does not move a score today and no rule can read it; it will earn a weight only after it has been measured.

See Logged-in visitors.

Enforcement is decided by rules only

Botect had two places that could decide to block or challenge: your rules, and a pair of enforcement toggles on the project settings. They overlapped exactly — each toggle duplicated a rule shipped with every project — but had different reach, since the Cloudflare blocklist is built from active rules and never saw the toggles. Rules are now the single decision point.

Removed: block_definite and challenge_likely.

• PUT /v1/projects/{project}/scoring/settings rejects both fields with 422. They are not translated silently — a settings write should never conjure a rule you did not ask for.
• bot_settings in every response now carries allow_verified and protect_static only. Both are guards: they decide who skips checking, and they still run before rules.
• likely_bot_threshold is unchanged — it defines the bands themselves.

What to do instead: activate the starter rule that matches — band == "definite" → block, or band == "likely_automated" → challenge. Both ship with every project, inactive. Or create your own rule to act on a path, country or detection instead of a whole band.

Also new: PATCH /v1/projects/{project}/rules/{rule} — the API could previously create and delete rules but not change one, so there was no way to activate a starter rule outside the dashboard. See Update a rule.

The resolution order is now: verified short-circuit → static skip → rules → allow. Because rules are evaluated in sort_order and the first terminating match wins, an allow rule placed above a band rule now overrides it — the toggles used to run last, after every rule.

Blocks recorded by the verdict API carry source: "rule" and the id of the rule that caused them.

Export the verified-bot allowlist

• GET /v1/verified-bots/export — pull the full verified-bot allowlist (CIDR and rDNS rules) as a flat JSON list, to mirror into your own edge or audit recognized operators.

Gated on the new verified-bots-export plan feature (Business and Owner-lifetime plans) and the projects:read token ability. A token without the ability now returns 403 INSUFFICIENT_TOKEN_ABILITY.

See Export verified bots and Verified bots.

v1 API is live

The first release of the Botect bot-detection API. A two-plane design under /v1: a never-rate-limited data plane for ingest and verdicts, and an account-scoped control plane for configuration.

Data plane:

• POST /v1/events — ingest privacy-safe interaction signals (site-key auth, async-scored, idempotent)
• GET /v1/sessions/{token}/verdict — read a session's decision (private-key auth, Redis-cached, fails open)

Control plane:

• POST /v1/projects/{project}/scoring — enable scoring, mint site + private keys
• POST /v1/projects/{project}/scoring/rotate — rotate a site or private key
• PUT /v1/projects/{project}/scoring/settings — toggles + bot threshold
• GET|POST|DELETE /v1/projects/{project}/rules — custom rule CRUD
• GET /user, GET /v1/account — identity & account context

Scoring:

• Three independent engines — heuristics, JS detection (non-enforcing), behavioral — combined by strongest evidence into a 1–99 score (0 = not computed)
• Stable detection IDs and plain-English reasons on every bot-banded verdict
• Verified-bot allowlist with category, short-circuited to allow by default
• Safe rule grammar compiled to an AST — never eval'd

Defaults:

• Observe-first — block_definite and challenge_likely start off, so enabling scoring never breaks legitimate traffic
• Likely-bot threshold T = 30
• Verdict cache TTL 60s — a configuration change applies to verdicts computed after it, and already-cached verdicts expire within the TTL

See How scoring works for the engine model and Plans & quotas for how ingest volume is metered.