Base URL
/api/v1/vpn/* to the WXA VPN backend. All
URLs in this reference are relative to the base.
Endpoint inventory
Lookup
| Method | Path | Description | Min tier |
|---|---|---|---|
GET | /ip/{ip} | Single IP classification | Free |
POST | /ip/batch | Batch up to 100 IPs (max 100 per request) | Starter |
GET | /shadow_vpn/lookup/{ip} | Shadow VPN / RAI assets on an IP | Enterprise |
Aggregates
| Method | Path | Description | Min tier |
|---|---|---|---|
GET | /stats | Global classification counts | Free |
GET | /providers | All known providers + IP counts | Free |
GET | /stats/country/{code} | Per-country VPN concentrators | Business |
GET | /stats/asn-abuse | ASN abuse leaderboard (premium columns stripped below Pro) | Free |
Bulk exports
| Method | Path | Description | Min tier |
|---|---|---|---|
GET | /export/csv | Full dataset, CSV | Pro |
GET | /export/mmdb | MaxMind-style database | Business |
GET | /export/parquet | Columnar Parquet | Business |
Conventions
IP format
Always use canonical string form. Both IPv4 and IPv6 are supported:- IPv4:
1.1.1.1 - IPv6:
2606:4700:4700::1111
400 invalid_ip_reserved — we don’t
classify them. This covers RFC 1918 private space, RFC 6598 / CGNAT, loopback,
multicast, link-local, and TEST-NET ranges (e.g. GET /api/v1/ip/0.0.0.0 →
400 invalid_ip_reserved).
Response shape
The pinned fields (see CONTRACT.md) are stable. Field availability depends on tier — see tiers. Tier-gated fields keep their keys present rather than being omitted — gate on your own tier, not on field presence:- The residential-attribution precision sub-flags
(
is_residential_proxy_high_confidence,is_residential_proxy_mobile) are always present but forced tofalsebelow the pro tier. (The baseis_residential_proxyboolean is shown to all tiers.) provider(and operator name) isnullbelow the starter tier.
asn_abuse and sanctions_risk are legitimately object-or-null
(present as null when there is no data, regardless of tier) — that null
is a real “no data” signal, not a tier strip.
Caching
Aggregate endpoints (/stats, /providers, /stats/country/*,
/stats/asn-abuse) are server-side cached for 60 s – 5 min. The
Cache-Control header reflects this. Lookup endpoints are not cached
server-side — every request hits the live database.
Time
All timestamps are ISO 8601 withZ suffix:
2026-04-28T17:23:00Z. They reflect UTC.