> ## Documentation Index
> Fetch the complete documentation index at: https://vpn-docs.wxapros.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference Overview

> Endpoint inventory and conventions.

## Base URL

```
https://wxaintel.wxapros.com/api/v1/vpn
```

The wxaintel gateway proxies `/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}`](/api-reference/lookup-ip)                        | Single IP classification                  | Free       |
| `POST` | [`/ip/batch`](/api-reference/lookup-batch)                    | Batch up to 100 IPs (max 100 per request) | Starter    |
| `GET`  | [`/shadow_vpn/lookup/{ip}`](/api-reference/shadow-vpn-lookup) | Shadow VPN / RAI assets on an IP          | Enterprise |

### Aggregates

| Method | Path                                                    | Description                                                | Min tier |
| ------ | ------------------------------------------------------- | ---------------------------------------------------------- | -------- |
| `GET`  | [`/stats`](/api-reference/stats)                        | Global classification counts                               | Free     |
| `GET`  | [`/providers`](/api-reference/providers)                | All known providers + IP counts                            | Free     |
| `GET`  | [`/stats/country/{code}`](/api-reference/country-stats) | Per-country VPN concentrators                              | Business |
| `GET`  | [`/stats/asn-abuse`](/api-reference/asn-abuse-stats)    | ASN abuse leaderboard (premium columns stripped below Pro) | Free     |

### Bulk exports

| Method | Path                                               | Description            | Min tier |
| ------ | -------------------------------------------------- | ---------------------- | -------- |
| `GET`  | [`/export/csv`](/api-reference/export-csv)         | Full dataset, CSV      | Pro      |
| `GET`  | [`/export/mmdb`](/api-reference/export-mmdb)       | MaxMind-style database | Business |
| `GET`  | [`/export/parquet`](/api-reference/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`

Reserved and non-global ranges return `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](https://github.com/whois-api-llc/wxa_vpn/blob/main/CONTRACT.md))
are stable. Field availability depends on tier — see [tiers](/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 to `false` below the **pro** tier. (The base
  `is_residential_proxy` boolean is shown to all tiers.)
* `provider` (and operator name) is `null` below the **starter** tier.

Note that `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 with `Z` suffix:
`2026-04-28T17:23:00Z`. They reflect UTC.