Bot Detection API: Complete Developer Guide

If you're building anything public — a SaaS, an e-commerce store, an API — automated traffic is already hitting it. A bot detection API is the cleanest way to handle it: instead of maintaining your own detection logic, you send each visitor's request context to an API and receive a decision you can act on. This guide explains how they work, what to look for, and how to integrate one today.

What a bot detection API actually does

You send a small request context — typically the client IP, the User-Agent, and which of your domains the request targeted. The API evaluates it across multiple signal groups and responds with:

• A decision (allow / challenge / block) — what your app should do.
• A bot score — how machine-like the request looks.
• Reasons — which signals fired (datacenter IP, velocity, automation flags…), so the decision is auditable.

That last part matters more than people realize. A bare "isBot: true" is not actionable when a customer complains. Reasons are.

Anatomy of a request (XAntiBot example)

XAntiBot's POST /api/check takes JSON: the client ip, the browser ua, and the protected domain, authenticated by an X-API-Key header (server-side only — never in frontend code):

{
  "ip": "203.0.113.44",
  "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
  "domain": "yourwebsite.com"
}

Response (shape illustrative — check current docs):

{
  "action": "allow",
  "isBot": false,
  "botScore": 0.07,
  "reasons": [],
  "visitId": "…"
}

Contract note: always branch on the action field, not only on isBot. A challenge response is not a block — it expects you to route the visitor into a challenge flow (e.g. Cloudflare Turnstile via a gateway).

What signals feed the score

A good API layers several groups — here's what XAntiBot evaluates:

1. Network intelligence: TOR exit-node lists (cached), datacenter/ASN ranges (GeoLite2 + fallback enrichment), custom IP/CIDR rules.
2. Behavioral velocity: rolling request counters across 1-minute, 10-minute, and 1-hour windows.
3. Browser signals: optional JavaScript check confirming a real browser environment (WebDriver flags, headless indicators).
4. Self-built IP reputation: abuse observed on your properties, time-decayed (24h half-life).
5. Challenge feedback: passes/failures/expiries of past challenges feed back into scoring.
6. Your custom rules: specific IPs, user-agents, or countries you allow/block regardless of score.

Rate limiting vs detection

Rate limiting answers "too many requests?" — detection answers "does this request look machine-made?". You want both: rate limits stop volume; detection stops stealthy volume that a limit would miss. (Full comparison: Bot Detection vs Rate Limiting.)

Choosing an API — an honest checklist

• Free tier you can actually use — not a 14-day demo. XAntiBot's free plan runs real traffic within a quota.
• Server-side key handling — keys must live in your backend, never in HTML/JS.
• Quota clarity — what counts as a request; what happens at the limit (XAntiBot: rate-limited refusals are never billed as detections).
• Decision + reasons — not just a boolean.
• Integration effort — downloadable packages (XAntiBot ships PHP packages) beat raw HTTP when you want to start fast.
• Failure mode — what happens when the API is unreachable; make it configurable.

Integration patterns

• PHP sites: include-first protection package (blocks before HTML renders). Full tutorial.
• Express/Node: middleware calling /api/check before your handlers. Full tutorial.
• Anything else (Python, Go, mobile backends): the API is plain HTTP — call it from any language.

FAQ

Is there a free bot detection API? Yes — XAntiBot's free tier covers real traffic within a monthly quota; no credit card required. How fast is a detection call? Tens of milliseconds over HTTPS; cache results per session where your app allows. Can detection be bypassed? Nothing is unbreakable. Layered signals + challenge feedback + reputation decay make evasion expensive instead of trivial.

Next steps

Create your free account → grab an API key → run your first /api/check in under five minutes.