API Documentation
Quick Start
Base URL: https://api.blackicehq.com
Authentication: X-API-Key header
curl -X POST https://api.blackicehq.com/analyze \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{"events":[{"user_id":"usr-001","timestamp":"2026-03-19T01:30:00Z","ip_address":"185.220.101.5","action":"login"}]}'
Endpoints
POST /analyze
Main fraud detection endpoint
{
"events": [EventObject]
}
EventObject fields:
- user_id (required)
- timestamp (required, ISO8601)
- ip_address (required)
- action (optional)
- device_id (optional)
- geo (optional)
- country (optional)
Response: summary, results[], usage
POST /access/request
Request API key
{
"email": "...",
"first_name": "...",
"last_name": "...",
"company": "...",
"job_title": "...",
"company_size": "...",
"industry": "...",
"use_case": "..."
}
POST /api/verify-token
Verify sandbox token
{
"token": "your_token"
}
Detection Rules
| Rule | Weight | Description |
|---|---|---|
| session_hijack | 0.85 | IP or device changed mid-session |
| impossible_travel | 0.80 | Geographically impossible location change |
| tor_exit | 0.75 | Connection via TOR anonymous network |
| ip_reuse | 0.70 | One IP used by multiple accounts |
| device_reuse | 0.70 | One device used by multiple accounts |
| repeated_failure | 0.65 | Multiple failed login attempts |
| login_payment_pattern | 0.65 | Login immediately followed by payment |
| velocity_spike | 0.55 | Unusually high action frequency |
| multiple_ips | 0.45 | Multiple IPs for single user |
| low_and_slow | 0.45 | Rare distributed actions over time |
| geo_ip_mismatch | 0.50 | IP country ≠ profile country |
| suspicious_hour | 0.25 | Activity between 1AM-5AM UTC |
| new_device | 0.20 | Unrecognized device |
Response Format
{
"verdict": "block",
"risk_score": 0.94,
"rules_fired": ["session_hijack", "tor_exit"],
"evidence_list": [
"IP changed mid-session",
"Connection via TOR exit node"
],
"narrative": "Session hijack detected: user logged in from a new device and TOR network."
}
Verdict Thresholds
- block — risk_score >= 0.75
- stepup — risk_score >= 0.50
- allow — risk_score < 0.50
Trial Limits
- 30 days free or 10,000 events
- After trial: $0.002/event