{ "openapi": "3.1.0", "info": { "title": "Device Fingerprint & Bot Detection API", "version": "v0.0.2", "description": "Assess bot and fraud risk from device fingerprints, browser signals, request headers and IP context.", "x-pricing-model": "payg", "x-free-tier-calls": 0, "x-docs-url": "", "x-dakidarts-contract-status": "published", "x-dakidarts-execution-status": "source-only" }, "servers": [ { "url": "https://api.dakidarts.com/device-fingerprint-bot-detection", "description": "Dakidarts direct gateway" } ], "tags": [ { "name": "Operations", "description": "Operations endpoints sourced from the Device Fingerprint & Bot Detection API implementation." }, { "name": "Analysis", "description": "Analysis endpoints sourced from the Device Fingerprint & Bot Detection API implementation." }, { "name": "Device Info", "description": "Device Info endpoints sourced from the Device Fingerprint & Bot Detection API implementation." }, { "name": "Entropy", "description": "Entropy endpoints sourced from the Device Fingerprint & Bot Detection API implementation." }, { "name": "Compare", "description": "Compare endpoints sourced from the Device Fingerprint & Bot Detection API implementation." } ], "paths": { "/": { "get": { "summary": "Index", "description": "Service banner: name, version, description.", "operationId": "device-fingerprint-bot-detection_get_root", "tags": [ "Operations" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true } }, "/status": { "get": { "summary": "Status", "description": "Health check and version.", "operationId": "device-fingerprint-bot-detection_get_status", "tags": [ "Operations" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true } }, "/meta": { "get": { "summary": "Meta", "description": "Self-describing metadata: version, full endpoint list and the BYOK headers the service understands. Useful for auto-generated API clients and RapidAPI docs.", "operationId": "device-fingerprint-bot-detection_get_meta", "tags": [ "Operations" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true } }, "/fingerprint": { "get": { "summary": "Fingerprint Route", "description": "Generates a fingerprint from **custom JSON input**. Supports both **snake_case** and **camelCase** keys. Backward compatible with v0.0.1 \u2014 the legacy `fingerprint` hash and `risk` object are unchanged.", "operationId": "device-fingerprint-bot-detection_get_fingerprint", "tags": [ "Analysis" ], "parameters": [ { "name": "user_agent", "in": "query", "required": false, "description": "Browser User-Agent (defaults to the request's UA).", "schema": { "type": "string", "example": "Mozilla/5.0 (X11; Linux)" }, "example": "Mozilla/5.0 (X11; Linux)" }, { "name": "userAgent", "in": "query", "required": false, "description": "Browser User-Agent (defaults to the request's UA).", "schema": { "type": "string", "example": "Mozilla/5.0 (X11; Linux)" }, "example": "Mozilla/5.0 (X11; Linux)" }, { "name": "ip", "in": "query", "required": false, "description": "Client IP address (defaults to the request's remote address).", "schema": { "type": "string", "example": "203.0.113.9" }, "example": "203.0.113.9" }, { "name": "headers", "in": "query", "required": false, "description": "Custom headers dictionary.", "schema": { "type": "object", "example": { "X-Test-Header": "boom" } }, "example": { "X-Test-Header": "boom" } }, { "name": "signals", "in": "query", "required": false, "description": "Client-side fingerprint signals (canvas/WebGL/audio hashes, screen, fonts, timezone, CPU/memory, webdriver, etc.). See table below.", "schema": { "type": "object", "example": { "screen": { "width": 1920, "height": 1080 }, "webdriver": false, "canvas_hash": "abc" } }, "example": { "screen": { "width": 1920, "height": 1080 }, "webdriver": false, "canvas_hash": "abc" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "description": "Dynamic source value; no concrete response example is published." }, "risk": { "type": "object", "additionalProperties": true }, "ip_source": { "description": "Dynamic source value; no concrete response example is published." }, "components": { "description": "Dynamic source value; no concrete response example is published." }, "user_agent": { "type": "integer" }, "fingerprint": { "description": "Dynamic source value; no concrete response example is published." }, "completeness": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_full": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_type": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_extended": { "description": "Dynamic source value; no concrete response example is published." } }, "additionalProperties": true } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true }, "post": { "summary": "Fingerprint Route", "description": "Generates a fingerprint from **custom JSON input**. Supports both **snake_case** and **camelCase** keys. Backward compatible with v0.0.1 \u2014 the legacy `fingerprint` hash and `risk` object are unchanged.", "operationId": "device-fingerprint-bot-detection_post_fingerprint", "tags": [ "Analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "description": "Dynamic source value; no concrete response example is published." }, "risk": { "type": "object", "additionalProperties": true }, "ip_source": { "description": "Dynamic source value; no concrete response example is published." }, "components": { "description": "Dynamic source value; no concrete response example is published." }, "user_agent": { "type": "integer" }, "fingerprint": { "description": "Dynamic source value; no concrete response example is published." }, "completeness": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_full": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_type": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_extended": { "description": "Dynamic source value; no concrete response example is published." } }, "additionalProperties": true } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_agent": { "type": "string", "example": "Mozilla/5.0 (X11; Linux)" }, "userAgent": { "type": "string", "example": "Mozilla/5.0 (X11; Linux)" }, "ip": { "type": "string", "example": "203.0.113.9" }, "headers": { "type": "object", "example": { "X-Test-Header": "boom" } }, "signals": { "type": "object", "example": { "screen": { "width": 1920, "height": 1080 }, "webdriver": false, "canvas_hash": "abc" } } } } } } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true } }, "/bot-detection": { "get": { "summary": "Bot Detection Route", "description": "Scores how likely a request is automated across three surfaces: User-Agent, request headers, and client-side signals. No signals required \u2014 but sending `webdriver`, `hardware_concurrency`, `device_memory`, `screen`, `languages` dramatically improves headless detection.", "operationId": "device-fingerprint-bot-detection_get_bot-detection", "tags": [ "Analysis" ], "parameters": [ { "name": "user_agent", "in": "query", "required": false, "description": "User-Agent string to analyze.", "schema": { "type": "string", "example": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" }, "example": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" }, { "name": "headers", "in": "query", "required": false, "description": "Request headers.", "schema": { "type": "object", "example": { "X-Requested-With": "XMLHttpRequest" } }, "example": { "X-Requested-With": "XMLHttpRequest" } }, { "name": "signals", "in": "query", "required": false, "description": "Client-side signals.", "schema": { "type": "object", "example": { "webdriver": true, "hardware_concurrency": 0 } }, "example": { "webdriver": true, "hardware_concurrency": 0 } }, { "name": "userAgent", "in": "query", "required": false, "description": "Alias for `user_agent`; User-Agent string to analyze.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true }, "post": { "summary": "Bot Detection Route", "description": "Scores how likely a request is automated across three surfaces: User-Agent, request headers, and client-side signals. No signals required \u2014 but sending `webdriver`, `hardware_concurrency`, `device_memory`, `screen`, `languages` dramatically improves headless detection.", "operationId": "device-fingerprint-bot-detection_post_bot-detection", "tags": [ "Analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "reasons": [ "Automation / headless tool string detected in UA", "navigator.webdriver flag is true", "hardwareConcurrency is 0 (headless browsers report 0)", "deviceMemory is 0 (headless browsers report 0)", "No navigator.languages reported" ], "verdict": "automated", "confidence": "high", "risk_level": "high", "risk_score": 100, "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/120.0.0.0 Safari/537.36", "signals_checked": 7, "signals_available": 3 } } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_agent": { "type": "string", "example": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" }, "headers": { "type": "object", "example": { "X-Requested-With": "XMLHttpRequest" } }, "signals": { "type": "object", "example": { "webdriver": true, "hardware_concurrency": 0 } }, "userAgent": { "type": "string" } } } } } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true, "x-dakidarts-sample-response": { "reasons": [ "Automation / headless tool string detected in UA", "navigator.webdriver flag is true", "hardwareConcurrency is 0 (headless browsers report 0)", "deviceMemory is 0 (headless browsers report 0)", "No navigator.languages reported" ], "verdict": "automated", "confidence": "high", "risk_level": "high", "risk_score": 100, "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/120.0.0.0 Safari/537.36", "signals_checked": 7, "signals_available": 3 } } }, "/device-info": { "get": { "summary": "Device Info Route", "description": "Parses any User-Agent string into a structured device/browser/OS breakdown. Heuristic, dependency-free; unknown strings fall back to `\"unknown\"`.", "operationId": "device-fingerprint-bot-detection_get_device-info", "tags": [ "Device Info" ], "parameters": [ { "name": "user_agent", "in": "query", "required": false, "description": "User-Agent string to analyze.", "schema": { "type": "string", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_1 like Mac OS X) AppleWebKit/605.1.15 ... Safari/604.1" }, "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_1 like Mac OS X) AppleWebKit/605.1.15 ... Safari/604.1" }, { "name": "userAgent", "in": "query", "required": false, "description": "User-Agent string to analyze.", "schema": { "type": "string", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_1 like Mac OS X) AppleWebKit/605.1.15 ... Safari/604.1" }, "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_1 like Mac OS X) AppleWebKit/605.1.15 ... Safari/604.1" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true }, "post": { "summary": "Device Info Route", "description": "Parses any User-Agent string into a structured device/browser/OS breakdown. Heuristic, dependency-free; unknown strings fall back to `\"unknown\"`.", "operationId": "device-fingerprint-bot-detection_post_device-info", "tags": [ "Device Info" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "os": "iOS", "is_bot": false, "browser": "Safari", "is_mobile": true, "is_tablet": false, "os_version": "17.1", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1 Mobile/15E148 Safari/604.1", "device_type": "phone", "device_brand": "Apple", "device_model": "iPhone", "browser_engine": "WebKit", "browser_version": "17.1" } } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_agent": { "type": "string", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_1 like Mac OS X) AppleWebKit/605.1.15 ... Safari/604.1" }, "userAgent": { "type": "string", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_1 like Mac OS X) AppleWebKit/605.1.15 ... Safari/604.1" } } } } } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true, "x-dakidarts-sample-response": { "os": "iOS", "is_bot": false, "browser": "Safari", "is_mobile": true, "is_tablet": false, "os_version": "17.1", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1 Mobile/15E148 Safari/604.1", "device_type": "phone", "device_brand": "Apple", "device_model": "iPhone", "browser_engine": "WebKit", "browser_version": "17.1" } } }, "/headers/analyze": { "get": { "summary": "Headers Analyze Route", "description": "Forensic analysis of a request-header map: proxy/VPN hints, reconstructed `X-Forwarded-For` chain, spoofed/placeholder values, structural anomalies, and missing browser headers with recommendations.", "operationId": "device-fingerprint-bot-detection_get_headers_analyze", "tags": [ "Analysis" ], "parameters": [ { "name": "headers", "in": "query", "required": false, "description": "Headers to analyze (defaults to the request's own headers).", "schema": { "type": "object", "example": { "Accept": "text/html", "User-Agent": "Mozilla/5.0 ...", "X-Forwarded-For": "1.2.3.4, 5.6.7.8" } }, "example": { "Accept": "text/html", "User-Agent": "Mozilla/5.0 ...", "X-Forwarded-For": "1.2.3.4, 5.6.7.8" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true }, "post": { "summary": "Headers Analyze Route", "description": "Forensic analysis of a request-header map: proxy/VPN hints, reconstructed `X-Forwarded-For` chain, spoofed/placeholder values, structural anomalies, and missing browser headers with recommendations.", "operationId": "device-fingerprint-bot-detection_post_headers_analyze", "tags": [ "Analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "anomalies": [], "header_count": 5, "proxy_headers": [ "x-forwarded-for" ], "forwarded_chain": [ "1.2.3.4", "5.6.7.8" ], "headers_present": [ "accept", "accept-language", "user-agent", "x-forwarded-for", "x-requested-with" ], "recommendations": [ "Proxy/VPN headers seen; treat the client IP with suspicion or re-derive it from the left-most X-Forwarded-For hop." ], "spoofing_indicators": [], "missing_browser_headers": [ "accept-encoding/connection" ] } } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "headers": { "type": "object", "example": { "Accept": "text/html", "User-Agent": "Mozilla/5.0 ...", "X-Forwarded-For": "1.2.3.4, 5.6.7.8" } } } } } } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true, "x-dakidarts-sample-response": { "anomalies": [], "header_count": 5, "proxy_headers": [ "x-forwarded-for" ], "forwarded_chain": [ "1.2.3.4", "5.6.7.8" ], "headers_present": [ "accept", "accept-language", "user-agent", "x-forwarded-for", "x-requested-with" ], "recommendations": [ "Proxy/VPN headers seen; treat the client IP with suspicion or re-derive it from the left-most X-Forwarded-For hop." ], "spoofing_indicators": [], "missing_browser_headers": [ "accept-encoding/connection" ] } } }, "/ip/geolocate": { "get": { "summary": "Geolocate Route", "description": "Geolocates an IP and reports proxy/VPN/Tor/datacenter signals. **BYOK** \u2014 default provider `ipwhois` needs no key. For keyed providers (`ipinfo`, `abstractapi`, `ip2location`), pass your key via the `X-IP-Geo-Key` header or `api_key` param. All providers are normalized to one response schema.", "operationId": "device-fingerprint-bot-detection_get_ip_geolocate", "tags": [ "Analysis" ], "parameters": [ { "name": "ip", "in": "query", "required": false, "description": "IP to geolocate (defaults to the caller's IP).", "schema": { "type": "string", "example": "8.8.8.8" }, "example": "8.8.8.8" }, { "name": "provider", "in": "query", "required": false, "description": "Provider: `ipwhois` (default), `ipinfo`, `ipapi`, `abstractapi`, `ip2location`. Header equivalent: `X-IP-Geo-Provider`.", "schema": { "type": "string", "example": "ipinfo" }, "example": "ipinfo" }, { "name": "api_key", "in": "query", "required": false, "description": "Your provider key (required only for `ipinfo`/`abstractapi`/`ip2location`). Header equivalent: `X-IP-Geo-Key`.", "schema": { "type": "string", "example": "your_token" }, "example": "your_token" }, { "name": "X-IP-Geo-Provider", "in": "header", "required": false, "description": "Optional geolocation provider selector (BYOK configuration).", "schema": { "type": "string" } }, { "name": "X-IP-Geo-Key", "in": "header", "required": false, "description": "Optional API key for the selected geolocation provider (BYOK).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true }, "post": { "summary": "Geolocate Route", "description": "Geolocates an IP and reports proxy/VPN/Tor/datacenter signals. **BYOK** \u2014 default provider `ipwhois` needs no key. For keyed providers (`ipinfo`, `abstractapi`, `ip2location`), pass your key via the `X-IP-Geo-Key` header or `api_key` param. All providers are normalized to one response schema.", "operationId": "device-fingerprint-bot-detection_post_ip_geolocate", "tags": [ "Analysis" ], "parameters": [ { "name": "X-IP-Geo-Provider", "in": "header", "required": false, "description": "Optional geolocation provider selector (BYOK configuration).", "schema": { "type": "string" } }, { "name": "X-IP-Geo-Key", "in": "header", "required": false, "description": "Optional API key for the selected geolocation provider (BYOK).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ip": "8.8.8.8", "asn": "15169", "isp": "Google LLC", "org": "Google LLC", "city": "San Jose", "postal": "95141", "region": "California", "source": "ipwhois", "status": "ok", "country": "United States", "latitude": 37.3394, "security": { "tor": false, "vpn": false, "proxy": false, "crawler": false, "hosting": false, "fraud_score": null, "threat_score": null }, "timezone": "America/Los_Angeles", "continent": "North America", "longitude": -121.895, "country_code": "US" } } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "example": "8.8.8.8" }, "provider": { "type": "string", "example": "ipinfo" }, "api_key": { "type": "string", "example": "your_token" } } } } } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true, "x-dakidarts-sample-response": { "ip": "8.8.8.8", "asn": "15169", "isp": "Google LLC", "org": "Google LLC", "city": "San Jose", "postal": "95141", "region": "California", "source": "ipwhois", "status": "ok", "country": "United States", "latitude": 37.3394, "security": { "tor": false, "vpn": false, "proxy": false, "crawler": false, "hosting": false, "fraud_score": null, "threat_score": null }, "timezone": "America/Los_Angeles", "continent": "North America", "longitude": -121.895, "country_code": "US" } } }, "/risk-analysis": { "get": { "summary": "Risk Analysis Route", "description": "The go/no-go fraud verdict. Blends four surfaces into a single 0\u2013100 score:", "operationId": "device-fingerprint-bot-detection_get_risk-analysis", "tags": [ "Analysis" ], "parameters": [ { "name": "ip", "in": "query", "required": false, "description": "Device IP.", "schema": { "type": "string", "example": "8.8.8.8" }, "example": "8.8.8.8" }, { "name": "user_agent", "in": "query", "required": false, "description": "User-Agent string to analyze.", "schema": { "type": "string", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..." }, "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..." }, { "name": "userAgent", "in": "query", "required": false, "description": "User-Agent string to analyze.", "schema": { "type": "string", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..." }, "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..." }, { "name": "headers", "in": "query", "required": false, "description": "Request headers.", "schema": { "type": "object", "example": { "Accept": "text/html", "Accept-Language": "en-US,en;q=0.9" } }, "example": { "Accept": "text/html", "Accept-Language": "en-US,en;q=0.9" } }, { "name": "signals", "in": "query", "required": false, "description": "Client-side signals.", "schema": { "type": "object", "example": { "screen": { "width": 1920, "height": 1080 }, "webdriver": false, "hardware_concurrency": 8 } }, "example": { "screen": { "width": 1920, "height": 1080 }, "webdriver": false, "hardware_concurrency": 8 } }, { "name": "include_geo", "in": "query", "required": false, "description": "Run IP geolocation enrichment. Set `false` to skip the external call.", "schema": { "type": "boolean" } }, { "name": "provider", "in": "query", "required": false, "description": "Geolocation provider (same as `/ip/geolocate`).", "schema": { "type": "string", "example": "ipwhois" }, "example": "ipwhois" }, { "name": "api_key", "in": "query", "required": false, "description": "Provider key (BYOK).", "schema": { "type": "string", "example": "your_token" }, "example": "your_token" }, { "name": "X-IP-Geo-Provider", "in": "header", "required": false, "description": "Optional geolocation provider selector (BYOK configuration).", "schema": { "type": "string" } }, { "name": "X-IP-Geo-Key", "in": "header", "required": false, "description": "Optional API key for the selected geolocation provider (BYOK).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "description": "Dynamic source value; no concrete response example is published." }, "flags": { "type": "array", "items": {} }, "headers": { "description": "Dynamic source value; no concrete response example is published." }, "reasons": { "description": "Dynamic source value; no concrete response example is published." }, "verdict": { "description": "Dynamic source value; no concrete response example is published." }, "breakdown": { "type": "object", "properties": { "confidence": { "description": "Dynamic source value; no concrete response example is published." }, "bot_detection": { "description": "Dynamic source value; no concrete response example is published." }, "ip_geolocation": { "description": "Dynamic source value; no concrete response example is published." }, "header_analysis": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_completeness": { "type": "integer" } }, "additionalProperties": true }, "ip_source": { "description": "Dynamic source value; no concrete response example is published." }, "risk_level": { "description": "Dynamic source value; no concrete response example is published." }, "risk_score": { "type": "integer" }, "user_agent": { "type": "integer" }, "analyzed_at": { "type": "string", "format": "date-time" }, "fingerprint": { "type": "object", "properties": { "components": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_full": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_extended": { "description": "Dynamic source value; no concrete response example is published." } }, "additionalProperties": true }, "geolocation": {}, "bot_detection": { "description": "Dynamic source value; no concrete response example is published." } }, "additionalProperties": true } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true }, "post": { "summary": "Risk Analysis Route", "description": "The go/no-go fraud verdict. Blends four surfaces into a single 0\u2013100 score:", "operationId": "device-fingerprint-bot-detection_post_risk-analysis", "tags": [ "Analysis" ], "parameters": [ { "name": "X-IP-Geo-Provider", "in": "header", "required": false, "description": "Optional geolocation provider selector (BYOK configuration).", "schema": { "type": "string" } }, { "name": "X-IP-Geo-Key", "in": "header", "required": false, "description": "Optional API key for the selected geolocation provider (BYOK).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "description": "Dynamic source value; no concrete response example is published." }, "flags": { "type": "array", "items": {} }, "headers": { "description": "Dynamic source value; no concrete response example is published." }, "reasons": { "description": "Dynamic source value; no concrete response example is published." }, "verdict": { "description": "Dynamic source value; no concrete response example is published." }, "breakdown": { "type": "object", "properties": { "confidence": { "description": "Dynamic source value; no concrete response example is published." }, "bot_detection": { "description": "Dynamic source value; no concrete response example is published." }, "ip_geolocation": { "description": "Dynamic source value; no concrete response example is published." }, "header_analysis": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_completeness": { "type": "integer" } }, "additionalProperties": true }, "ip_source": { "description": "Dynamic source value; no concrete response example is published." }, "risk_level": { "description": "Dynamic source value; no concrete response example is published." }, "risk_score": { "type": "integer" }, "user_agent": { "type": "integer" }, "analyzed_at": { "type": "string", "format": "date-time" }, "fingerprint": { "type": "object", "properties": { "components": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_full": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_extended": { "description": "Dynamic source value; no concrete response example is published." } }, "additionalProperties": true }, "geolocation": {}, "bot_detection": { "description": "Dynamic source value; no concrete response example is published." } }, "additionalProperties": true } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "example": "8.8.8.8" }, "user_agent": { "type": "string", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..." }, "userAgent": { "type": "string", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..." }, "headers": { "type": "object", "example": { "Accept": "text/html", "Accept-Language": "en-US,en;q=0.9" } }, "signals": { "type": "object", "example": { "screen": { "width": 1920, "height": 1080 }, "webdriver": false, "hardware_concurrency": 8 } }, "include_geo": { "type": "boolean" }, "provider": { "type": "string", "example": "ipwhois" }, "api_key": { "type": "string", "example": "your_token" } } } } } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true, "x-dakidarts-sample-response": { "ip": "8.8.8.8", "flags": [], "headers": { "anomalies": [], "proxy_headers": [], "spoofing_indicators": [] }, "reasons": [], "verdict": "low_risk", "breakdown": { "confidence": "medium", "bot_detection": 10, "ip_geolocation": 0, "header_analysis": 10, "fingerprint_completeness": 0 }, "ip_source": "provided", "risk_level": "low", "risk_score": 14, "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...", "analyzed_at": "2026-08-28T11:57:08+00:00", "fingerprint": { "components": { "canvas": true, "screen": true }, "fingerprint_full": "4863c2cbe782e713fc5bd059d9adc2c3...", "fingerprint_extended": "c436873ca9a49169e5451da0fe60f91f..." }, "geolocation": { "source": "ipwhois", "status": "ok", "country": "United States", "security": { "proxy": false } }, "bot_detection": { "verdict": "human", "confidence": "medium", "risk_level": "low", "risk_score": 10 } } } }, "/entropy": { "get": { "summary": "Entropy Route", "description": "Analyzes the entropy/stability of a fingerprint hash \u2014 or derives one from signals first. Low entropy means the hash is predictable/collidable.", "operationId": "device-fingerprint-bot-detection_get_entropy", "tags": [ "Entropy" ], "parameters": [ { "name": "fingerprint", "in": "query", "required": false, "description": "A fingerprint hash to analyze.", "schema": { "type": "string", "example": "c436873ca9a49169e5451da0fe60f91f234454cf2e5b724b56813f979cb45274" }, "example": "c436873ca9a49169e5451da0fe60f91f234454cf2e5b724b56813f979cb45274", "x-required-group": "conditional" }, { "name": "signals", "in": "query", "required": false, "description": "Signals to derive a fingerprint from (when `fingerprint` is omitted).", "schema": { "type": "object", "example": { "screen": { "width": 1920, "height": 1080 }, "canvas_hash": "abc" } }, "example": { "screen": { "width": 1920, "height": 1080 }, "canvas_hash": "abc" }, "x-required-group": "conditional" }, { "name": "ip", "in": "query", "required": false, "description": "Used when deriving from signals.", "schema": { "type": "string", "example": "8.8.8.8" }, "example": "8.8.8.8" }, { "name": "user_agent", "in": "query", "required": false, "description": "Used when deriving from signals.", "schema": { "type": "string", "example": "Mozilla/5.0 ..." }, "example": "Mozilla/5.0 ..." }, { "name": "headers", "in": "query", "required": false, "description": "Used when deriving from signals.", "schema": { "type": "object", "example": { "Accept": "text/html" } }, "example": { "Accept": "text/html" } }, { "name": "or `signals` (+ optional `ip`/`user_agent`/`headers`)", "in": "query", "required": false, "description": "Computes a fingerprint from signals, then analyzes it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true }, "post": { "summary": "Entropy Route", "description": "Analyzes the entropy/stability of a fingerprint hash \u2014 or derives one from signals first. Low entropy means the hash is predictable/collidable.", "operationId": "device-fingerprint-bot-detection_post_entropy", "tags": [ "Entropy" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "notes": [ "high per-character entropy - collisions are unlikely" ], "hex_length": 64, "fingerprint": "c436873ca9a49169e5451da0fe60f91f234454cf2e5b724b56813f979cb45274", "completeness": { "signals": [ "canvas_hash", "platform", "screen" ], "signals_max": 25, "signals_present": 3, "completeness_level": "sparse", "completeness_score": 12 }, "hash_algorithm": "HMAC-SHA256", "entropy_bits_per_char": 3.85, "estimated_entropy_bits": 247 } } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fingerprint": { "type": "string", "example": "c436873ca9a49169e5451da0fe60f91f234454cf2e5b724b56813f979cb45274", "x-required-group": "conditional" }, "signals": { "type": "object", "example": { "screen": { "width": 1920, "height": 1080 }, "canvas_hash": "abc" }, "x-required-group": "conditional" }, "ip": { "type": "string", "example": "8.8.8.8" }, "user_agent": { "type": "string", "example": "Mozilla/5.0 ..." }, "headers": { "type": "object", "example": { "Accept": "text/html" } }, "or `signals` (+ optional `ip`/`user_agent`/`headers`)": { "type": "string" } } } } } }, "x-required-groups": { "conditional": [ "fingerprint", "signals" ] }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true, "x-dakidarts-sample-response": { "notes": [ "high per-character entropy - collisions are unlikely" ], "hex_length": 64, "fingerprint": "c436873ca9a49169e5451da0fe60f91f234454cf2e5b724b56813f979cb45274", "completeness": { "signals": [ "canvas_hash", "platform", "screen" ], "signals_max": 25, "signals_present": 3, "completeness_level": "sparse", "completeness_score": 12 }, "hash_algorithm": "HMAC-SHA256", "entropy_bits_per_char": 3.85, "estimated_entropy_bits": 247 } } }, "/compare": { "get": { "summary": "Compare Route", "description": "Compares two fingerprints \u2014 either two hashes (match verdict) or two signal sets (Jaccard similarity + same-device verdict). Useful for account-takeover & device-swap detection.", "operationId": "device-fingerprint-bot-detection_get_compare", "tags": [ "Compare" ], "parameters": [ { "name": "fingerprint_a", "in": "query", "required": true, "description": "First fingerprint hash.", "schema": { "type": "string", "example": "c436873ca9a49169e5451da0fe60f91f..." }, "example": "c436873ca9a49169e5451da0fe60f91f..." }, { "name": "fingerprint_b", "in": "query", "required": true, "description": "Second fingerprint hash.", "schema": { "type": "string", "example": "4863c2cbe782e713fc5bd059d9adc2c3..." }, "example": "4863c2cbe782e713fc5bd059d9adc2c3..." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "description": "Dynamic source value; no concrete response example is published." }, "result": { "description": "Dynamic source value; no concrete response example is published." }, "entropy_a": { "description": "Dynamic source value; no concrete response example is published." }, "entropy_b": { "description": "Dynamic source value; no concrete response example is published." }, "identical": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_a": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_b": { "description": "Dynamic source value; no concrete response example is published." } }, "additionalProperties": true } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true }, "post": { "summary": "Compare Route", "description": "Compares two fingerprints \u2014 either two hashes (match verdict) or two signal sets (Jaccard similarity + same-device verdict). Useful for account-takeover & device-swap detection.", "operationId": "device-fingerprint-bot-detection_post_compare", "tags": [ "Compare" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "description": "Dynamic source value; no concrete response example is published." }, "result": { "description": "Dynamic source value; no concrete response example is published." }, "entropy_a": { "description": "Dynamic source value; no concrete response example is published." }, "entropy_b": { "description": "Dynamic source value; no concrete response example is published." }, "identical": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_a": { "description": "Dynamic source value; no concrete response example is published." }, "fingerprint_b": { "description": "Dynamic source value; no concrete response example is published." } }, "additionalProperties": true } } } }, "4XX": { "description": "Client error" }, "5XX": { "description": "Upstream or gateway error" }, "503": { "description": "No live upstream is configured. Sample responses are preview-only." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fingerprint_a": { "type": "string", "example": "c436873ca9a49169e5451da0fe60f91f..." }, "fingerprint_b": { "type": "string", "example": "4863c2cbe782e713fc5bd059d9adc2c3..." } }, "required": [ "fingerprint_a", "fingerprint_b" ] } } } }, "x-dakidarts-execution-status": "source-only", "x-dakidarts-source-contract": true, "x-dakidarts-sample-response": { "method": "signals", "verdict": "likely_same_device", "only_in_a": [ "fonts" ], "only_in_b": [], "shared_signals": [ "canvas_hash", "platform", "screen" ], "matching_values": [ "canvas_hash", "platform" ], "differing_values": [ "screen" ], "jaccard_similarity": 0.75 } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } }, "security": [ { "ApiKeyAuth": [] } ] }