Skip to content
Back to Docs

Server SDKs

Server API

Merchant backend API for event retrieval, device lookup, bot detection, and threat assessment.

openapi/server-api.yamlInteractive API Reference

Authentication

Use your tenant secret API key (typically sk_live_... or lrws1. prefix). Never expose it in browser code.

curl
curl https://api.lrdefender.lightningresearch.ai/api/v4/events/{eventId} \
  -H "Authorization: Bearer sk_live_xxxxxxxx" \
  -H "Content-Type: application/json"

# Alternative header:
# -H "X-API-Key: sk_live_xxxxxxxx"

Base URLs: api.lrdefender.lightningresearch.ai (global), api.us.lrdefender.lightningresearch.ai, api.eu.lrdefender.lightningresearch.ai

Endpoints

GET/api/analytics/events/{eventId}

Retrieve a single identification event by 24-char hex event ID.

Implementation: GET /api/v4/events/{eventId} · SDK: getEvent(eventId)

GET/api/fingerprint/visitor/{visitorId}

Visitor history with cursor pagination (limit, before).

Implementation: GET /api/v4/events?visitor_id={visitorId} · SDK: getVisitor(visitorId, { limit, before })

GET/api/fingerprint/device/{deviceId}

Look up device record: confidence, risk, visit count, smart signals.

Implementation: GET /api/device/{id} · SDK: getDevice(deviceId)

POST/api/bot/detect

Classify bot vs human using fingerprint and optional behavioral signals.

Implementation: POST /api/v1/bot/check · SDK: detectBot({ fingerprint, behavioral? })

POST/api/threat/assess

Evaluate IP reputation: VPN, proxy, Tor, datacenter, threat score.

Implementation: POST /api/v1/threat/assess · SDK: assessThreat(ip)

Code samples

Node.js (@lightningresearch/node-sdk)

node.ts
import { FingerprintServerClient } from '@lightningresearch/node-sdk';

const client = new FingerprintServerClient({
  apiKey: process.env.LRDEFENDER_API_KEY!,
  region: 'auto',
});

const event = await client.getEvent('a1b2c3d4e5f6789012345678');
const visitor = await client.getVisitor('a1b2c3d4e5f6789012345678', { limit: 20 });
const device = await client.getDevice('a1b2c3d4e5f6789012345678');
const bot = await client.detectBot({ fingerprint: { userAgent: 'Mozilla/5.0' } });
const threat = await client.assessThreat('203.0.113.42');

Python (lightningresearch)

python.py
from lightningresearch import FingerprintServerClient

client = FingerprintServerClient(api_key="lrws1.your_key", region="auto")

event = client.get_event("event_id_here")
visitor = client.get_visitor("visitor_id_here")
device = client.get_device("device_id_here")
bot = client.detect_bot({"userAgent": "Mozilla/5.0"})
threat = client.assess_threat("203.0.113.42")

Go (github.com/lightningresearch/go-sdk)

main.go
client := lrdefender.NewClient("lrws1.your_key", lrdefender.WithRegion("auto"))
ctx := context.Background()

event, _ := client.GetEvent(ctx, "event_id_here")
visitor, _ := client.GetVisitor(ctx, "visitor_id_here", 20, "")
device, _ := client.GetDevice(ctx, "device_id_here")
bot, _ := client.DetectBot(ctx, lrdefender.BotDetectRequest{
    Fingerprint: map[string]any{"userAgent": "Mozilla/5.0"},
})
threat, _ := client.AssessThreat(ctx, "203.0.113.42")

Java (com.lightningresearch:sdk)

App.java
LRDefenderClient client = new LRDefenderClient("lrws1.your_key", "auto");

Event event = client.getEvent("event_id_here");
VisitorResponse visitor = client.getVisitor("visitor_id_here");
DeviceIdentity device = client.getDevice("device_id_here");
BotResult bot = client.detectBot(Map.of("userAgent", "Mozilla/5.0"));
ThreatResult threat = client.assessThreat("203.0.113.42");

PHP (lightningresearch/sdk)

index.php
$client = new LRDefenderClient('lrws1.your_key', 'auto');

$event = $client->getEvent('event_id_here');
$visitor = $client->getVisitor('visitor_id_here');
$device = $client->getDevice('device_id_here');
$bot = $client->detectBot(['userAgent' => 'Mozilla/5.0']);
$threat = $client->assessThreat('203.0.113.42');

.NET (LightningResearch.SDK)

Program.cs
await using var client = new LRDefenderClient("lrws1.your_key", "auto");

Event eventRecord = await client.GetEventAsync("event_id_here");
VisitorResponse visitor = await client.GetVisitorAsync("visitor_id_here");
DeviceIdentity device = await client.GetDeviceAsync("device_id_here");
BotResult bot = await client.DetectBotAsync(new Dictionary<string, object> {
    ["userAgent"] = "Mozilla/5.0",
});
ThreatResult threat = await client.AssessThreatAsync("203.0.113.42");

Response schemas

DeviceIdentity / getDevice

Field
Type
deviceId
string (24 hex)
visitorId
string (24 hex)
confidence
number 0–1
risk.level
low | medium | high | critical
risk.score
number 0–1
isNewDevice
boolean
visitCount
integer

BotResult / detectBot

Field
Type
isBot
boolean
botScore
number 0–1
confidence
number 0–1
detectionMethod
string
action
string

ThreatResult / assessThreat

Field
Type
threatScore
number 0–1
riskLevel
clean | low | medium | high | critical
isProxy / isVpn / isTor
boolean
action
allow | monitor | challenge | block
event-response.json
{
  "eventId": "a1b2c3d4e5f6789012345678",
  "timestamp": "2026-06-09T12:00:00.000Z",
  "visitorId": "b2c3d4e5f6789012345678ab",
  "linkedId": "user-42",
  "identification": { "confidence": 0.98, "visitorFound": true },
  "smartSignals": { "vpn": false, "bot": false }
}

Rate limits

Defaults are deployment-configurable (commonly 100 requests/minute per API key). Responses may include X-RateLimit-Remaining and X-RateLimit-Reset headers. HTTP 429 indicates rate limiting — back off with exponential delay. Server SDKs retry transient 5xx errors automatically (3 attempts by default).

Related:WebhooksQuick StartProxy Setup