REST API v1 · api.antivpn.tech · V8 Volatile Isolate Runtime

Sentinel Edge Intelligence API Reference

Evaluate inbound IP connections in sub-millisecond volatile memory before completing TCP/TLS handshakes or processing application request bodies.

Step 1

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.

bash — cURL Evaluation
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 .
Public Showcase Key: You can run zero-cost evaluations against real endpoints without an account using: stl_test_showcase_demo.
Security

2. Authentication & Credentials

All requests to api.antivpn.tech must be authenticated using your Universal License Key (stl_live_...).

Standard Authorization Header (Recommended)

Authorization: Bearer stl_live_your_api_key_here

Custom Header Equivalent

X-Sentinel-Key: stl_live_your_api_key_here

Query Parameter Fallback

For legacy game server plugins or Webhooks where custom request headers cannot be configured:

https://api.antivpn.tech/v1/check?ip=1.1.1.1&key=stl_live_your_api_key_here
Payload Specification

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.

JSON — Complete Edge Verdict Payload
{
  "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:

0.99 Confidence Deterministic

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).

0.95 Confidence Carrier Classified

Mobile cellular networks with dynamic CGNAT pooling, or recognized gaming route accelerators (e.g. ExitLag). Requires whitelist preservation for legitimate gamers.

0.88 Confidence Behavioral Anomaly

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.
Policy Triggers

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
REST Endpoints

5. Endpoints Specification

POST /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.

Request Body (application/json):
{ "ip": "185.213.154.20" }
GET /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.

Parameters:
  • ip (string, required): Explicit IPv4 or IPv6 string.
GET /v1/check

Automatically detects and evaluates the inbound caller's connection from edge proxy headers (CF-Connecting-IP, X-Forwarded-For).

GET /v1/license/status

Returns the authenticated license key's current tier, monthly allotment, and remaining check balance.

POST /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.

Request Body (application/json):
{ "ips": ["185.213.154.20", "8.8.8.8"] }
Response (application/json):
{ "count": 2, "results": [ { "ip": "185.213.154.20", "action": "BLOCK" }, { "ip": "8.8.8.8", "action": "ALLOW" } ] }
GET /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.

Web Integration Snippet:
<script src="https://api.antivpn.tech/v1/sentinel.js"></script>
<script>
  const verdict = await Sentinel.verify({ key: "stl_live_your_api_key_here" });
  if (verdict.action === "BLOCK") { console.warn("Restricted connection detected"); }
</script>
GET /healthz

Global Anycast edge liveness probe. Returns HTTP 200 OK ({"status": "ok"}). No authentication required.

Response Metadata

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.
Status Codes & Quotas

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.
Resilience Pattern

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.

javascript — Node / Express Fail-Open Middleware
// 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();
  }
}
Reverse Proxy Security Warning: Never trust 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', ...)).
Implementation Pattern

9. Graduated Defense Policy Recipe

Take full advantage of confidence and reason_codes to separate deterministic datacenter/VPN drops from residential proxies:

javascript — Multi-Tier Graduated Enforcement
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" };
}
Specification & Stability

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.

Non-breaking additive schema extensions only

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.