Sentinel Edge Intelligence API Reference
Evaluate inbound IP connections in sub-millisecond volatile memory before completing TCP/TLS handshakes or processing application request bodies.
1. Quickstart (3 Minutes)
Send an authenticated HTTP GET request to https://api.antivpn.tech/v1/check. Pass your target IP address in the ip query parameter.
curl -s -X GET "https://api.antivpn.tech/v1/check?ip=185.213.154.20" \ -H "Authorization: Bearer stl_live_your_api_key_here" \ -H "Accept: application/json" | jq .
stl_test_showcase_demo.
2. Authentication & Credentials
All requests to api.antivpn.tech must be authenticated using your Universal License Key (stl_live_...).
Standard Authorization Header (Recommended)
Custom Header Equivalent
Query Parameter Fallback
For legacy game server plugins or Webhooks where custom request headers cannot be configured:
3. Output Schema & Calibrated Confidence Scoring
Sentinel provides multi-dimensional, machine-actionable outputs. Instead of forcing your application into a fragile binary block, responses include an integer risk_score (0–100), a statistically calibrated confidence score (0.00–1.00), boolean flags (is_vpn, is_gaming_optimizer, is_privacy_relay), and both machine-readable reason_codes and human-readable reasons.
{
"ip": "185.213.154.20",
"action": "BLOCK",
"risk_score": 95,
"confidence": 0.99,
"threat_type": "Commercial VPN",
"is_vpn": true,
"is_gaming_optimizer": false,
"is_privacy_relay": false,
"asn": 206016,
"provider": "Mullvad VPN AB",
"hostname": "se-sto-wg-001.relays.mullvad.net",
"country": "SE",
"city": "Stockholm",
"region": "Stockholm County",
"timezone": "Europe/Stockholm",
"reason_codes": [
"CARRIER_COMMERCIAL_VPN",
"HOSTING_INFRASTRUCTURE_MATCH"
],
"reasons": [
"Carrier Network Classification: Commercial VPN (Mullvad VPN AB)",
"Subscriber Carrier Verification: Infrastructure Topology Match"
],
"execution_time_ms": 0.38,
"duration_ms": 0,
"dataset_sync_timestamp": "2026-10-09T03:55:00Z"
}
Calibrated Confidence Scoring Defined
Unlike uncalibrated raw heuristic scores, Sentinel's confidence metric represents the empirical posterior probability that the classification is correct. This enables mathematically sound policy thresholds:
Direct ASN registry matches, authoritative Tor exit directory relays, datacenter server subnets, or verified clean residential broadband. Immediate hard-kick is statistically safe (>99.9% precision).
Mobile cellular networks with dynamic CGNAT pooling, or recognized gaming route accelerators (e.g. ExitLag). Requires whitelist preservation for legitimate gamers.
Dynamic Tunnel & Gateway Behavioral Anomaly Detection on residential IP space. Graduated Defense recommended: soft-alert, challenge (2FA/CAPTCHA), or audit log rather than instant hard kick.
Field Dictionary
| Field | Type | Description |
|---|---|---|
| ip | string | The evaluated IPv4 or IPv6 address. |
| action | string | ALLOW, FLAG, or BLOCK based on standard baseline thresholds. |
| risk_score | integer (0–100) | Assessed threat severity. 0 = clean subscriber, 100 = active confirmed threat hop. |
| confidence | float (0.00–1.00) | Calibrated statistical posterior probability of the classification. Allows developers to tune sensitivity thresholds. |
| threat_type | string | Primary classification (e.g. Commercial VPN, Datacenter VPS, Residential Proxy, Tor Exit Node, Clean Residential). |
| is_vpn | boolean | Convenience boolean flag set to true if the connection represents an anonymizing proxy, VPN, or datacenter hop. |
| is_gaming_optimizer | boolean | True if traffic originates from a legitimate gaming network accelerator (e.g., ExitLag, WTFast, NoPing). Never blocked if whitelist is active. |
| is_privacy_relay | boolean | True if traffic originates from verified legitimate privacy relays (e.g., Apple iCloud Private Relay, Cloudflare WARP). Distinguishes privacy-conscious end-users from commercial threat actors. |
| reason_codes | array[string] | Standardized machine-readable triggers (e.g., CARRIER_COMMERCIAL_VPN) for programmatic rule matching. |
| reasons | array[string] | Human-readable explanatory strings for console logging and UI alerts. |
| asn | integer | Autonomous System Number (ASN) resolved via Carrier & Topology Intelligence. |
| provider | string | Carrier or ISP organization name associated with the Autonomous System. |
| hostname | string (nullable) | Reverse DNS (PTR) hostname sanitized with internal octet masking for privacy. |
| execution_time_ms / duration_ms | float / integer | Local in-memory isolate compute duration in milliseconds. Dual-supported for backward compatibility across all client SDKs. |
| dataset_sync_timestamp | ISO 8601 string | Timestamp when the active Global Threat Grid delta was synchronized into isolate memory. |
4. Standardized Reason Codes Catalog
Developers can write fine-grained application logic by inspecting the reason_codes array:
| Reason Code | Category | Typical Risk | Recommended Enforcement |
|---|---|---|---|
| CARRIER_COMMERCIAL_VPN | Commercial VPN | 85–100 | Immediate Handshake Drop or 403 Forbidden |
| HOSTING_INFRASTRUCTURE_MATCH | Datacenter VPS | 80–100 | Block automated scrapers & server hops |
| TOR_EXIT_NODE | Tor Anonymous Network | 100 | Strict Connection Refusal |
| RESIDENTIAL_TUNNEL_PROXY | Residential Proxy | 65–90 | Step-Up Challenge: Trigger MFA, CAPTCHA, or rate throttle |
| INGRESS_ANOMALY_TEMPORAL | Behavioral Anomaly | 50–75 | Log audit telemetry & monitor velocity |
| CARRIER_RESIDENTIAL_CLEAN | Consumer Broadband | 0–15 | Unrestricted Clean Pass |
| CARRIER_MOBILE_CELLULAR | Mobile 5G/LTE | 0–25 | Clean Pass with CGNAT Session Tolerance |
5. Endpoints Specification
/v1/check
Recommended for Zero-Log Hygiene
Evaluates an explicit target IP address transmitted via a JSON request body ({ "ip": "1.1.1.1" }).
Privacy Advantage: Sending the IP in the POST body ensures visitor IPs are never recorded in URL access logs, intermediate proxy access logs, or browser histories, preserving Sentinel's Zero-Log Volatile Memory Architecture.
/v1/check?ip={target_ip}
Evaluates an explicit target IPv4 or IPv6 address passed as a URL query parameter. Supported across all client libraries and legacy game server connectors.
ip(string, required): Explicit IPv4 or IPv6 string.
/v1/check
Automatically detects and evaluates the inbound caller's connection from edge proxy headers (CF-Connecting-IP, X-Forwarded-For).
/v1/license/status
Returns the authenticated license key's current tier, monthly allotment, and remaining check balance.
/v1/batch
High-Throughput Parallel Ingress
Evaluates up to 20 IPv4 or IPv6 addresses in a single request across the Sentinel Global Threat Grid with automatic address deduplication and concurrent subrequest safety. Each evaluated IP consumes exactly 1 check against your monthly license allotment.
/v1/sentinel.js
Zero-Dependency Browser SDK
Serves the lightweight, zero-dependency browser telemetry collector (<2KB gzipped). Dynamically inspects client-side temporal coherence, WebRTC interface routing integrity, and display virtualization before issuing an edge verification query.
<script>
const verdict = await Sentinel.verify({ key: "stl_live_your_api_key_here" });
if (verdict.action === "BLOCK") { console.warn("Restricted connection detected"); }
</script>
/healthz
Global Anycast edge liveness probe. Returns HTTP 200 OK ({"status": "ok"}). No authentication required.
6. Telemetry & Quota Response Headers
Every response from Sentinel includes real-time telemetry headers evaluated directly in volatile isolate RAM:
| Header | Example Value | Description |
|---|---|---|
| X-Sentinel-Tier | business | Active license plan tier. |
| X-Sentinel-Quota-Limit | 250000 | Total monthly evaluations allocated to key. |
| X-Sentinel-Quota-Remaining | 241820 | Checks remaining in active billing cycle. |
| X-Sentinel-Dataset-Sync | 2026-10-09T03:55:00Z | Timestamp of active Global Threat Grid synchronization. |
| X-Sentinel-Data-Age | 180s | Seconds elapsed since the latest micro-delta sync. |
| X-Sentinel-Execution-Time | 0.38ms | Local isolate execution duration in milliseconds. |
7. Errors, Quota Tiers & Rate Limit Behavior
Sentinel follows standard HTTP status conventions. Error payloads return structured JSON envelopes paired with real-time quota telemetry headers.
Tier Quota & Concurrency Matrix
| Tier | Monthly Allotment | Burst Concurrency | Overage / Quota Depletion |
|---|---|---|---|
Sandbox Demo (stl_test_showcase_demo) |
50 requests / day | 5 req / sec | Shared public rate limit; HTTP 429 when exhausted |
| Developer | 5,000 checks / mo | 15 req / sec | Soft-cap warning at <500 checks remaining; HTTP 403 on depletion |
| Starter | 150,000 checks / mo | 50 req / sec | $0.25 / 10k overage available; automatic billing rollover |
| Business | 1,000,000 checks / mo | 200 req / sec | $0.18 / 10k overage; priority edge isolate routing |
| Scale | 5,000,000 checks / mo | 1,000 req / sec | $0.10 / 10k overage; global multi-key orchestration |
| Enterprise | 20,000,000 checks / mo | Custom dedicated | $0.05 / 10k overage; 99.99% SLA & dedicated edge reflector |
HTTP Status Codes & Backoff Handling
| Status | Error Code | Trigger Condition | Client Recommended Action |
|---|---|---|---|
| 400 Bad Request | INVALID_IP_FORMAT | Supplied string is not valid IPv4 or IPv6 syntax. | Validate IP format before querying API. |
| 401 Unauthorized | INVALID_LICENSE_KEY | Authorization header is missing or key is unrecognized. | Check environment variable SENTINEL_API_KEY or configuration file. |
| 403 Forbidden | QUOTA_DEPLETED | Monthly check allotment has reached 0. | Fail-Open: Plugins default to open allow to avoid lockout. Upgrade tier at antivpn.tech. |
| 429 Rate Limited | RATE_LIMIT_EXCEEDED | Queries per second exceed burst concurrency, or daily sandbox cap reached. | Honor Retry-After header (seconds). Apply exponential backoff with jitter. |
| 500 / 503 Edge Error | EDGE_ISOLATE_TIMEOUT | Edge isolate timeout or temporary transit disruption. | Fail-Open: Forward traffic immediately to avoid user-facing downtime. |
8. Production Fail-Open Architecture
Security software should never create single points of failure. In production web applications and APIs, always wrap Sentinel calls in a fail-open handler: if network connectivity to the edge fails or times out, permit the connection and log a warning rather than locking out legitimate visitors.
// Configure Express trusted proxies to safely resolve req.ip:
app.set("trust proxy", "loopback, linklocal, uniquelocal");
async function sentinelGuard(req, res, next) {
// Use securely validated client IP (prevents header spoofing attacks)
const clientIP = req.ip || req.socket.remoteAddress;
try {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 1200); // 1.2s timeout
// Transmit via POST JSON body for heightened zero-log URL privacy
const resp = await fetch("https://api.antivpn.tech/v1/check", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.SENTINEL_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ ip: clientIP }),
signal: controller.signal
});
clearTimeout(timeout);
// Fail-open: Permit traffic on non-200 edge error or temporary rate limits
if (!resp.ok) return next();
const verdict = await resp.json();
if (verdict.action === "BLOCK" && verdict.confidence >= 0.95) {
return res.status(403).json({ error: "Access Denied: Untrusted Ingress Hop" });
}
next();
} catch (err) {
// Fail-open: Never disrupt legitimate user traffic if edge network is unreachable
console.warn(`[Sentinel Warning] Fail-open bypass for ${clientIP}: ${err.message}`);
next();
}
}
req.headers["cf-connecting-ip"] directly on servers open to the public web unless locked to Cloudflare's published IP ranges (via firewall rules or Authenticated Origin Pulls). On direct connections, attackers can spoof this header with clean residential IPs. Always rely on validated framework proxy settings (app.set('trust proxy', ...)).
9. Graduated Defense Policy Recipe
Take full advantage of confidence and reason_codes to separate deterministic datacenter/VPN drops from residential proxies:
function enforceIngressPolicy(verdict) {
// 1. Deterministic Hard Drop (Commercial VPNs, Hosting Scrapers, Tor)
if (verdict.risk_score >= 85 && verdict.confidence >= 0.95) {
return { decision: "DENY", status: 403 };
}
// 2. Probabilistic Step-Up Challenge (Residential Proxies & Tunnels)
if (verdict.reason_codes.includes("RESIDENTIAL_TUNNEL_PROXY")) {
return { decision: "CHALLENGE", action: "PROMPT_CAPTCHA_OR_MFA" };
}
// 3. Clean Connection: Allow without friction
return { decision: "PASS" };
}
10. OpenAPI 3.1 & Semantic Versioning Policy
Sentinel adheres to strict semantic API versioning to ensure zero unexpected breaking changes across production microservices, reverse proxies, and game server plugins.
Strict Backward Compatibility
All endpoints prefixed with /v1/ are covered by our backward-compatibility guarantee: existing schema fields (risk_score, action, is_vpn, duration_ms) will never be renamed, changed in data type, or removed within v1.
OpenAPI 3.1 Contract
Import our formal OpenAPI 3.1 contract directly into Postman, Insomnia, or code generators (Fern, Orval, OpenAPI Generator) for type-safe client generation in Go, Rust, TypeScript, or Python.