API reference | LR Defender

Overview

Download openapi.yamlLR Defender API 1.0.0

Base address: https://api.lrdefender.lightningresearch.ai
Authentication: Your secret key in the X-API-Key header, sent from your server only.

Device fingerprinting and bot detection API for LR Defender.

Authenticate every request with your tenant API key via the X-API-Key header. Keys are issued from the LR Defender dashboard and typically use the sk_ prefix.

Identification

Device fingerprinting and visitor identification.

Identify a device from signal payload

POST/api/device-idSecret key, X-API-Key

Primary device identification endpoint. Accepts browser or server-collected signal payloads and returns a stable deviceId, confidence score, smart signals, and risk analysis.

Set X-Fingerprint-Update: 1 or updateOnly: true to perform a lightweight update without full re-identification. Set X-API-Version: 2 or apiVersion=2 for the unified v2 response envelope.

Parameters of POST /api/device-id
Name	Type	Required or optional	Description
`X-Fingerprint-Update`	0 \| 1 \| true \| false (header)	Optional	When `1` or `true`, perform update-only persistence.
`X-API-Version`	2 (header)	Optional	Request the unified API v2 response envelope.
`X-Sealed-Results`	true \| false (header)	Optional	When `true`, return tamper-proof sealed (encrypted) results.
`apiVersion`	2 (query)	Optional

X-Fingerprint-Update0 | 1 | true | false (header)Optional: When 1 or true, perform update-only persistence.
X-API-Version2 (header)Optional: Request the unified API v2 response envelope.
X-Sealed-Resultstrue | false (header)Optional: When true, return tamper-proof sealed (encrypted) results.
apiVersion2 (query)Optional

Request body: DeviceIdentificationRequest, as JSON.

curl -X POST https://api.lrdefender.lightningresearch.ai/api/device-id \  -H "X-API-Key: $LR_SECRET_KEY" \  -H "Content-Type: application/json" \  -d '{    "platform": "MacIntel",    "timezone": "Europe/Paris",    "language": "en-US",    "screenWidth": 1920,    "screenHeight": 1080,    "devicePixelRatio": 1,    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",    "webglVendor": "Apple Inc.",    "webglRenderer": "Apple GPU",    "privacy": {      "mode": "full",      "consentStatus": "granted",      "version": "1.0"    }  }'

Responses of POST /api/device-id
Status	Meaning	Body
`200`	Identification succeeded	`DeviceIdentificationResponse`
`400`	Validation error	`ValidationError`
`401`	Missing or invalid API key	`ErrorResponse`
`403`	One of your rules blocked this identification (status blocked, with the matching rules in ruleResults), or a license or origin restriction	`RuleBlockedResponse` or `ErrorResponse`
`429`	Rate limit exceeded	`ErrorResponse`
`500`	Internal server error	`ErrorResponse`

200: MeaningIdentification succeeded; BodyDeviceIdentificationResponse
400: MeaningValidation error; BodyValidationError
401: MeaningMissing or invalid API key; BodyErrorResponse
403: MeaningOne of your rules blocked this identification (status blocked, with the matching rules in ruleResults), or a license or origin restriction; BodyRuleBlockedResponse or ErrorResponse
429: MeaningRate limit exceeded; BodyErrorResponse
500: MeaningInternal server error; BodyErrorResponse

Verify or retrieve an identification result

GET/api/device-id/{requestId}Secret key, X-API-Key

Poll the result of a prior identification request by requestId. Use the requestId that identify() returned in the browser, or one returned from an async or sealed identification flow, or from the API v2 response envelope. Results are kept for 24 hours after the identification.

Returns 404 when the request ID is unknown or has expired.

Parameters of GET /api/device-id/{requestId}
Name	Type	Required or optional	Description
`requestId`	string (path)	Required	Identification request identifier (e.g. `req_m3k9x2_a1b2c3`)

requestIdstring (path)Required: Identification request identifier (e.g. req_m3k9x2_a1b2c3)

curl https://api.lrdefender.lightningresearch.ai/api/device-id/$REQUEST_ID \  -H "X-API-Key: $LR_SECRET_KEY"

Responses of GET /api/device-id/{requestId}
Status	Meaning	Body
`200`	Identification result found	`IdentificationResultResponse`
`401`	Missing or invalid API key	`ErrorResponse`
`404`	Request ID not found or expired	`ErrorResponse`
`429`	Rate limit exceeded	`ErrorResponse`

200: MeaningIdentification result found; BodyIdentificationResultResponse
401: MeaningMissing or invalid API key; BodyErrorResponse
404: MeaningRequest ID not found or expired; BodyErrorResponse
429: MeaningRate limit exceeded; BodyErrorResponse

Recall a device by ID

GET/api/device-recall/{deviceId}Secret key, X-API-Key

Look up a previously identified device by its 24-character hexadecimal deviceId. Returns persistence metadata, the match type and confidence, and when the device was first and last seen.

Also available without a path parameter at GET /api/device-recall when using a valid persistence cookie or device token from a prior identification.

Parameters of GET /api/device-recall/{deviceId}
Name	Type	Required or optional	Description
`deviceId`	HexId24 (path)	Required	24-character hexadecimal device identifier

deviceIdHexId24 (path)Required: 24-character hexadecimal device identifier

curl https://api.lrdefender.lightningresearch.ai/api/device-recall/$DEVICE_ID \  -H "X-API-Key: $LR_SECRET_KEY"

Responses of GET /api/device-recall/{deviceId}
Status	Meaning	Body
`200`	Device found	`DeviceRecallResponse`
`401`	Missing or invalid API key	`ErrorResponse`
`404`	Device not found	`DeviceNotFoundResponse`
`429`	Rate limit exceeded	`ErrorResponse`
`500`	Internal server error	`ErrorResponse`

200: MeaningDevice found; BodyDeviceRecallResponse
401: MeaningMissing or invalid API key; BodyErrorResponse
404: MeaningDevice not found; BodyDeviceNotFoundResponse
429: MeaningRate limit exceeded; BodyErrorResponse
500: MeaningInternal server error; BodyErrorResponse

Collector

Server-side collector session issuance.

Create a collector session token

POST/api/collector/sessionSecret key, X-API-Key

Issue a short-lived bearer token for browser-side collector traffic via POST /collect/device. Call this from your server backend only; never expose your API key in client-side code.

Send the origin of the page that will run the check: without it the call returns 400 with the code origin_required. The token works only from that origin. If your account lists allowed origins, the origin must be one of them, or the call returns 403 with the code origin_not_allowed.

Request body: CollectorSessionRequest, as JSON.

curl -X POST https://api.lrdefender.lightningresearch.ai/api/collector/session \  -H "X-API-Key: $LR_SECRET_KEY" \  -H "Content-Type: application/json" \  -d '{    "origin": "https://app.example.com",    "ttlSeconds": 300,    "maxUses": 10  }'

Responses of POST /api/collector/session
Status	Meaning	Body
`200`	Collector session issued	`CollectorSessionResponse`
`400`	Invalid request (e.g. missing origin)	`ErrorResponse`
`401`	Missing or invalid API key	`ErrorResponse`
`403`	Origin not allowed or license invalid	`ErrorResponse`
`429`	Rate limit exceeded	`ErrorResponse`

200: MeaningCollector session issued; BodyCollectorSessionResponse
400: MeaningInvalid request (e.g. missing origin); BodyErrorResponse
401: MeaningMissing or invalid API key; BodyErrorResponse
403: MeaningOrigin not allowed or license invalid; BodyErrorResponse
429: MeaningRate limit exceeded; BodyErrorResponse

Challenge

Behavioral challenge verification.

Verify a behavioral challenge

POST/api/challenge/verifySecret key, X-API-Key

Verify a challenge issued during device identification when status: challenge_required is returned. On success, returns a short-lived passToken to include on subsequent POST /api/device-id requests.

Request body: ChallengeVerifyRequest, as JSON.

curl -X POST https://api.lrdefender.lightningresearch.ai/api/challenge/verify \  -H "X-API-Key: $LR_SECRET_KEY" \  -H "Content-Type: application/json" \  -d '{    "challengeToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",    "solution": 42  }'

Responses of POST /api/challenge/verify
Status	Meaning	Body
`200`	Challenge verified; pass token issued	`ChallengeVerifyResponse`
`400`	Missing challenge token	`ErrorResponse`
`401`	Challenge verification failed	`ErrorResponse`
`500`	Failed to issue pass token	`ErrorResponse`

200: MeaningChallenge verified; pass token issued; BodyChallengeVerifyResponse
400: MeaningMissing challenge token; BodyErrorResponse
401: MeaningChallenge verification failed; BodyErrorResponse
500: MeaningFailed to issue pass token; BodyErrorResponse

Health

Service health and readiness.

Health check

GET/healthzNo key

Returns service health status including database, Redis, and queue connectivity. No API key is needed.

curl https://api.lrdefender.lightningresearch.ai/healthz

Responses of GET /healthz
Status	Meaning	Body
`200`	Service is healthy or degraded but operational	`HealthResponse`
`503`	Service is down (core dependencies unavailable)	`HealthResponse`

200: MeaningService is healthy or degraded but operational; BodyHealthResponse
503: MeaningService is down (core dependencies unavailable); BodyHealthResponse

Schemas

The request and response bodies the endpoints above use.

DeviceIdentificationRequest

Browser or server-collected signal payload

Fields of DeviceIdentificationRequest
Name	Type	Required or optional	Description
`updateOnly`	boolean	Optional	When true, perform update-only without full identification
`deviceId`	HexId24	Optional	See `HexId24`.
`platform`	string	Optional
`timezone`	string	Optional
`language`	string	Optional
`userAgent`	string	Optional
`screenWidth`	integer	Optional
`screenHeight`	integer	Optional
`devicePixelRatio`	number	Optional
`webglVendor`	string	Optional
`webglRenderer`	string	Optional
`behavioral`	object	Optional	Behavioral biometrics signals
`privacy`	object	Optional
`metadata`	object	Optional
`clientDetection`	object	Optional

updateOnlybooleanOptional: When true, perform update-only without full identification
deviceIdHexId24Optional: See HexId24.
platformstringOptional
timezonestringOptional
languagestringOptional
userAgentstringOptional
screenWidthintegerOptional
screenHeightintegerOptional
devicePixelRationumberOptional
webglVendorstringOptional
webglRendererstringOptional
behavioralobjectOptional: Behavioral biometrics signals
privacyobjectOptional
metadataobjectOptional
clientDetectionobjectOptional

HexId24

24-character lowercase hexadecimal identifier

A value, not an object: see its type where it is used.

DeviceIdentificationResponse

Fields of DeviceIdentificationResponse
Name	Type	Required or optional	Description
`deviceId`	HexId24	Required	See `HexId24`.
`visitorId`	HexId24	Optional	See `HexId24`.
`confidence`	number	Optional	How closely this visit matched a known device, from 0 to 100. A heuristic, not a probability. `identification.confidence.score` carries the same value from 0 to 1.
`status`	success \| challenge_required \| ignored	Required
`matchType`	string	Optional	Detection strategy (e.g. new, exact, fuzzy)
`identification`	object	Optional
`smartSignals`	object	Optional	Bot, VPN, tampering, and other smart signal results
`suspectScore`	object	Optional
`challenge`	object	Optional	Present when behavioral challenge is required or verified
`actionRequired`	challenge	Optional
`experiments`	object[]	Optional
`meta`	object	Optional
`ruleAction`	RuleAction	Optional	See `RuleAction`.
`ruleResults`	RuleResults	Optional	See `RuleResults`.

deviceIdHexId24Required: See HexId24.
visitorIdHexId24Optional: See HexId24.
confidencenumberOptional: How closely this visit matched a known device, from 0 to 100. A heuristic, not a probability. identification.confidence.score carries the same value from 0 to 1.
statussuccess | challenge_required | ignoredRequired
matchTypestringOptional: Detection strategy (e.g. new, exact, fuzzy)
identificationobjectOptional
smartSignalsobjectOptional: Bot, VPN, tampering, and other smart signal results
suspectScoreobjectOptional
challengeobjectOptional: Present when behavioral challenge is required or verified
actionRequiredchallengeOptional
experimentsobject[]Optional
metaobjectOptional
ruleActionRuleActionOptional: See RuleAction.
ruleResultsRuleResultsOptional: See RuleResults.

RuleAction

Present when one of your rules matched with block, challenge or flag, the strictest of them (block, then challenge, then flag). Your rules never change risk.recommendation.action; act on the stricter of the two.

A value, not an object: see its type where it is used.

RuleResults

Present when any of your rules matched, the rules that matched.

A value, not an object: see its type where it is used.

ValidationError

Fields of ValidationError
Name	Type	Required or optional	Description
`error`	string	Required	Human-readable error message
`code`	string	Optional	Machine-readable error code
`details`	object[]	Optional

errorstringRequired: Human-readable error message
codestringOptional: Machine-readable error code
detailsobject[]Optional

ErrorResponse

Fields of ErrorResponse
Name	Type	Required or optional	Description
`error`	string	Required	Human-readable error message
`code`	string	Optional	Machine-readable error code

errorstringRequired: Human-readable error message
codestringOptional: Machine-readable error code

RuleBlockedResponse

The answer of POST /api/device-id when one of your rules with the action block matched.

Fields of RuleBlockedResponse
Name	Type	Required or optional	Description
`status`	blocked	Required
`action`	block	Required
`deviceId`	HexId24	Optional	See `HexId24`.
`visitorId`	HexId24	Optional	See `HexId24`.
`confidence`	number	Optional
`ruleResults`	RuleResults	Optional	See `RuleResults`.
`requestId`	string	Optional
`message`	string	Optional
`session_id`	string	Optional	Present while the risk engine or account scoring runs, as on every verdict.

statusblockedRequired
actionblockRequired
deviceIdHexId24Optional: See HexId24.
visitorIdHexId24Optional: See HexId24.
confidencenumberOptional
ruleResultsRuleResultsOptional: See RuleResults.
requestIdstringOptional
messagestringOptional
session_idstringOptional: Present while the risk engine or account scoring runs, as on every verdict.

IdentificationResultResponse

Stored or async identification result for a given requestId

Fields of IdentificationResultResponse
Name	Type	Required or optional	Description
`requestId`	string	Required
`status`	success \| pending \| challenge_required \| not_found	Required
`deviceId`	HexId24	Optional	See `HexId24`.
`confidence`	number	Optional
`products`	object	Optional	API v2 product envelope when available
`timestamp`	string	Optional
`ruleAction`	RuleAction	Optional	See `RuleAction`.
`ruleResults`	RuleResults	Optional	See `RuleResults`.

requestIdstringRequired
statussuccess | pending | challenge_required | not_foundRequired
deviceIdHexId24Optional: See HexId24.
confidencenumberOptional
productsobjectOptional: API v2 product envelope when available
timestampstringOptional
ruleActionRuleActionOptional: See RuleAction.
ruleResultsRuleResultsOptional: See RuleResults.

DeviceRecallResponse

Fields of DeviceRecallResponse
Name	Type	Required or optional	Description
`status`	ok	Required
`deviceId`	HexId24	Required	See `HexId24`.
`visitorId`	HexId24	Optional	See `HexId24`.
`strategy`	string	Optional	Persistence resolution strategy
`issuedAt`	string	Optional
`confidence`	number	Optional
`matchType`	string	Optional
`lastSeen`	string	Optional
`firstSeen`	string	Optional

statusokRequired
deviceIdHexId24Required: See HexId24.
visitorIdHexId24Optional: See HexId24.
strategystringOptional: Persistence resolution strategy
issuedAtstringOptional
confidencenumberOptional
matchTypestringOptional
lastSeenstringOptional
firstSeenstringOptional

DeviceNotFoundResponse

Fields of DeviceNotFoundResponse
Name	Type	Required or optional	Description
`status`	not_found	Required
`deviceId`	null	Optional

statusnot_foundRequired
deviceIdnullOptional

CollectorSessionRequest

Fields of CollectorSessionRequest
Name	Type	Required or optional	Description
`origin`	string	Optional	The origin of the page that runs the check. Required unless the request carries an Origin header.
`ttlSeconds`	integer	Optional	Session lifetime in seconds. Values above 600 are treated as 600.
`maxUses`	integer	Optional	Maximum number of collector ingest calls per token. Values above 20 are treated as 20.

originstringOptional: The origin of the page that runs the check. Required unless the request carries an Origin header.
ttlSecondsintegerOptional: Session lifetime in seconds. Values above 600 are treated as 600.
maxUsesintegerOptional: Maximum number of collector ingest calls per token. Values above 20 are treated as 20.

CollectorSessionResponse

Fields of CollectorSessionResponse
Name	Type	Required or optional	Description
`tokenType`	string	Required
`sessionToken`	string	Required	Bearer token for `POST /collect/device`
`expiresAt`	string	Required
`collectPath`	string	Required
`maxUses`	integer	Optional
`tenantId`	HexId24	Optional	See `HexId24`.

tokenTypestringRequired
sessionTokenstringRequired: Bearer token for POST /collect/device
expiresAtstringRequired
collectPathstringRequired
maxUsesintegerOptional
tenantIdHexId24Optional: See HexId24.

HealthResponse

Fields of HealthResponse
Name	Type	Required or optional
`status`	ok \| degraded \| down	Required
`degraded`	boolean	Optional
`region`	string	Optional
`uptimeSeconds`	integer	Optional
`database`	connected \| disconnected \| in_memory_fallback	Optional
`databaseConnected`	boolean	Optional
`databaseDurable`	boolean	Optional
`fallbackMode`	boolean	Optional
`redis`	connected \| disconnected	Optional
`queue`	ready \| degraded	Optional
`redisConnected`	boolean	Optional
`queueConnected`	boolean	Optional
`timestamp`	string	Required

statusok | degraded | downRequired
degradedbooleanOptional
regionstringOptional
uptimeSecondsintegerOptional
databaseconnected | disconnected | in_memory_fallbackOptional
databaseConnectedbooleanOptional
databaseDurablebooleanOptional
fallbackModebooleanOptional
redisconnected | disconnectedOptional
queueready | degradedOptional
redisConnectedbooleanOptional
queueConnectedbooleanOptional
timestampstringRequired

ChallengeVerifyRequest

Fields of ChallengeVerifyRequest
Name	Type	Required or optional	Description
`challengeToken`	string	Optional	Challenge JWT from the identification response
`token`	string	Optional	Alias for challengeToken
`solution`	string or number	Optional	Challenge solution (e.g. proof-of-work nonce)
`proof`	string or number	Optional	Alias for solution
`response`	string or number	Optional	Alias for solution

challengeTokenstringOptional: Challenge JWT from the identification response
tokenstringOptional: Alias for challengeToken
solutionstring or numberOptional: Challenge solution (e.g. proof-of-work nonce)
proofstring or numberOptional: Alias for solution
responsestring or numberOptional: Alias for solution

ChallengeVerifyResponse

Fields of ChallengeVerifyResponse
Name	Type	Required or optional	Description
`status`	verified	Required
`tenantId`	HexId24	Optional	See `HexId24`.
`scope`	string	Optional
`passToken`	string	Required	Short-lived token for subsequent identification requests
`expiresAt`	string	Required

statusverifiedRequired
tenantIdHexId24Optional: See HexId24.
scopestringOptional
passTokenstringRequired: Short-lived token for subsequent identification requests
expiresAtstringRequired

Overview

Identification

Identify a device from signal payload

Verify or retrieve an identification result

Recall a device by ID

Collector

Create a collector session token

Challenge

Verify a behavioral challenge

Health

Health check

Schemas

DeviceIdentificationRequest

HexId24

DeviceIdentificationResponse

RuleAction

RuleResults

ValidationError

ErrorResponse

RuleBlockedResponse

IdentificationResultResponse

DeviceRecallResponse

DeviceNotFoundResponse

CollectorSessionRequest

CollectorSessionResponse

HealthResponse

ChallengeVerifyRequest

ChallengeVerifyResponse

Get a verdict in your own app.