API Documentation

22 behavioral signals for detection. 20 for verification. Two products, one API.

Quick Start

1 Get a free API key at /api-dashboard

2 Add the collector to your page (for detection) or POST events directly (for verification)

3 Call /api/score or /api/verify-bot

    Detection
<!-- Add collector to your page -->
<script src="https://unpkg.com/@empowered-humanity/detectionlab-collector"></script>
<script>
  DetectionLab.init({ apiKey: "detlab_your_key" });
  document.querySelector("form").addEventListener("submit", async (e) => {
    e.preventDefault();
    const result = await DetectionLab.score();
    if (result.verdict === "FAIL") return alert("Bot detected");
    e.target.submit();
  });
</script>
  

    Verification
# Verify a bot via REST API
curl -X POST https://detectionlab.app/api/verify-bot \
  -H "Content-Type: application/json" \
  -H "X-API-Key: detlab_your_key" \
  -d '{"events": [...]}'
  

Bot Detection Endpoints

POST /api/score

Score a set of behavioral events. Returns a full score report with verdict and intent classification.

Headers

Header	Required	Description
`Content-Type`	Yes	`application/json`
`X-API-Key`	Recommended	Your API key (`detlab_...`). Required for rate limit tracking and credit deduction.
`X-Request-ID`	No	Optional request ID for tracing. Auto-generated if omitted.

Request Body

      JSON
{
  "events": [
    { "type": "mousemove", "x": 412, "y": 305, "isTrusted": true, "timestamp_ms": 1523 },
    { "type": "click", "x": 415, "y": 308, "elem_center_x": 420, "elem_center_y": 310, "element_id": "submit-btn", "isTrusted": true, "timestamp_ms": 3841 },
    { "type": "keydown", "key": "t", "delay_ms": 87, "isTrusted": true, "timestamp_ms": 5102 },
    { "type": "fingerprint", "data": { "webdriver": false, "...": "..." }, "timestamp_ms": 502 }
  ]
}
    

Response (200)

      JSON
{
  "overall_score": 78.4,
  "verdict": "PASS",
  "signals": {
    "mouse_curvature": { "score": 82.1, "weight": 0.15, "status": "pass" },
    "keystroke_timing": { "score": 71.5, "weight": 0.15, "status": "pass" },
    // ... 20 more signals
  },
  "intent": {
    "primary": "human",
    "confidence": 1.0
  },
  "data_exposure": { /* browser, webgl, webdriver info */ },
  "raw_stats": { /* event counts, session duration */ }
}
    

curl Example

      Terminal
curl -X POST https://detectionlab.app/api/score \
  -H "Content-Type: application/json" \
  -H "X-API-Key: detlab_your_key" \
  -d '{"events": [{"type": "mousemove", "x": 100, "y": 200, "isTrusted": true, "timestamp_ms": 1000}]}'
    

POST /api/signup

Create a free Sandbox API key (100 evaluations/month).

Request

      JSON
{ "email": "you@company.com" }
    

Response (200)

      JSON
{
  "api_key": "detlab_sk_abc123...",
  "tier": "sandbox",
  "credits": 100,
  "rate_limit_per_minute": 10
}
    

GET /api/keys?email=you@company.com

List all API keys for an email address (keys are masked).

GET /api/usage?key_id=key_123

Get usage logs for a specific API key.

POST /api/checkout/session

Create a Stripe checkout session for Pro ($29/mo) or Scale ($99/mo).

Request

      JSON
{
  "plan": "pro",
  "email": "you@company.com"
}
    

Bot Verification Endpoints

POST /api/verify-bot

Verify an entity IS a bot. Inverted scoring — machine precision, sustained throughput, and autonomous behavior score HIGH. Returns a verdict, bot type classification, and optional JWT trust token.

Headers

Header	Required	Description
`Content-Type`	Yes	`application/json`
`X-API-Key`	Yes	Your API key. Required for trust token generation.
`X-Ephemeral`	No	Set to `true` for ephemeral mode. If HUMAN_DETECTED, signal breakdown is omitted from response.
`X-Request-ID`	No	Optional request ID for tracing.

Request Body

      JSON
{
  "events": [
    { "type": "mousemove", "x": 500, "y": 300, "timestamp_ms": 100 },
    { "type": "click", "x": 500, "y": 300, "elem_center_x": 500, "elem_center_y": 300, "timestamp_ms": 150 },
    { "type": "keydown", "key": "a", "delay_ms": 2, "timestamp_ms": 200 }
  ]
}
    

Response (200)

      JSON
{
  "overall_score": 94.7,
  "verdict": "BOT_VERIFIED",
  "bot_type": "autonomous_agent",
  "trust_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "signals": {
    "bv_sustained_precision": { "score": 98.1, "weight": 0.08 },
    "bv_throughput_capacity": { "score": 95.4, "weight": 0.08 },
    "bv_latency_consistency": { "score": 91.2, "weight": 0.07 },
    // ... 17 more signals
  },
  "raw_stats": {
    "mouse_moves_captured": 500,
    "clicks_captured": 50,
    "keystrokes_captured": 200
  }
}
    

POST /api/verify-bot/session

Create a new continuous bot verification session. Stream events over time and get live verdict updates.

Request Body

      JSON
{
  "webhook_url": "https://your-app.com/webhook"  // optional
}
    

Response (200)

      JSON
{
  "session_id": "abc123def456",
  "created_at": 1708473600.0,
  "status": "created"
}
    

If webhook_url is provided, Detection Lab will POST to it when the verdict changes (e.g., BOT_VERIFIED flips to HUMAN_DETECTED).

POST /api/verify-bot/session/{session_id}/events

Append events to an existing continuous session. Each call re-scores with accumulated data.

Request Body

      JSON
{
  "events": [
    { "type": "mousemove", "x": 100, "y": 200, "timestamp_ms": 50000 },
    // ... more events
  ]
}
    

Response (200)

      JSON
{
  "current_verdict": "BOT_VERIFIED",
  "overall_score": 95.2,
  "events_total": 1523,
  "verdict_changed": false
}
    

GET /api/verify-bot/session/{session_id}

Get the current state and verdict of a continuous session.

Response (200)

      JSON
{
  "session_id": "abc123def456",
  "current_verdict": "BOT_VERIFIED",
  "overall_score": 95.2,
  "events_total": 1523,
  "created_at": 1708473600.0,
  "last_event_at": 1708477200.0,
  "verdict_history": [
    { "verdict": "UNCERTAIN", "at": 1708473610.0 },
    { "verdict": "BOT_VERIFIED", "at": 1708473650.0 }
  ]
}
    

Bot Verification Verdicts

Verdict	Score	Meaning	Suggested Action
`BOT_VERIFIED`	70+	Confirmed autonomous bot behavior	Issue trust token, allow agent access
`UNCERTAIN`	40-69	Mixed signals, could be remote-controlled	Request more events or flag for review
`HUMAN_DETECTED`	<40	Human behavioral patterns detected	Deny bot-only access, may be human LARPing

Bot Type Classification

When a bot is verified, the bot_type field classifies it into one of four archetypes:

Bot Type	Description	Detection Pattern
`autonomous_agent`	Fully autonomous AI agent	High body + high mind scores
`human_larping`	Human pretending to be a bot	Low body (biological tremor, overshoot)
`remote_controlled`	Bot with human oversight	High body, low mind (human decision pauses)
`replay_bot`	Replayed recorded sessions	Identical paths, single-human timing

Trust Tokens (JWT)

When /api/verify-bot returns BOT_VERIFIED and the request includes an X-API-Key, a signed JWT trust token is included in the response. Downstream services can validate this token without calling Detection Lab again.

Token Claims

Claim	Type	Description
`verdict`	string	BOT_VERIFIED, UNCERTAIN, or HUMAN_DETECTED
`overall_score`	float	Composite verification score (0-100)
`bot_type`	string	Classification (autonomous_agent, etc.)
`iat`	int	Issued-at timestamp (Unix epoch)
`exp`	int	Expiration timestamp (default: 1 hour TTL)
`iss`	string	`detectionlab.app`

Validation Example

    Python
import jwt

token = response["trust_token"]
claims = jwt.decode(token, "your_shared_secret", algorithms=["HS256"], issuer="detectionlab.app")

if claims["verdict"] == "BOT_VERIFIED":
    allow_agent_access(claims["bot_type"])
  

Detection Verdicts

Verdict	Score	Meaning	Suggested Action
`PASS`	70+	Genuine human behavior	Allow request
`MARGINAL`	50-69	Suspicious but inconclusive	Rate limit or flag for review
`FAIL`	<50	Bot detected	Block or challenge

Intent Classification

When a bot is detected (FAIL or MARGINAL), the intent field tells you what kind of bot it is:

Intent	Description	Suggested Response
`human`	Genuine human behavior	Allow
`credential_stuffing`	Rapid automated form-filling	Block + alert security
`scraping`	Content extraction	Rate limit
`spam_submission`	Template/AI-generated text	Block or flag
`account_takeover`	Polished automation with stolen creds	Block + MFA challenge
`replay_attack`	Replayed recorded sessions	Block + invalidate session
`framework_automation`	Selenium/Playwright/Puppeteer	Block
`click_fraud`	Automated ad/button clicking	Block + report
`unknown_bot`	Bot detected, intent unclear	Flag for investigation

Detection Signals (22)

Each signal is scored 0-100. A score above 70 means human-like behavior for that signal.

mouse_curvature mouse_speed click_precision hover_before_click keystroke_timing scroll_behavior dwell_time action_pacing overshoot fingerprint scroll_jump timing_fit direction_changes path_uniqueness velocity_asymmetry css_fingerprint stealth_artifacts event_trust spatial_efficiency vocabulary_richness typing_burst content_naturalness

Verification Signals (20)

Each signal is scored 0-100. A score above 70 means bot-like behavior for that signal (inverted from detection).

bv_mouse_curvature bv_mouse_speed bv_click_precision bv_hover_before_click bv_keystroke_timing bv_scroll_behavior bv_dwell_time bv_action_pacing bv_overshoot bv_direction_changes bv_timing_distribution bv_spatial_efficiency bv_velocity_asymmetry bv_sustained_precision bv_throughput_capacity bv_response_latency bv_micro_jitter bv_latency_consistency bv_instruction_independence bv_reasoning_consistency

Event Types

The collector captures these event types automatically. If building a custom collector, your events must include these fields:

Type	Required Fields
`mousemove`	`x, y, isTrusted, timestamp_ms`
`click`	`x, y, elem_center_x, elem_center_y, element_id, isTrusted, timestamp_ms`
`keydown`	`key, delay_ms, isTrusted, timestamp_ms`
`scroll`	`delta_y, delta_mode, pause_after_ms, scroll_y, isTrusted, timestamp_ms`
`hover`	`element_id, isTrusted, timestamp_ms`
`fingerprint`	`data (object), timestamp_ms`
`page_enter`	`page, word_count, timestamp_ms`
`page_leave`	`page, timestamp_ms`

Rate Limits

Bot Detection

Tier	Price	Evaluations/month	Rate Limit
Sandbox (free)	$0	100	10 req/min
Pro	$29/mo	10,000	100 req/min
Scale	$99/mo	100,000	500 req/min
Enterprise	Custom	Unlimited	1,000 req/min

Bot Verification

Tier	Price	Verifications/month	Rate Limit
Sandbox (free)	$0	50	5 req/min
Startup	$49/mo	5,000	50 req/min
Scale	$199/mo	100,000	200 req/min
Enterprise	Custom	Unlimited	Custom

Rate limit headers are returned with authenticated requests:

X-RateLimit-Limit — max requests per minute
X-RateLimit-Remaining — remaining requests
X-RateLimit-Reset — unix timestamp when limit resets

Error Responses

Code	Body	Cause
400	`{"error": "no data"}`	Empty request body
400	`{"error": "no events"}`	Events array is empty
404	`{"error": "session not found"}`	Invalid session ID for continuous sessions
429	`{"error": "Rate limit exceeded"}`	Too many requests

View Pricing · Get API Key · Try the Sandbox · Bot Verification