Integration and operations

API

Every page is backed by an endpoint. Same contract, same fields.

The interface is built on the same API that is published. Every endpoint, parameter, response and error is described in the OpenAPI 3.1 specification, /api/v1/openapi.yaml — load it into Swagger UI, Postman or a client generator. Responses conform to it, and the test suite checks every one against it; no richer internal format exists.

Endpoint	Returns
`GET /api/v1/ip/{ip}`	Verdict for one address
`GET /api/v1/prefix/{cidr}`	Prefix with providers inside it
`GET /api/v1/asn/{asn}`	Network with provider distribution
`GET /api/v1/asn/{asn}/networks`	Every prefix of a network, filterable and paged
`GET /api/v1/org/{id}`	AS organisation as one network, and its ASNs
`GET /api/v1/org/{id}/networks`	Every prefix of an organisation, filterable and paged
`GET /api/v1/country/{cc}`	Networks and providers located in a country
`GET /api/v1/countries`	Every country with known exits
`GET /api/v1/service/{tag}`	Provider profile
`GET /api/v1/service/{tag}/networks`	Every network a provider exits from, paged
`POST /api/v1/bulk`	Many addresses, with a summary
`GET /api/v1/search?q=`	Resolve free text to an entity
`GET /api/v1/sources`	Feed provenance, licences and freshness — administrators only
`GET /api/v1/services`	Every provider at a glance: addresses, prefixes, networks, countries
`GET /api/v1/ip/{ip}/history`	Every week of an address
`GET /api/v1/prefix/{cidr}/addresses`	Every address of a prefix, in a window, filterable
`GET /api/v1/prefix/{cidr}/timeline`	Daily probing of a prefix
`GET /api/v1/suggest?q=`	Suggestions as you type
`GET /api/v1/meta`	Dataset version, counts, coverage — no key needed
`GET /api/v1/openapi.yaml`	This API's OpenAPI 3.1 specification — no key needed

Every response carries its own provenance

datasetVersion on every response. Do not interpret a result without it.
confidence and evidence accompany every claim.
No pre-filtering. The consuming system applies its own threshold.
degraded is set when part of the answer could not be produced, so a partial response is identifiable as such.

A lookup with a session cookie

curl -s --cookie 'vpndb_session=...' \
  https://vpndb.example/api/v1/asn/9009 | jq '.attribution[:3]'

Every endpoint, with an example

Each endpoint below comes with an example request. Sign in to see its real answer from this installation. The complete contract: OpenAPI 3.1 specification.

Single lookups

GET/api/v1/ip/{ip}Who operates an address

Ask: One IPv4 address. The most common call: an address from a log, an alert or a report, and the question which VPN or proxy service runs it.

Answer: anonymous and types (VPN, TOR, RELAY …), attribution — each provider with its weight (share of the days it was seen, recent days counting more), its confidence (0–3) and the methods behind it — and evidence with first and last sighting, observation count and confidenceBasis, the computation behind the confidence in one sentence. network, asn and location say where it sits; latest names the most recent provider where it is not the leader; feeds lists external lists naming it. An address we never saw but whose announced prefix we know is answered by interpolation (method: interpolated). A miss is a 404 with a reason, never an all-clear.

Example request

curl -s "https://staging.vpndb.io/api/v1/ip/37.120.237.182" \
  -H "Authorization: Bearer $VPNDB_KEY"

GET/api/v1/ip/{ip}/historyEvery week of an address

Ask: The record of one address week by week since probing began — for an incident months ago, the week governs, not today's verdict.

Answer: weeks: each week's status (probe, scan, interpolated, none), its providers with weights, the days seen and the probes; providers summarises who held the address and when. Network, ASN and country come from the local tables even for an address with no evidence at all.

Example request

curl -s "https://staging.vpndb.io/api/v1/ip/37.120.237.182/history" \
  -H "Authorization: Bearer $VPNDB_KEY"

GET/api/v1/prefix/{cidr}Any range, and who is inside it

Ask: Any IPv4 CIDR — an announced prefix or any other range. Every known exit address inside it counts, from our probing, the enriched snapshot and scan certificates together, each once.

Answer: observedIps, attribution by the provider of each address's most recent sighting, sources (how many addresses each source knows), prefixes.contained and prefixes.covering — the announced prefixes the range meets — networks (origin ASNs), countries by GeoIP share of the address space, and feeds.

Example request

curl -s "https://staging.vpndb.io/api/v1/prefix/37.19.196.0%2F23" \
  -H "Authorization: Bearer $VPNDB_KEY"

GET/api/v1/prefix/{cidr}/addressesEvery address of a prefix, in a window

Ask: The address table of a prefix for a time window: which addresses were used, by whom, through which tunnel — and the rest of each announced prefix by interpolation.

Answer: addresses a page at a time, each with its providers and their days, methods, pool, first and last seen; facets counts providers, methods and pools for the filters; observed, interpolated and total say how many there are; nextCursor continues.

from, to	The window, `yyyy-MM-dd`; default the last 30 days.
provider, method, pool	Filters; `method` takes several, comma-separated.
size, cursor	Page size (1–500) and continuation.

Example request

curl -s "https://staging.vpndb.io/api/v1/prefix/37.19.196.0%2F23/addresses?size=3" \
  -H "Authorization: Bearer $VPNDB_KEY"

GET/api/v1/prefix/{cidr}/timelineHow a prefix was probed, day by day

Ask: The daily probe activity of a range, to choose a window for the address table.

Answer: days with probe events and distinct addresses per day; firstSeen/lastSeen span every source.

Example request

curl -s "https://staging.vpndb.io/api/v1/prefix/37.19.196.0%2F23/timeline" \
  -H "Authorization: Bearer $VPNDB_KEY"

Networks, organisations and countries

GET/api/v1/asn/{asn}A network and its providers

Ask: One ASN: how much anonymising infrastructure it carries and whose.

Answer: observedIps, networkCount (prefixes), attribution — the provider distribution, each with addresses and share — singleTenant, infrastructureMix, collateral (what an ASN-wide block would hit), sources and aggregatedAt, when the union behind the figures was computed.

Example request

curl -s "https://staging.vpndb.io/api/v1/asn/9009" \
  -H "Authorization: Bearer $VPNDB_KEY"

GET/api/v1/asn/{asn}/networksEvery prefix of a network

Ask: All announced prefixes of an ASN that hold a known exit address — not only the busiest — to block or hunt precisely.

Answer: networks, each prefix with its size, known addresses and providers; total, matching, shared; nextCursor.

provider	Only prefixes this provider was seen in.
q	Part of a prefix, or `AS123`.
shared	`true`: only prefixes with several providers.
sort, size, cursor	`tenancy`, `addresses` or `address`; page size 1–500.

Example request

curl -s "https://staging.vpndb.io/api/v1/asn/9009/networks?size=3" \
  -H "Authorization: Bearer $VPNDB_KEY"

GET/api/v1/org/{id}A company and all its networks

Ask: An AS organisation by its CAIDA id (from /suggest) — the way in when a report names a hosting company rather than an ASN.

Answer: Every registered network (asns) with what we observed in each, and the organisation as one network: attribution across all its ASNs, providerCount, networkCount, observedAsns, collateral. sharesName warns when several organisations carry the same name.

Example request

curl -s "https://staging.vpndb.io/api/v1/org/ORG-DL201-RIPE" \
  -H "Authorization: Bearer $VPNDB_KEY"

GET/api/v1/org/{id}/networksEvery prefix of a company

Ask: The prefixes of all of an organisation's networks together, with the ASN announcing each.

Answer: The same list as for one network, across all its ASNs, with the same filters.

Example request

curl -s "https://staging.vpndb.io/api/v1/org/ORG-DL201-RIPE/networks?provider=nordvpn&size=3" \
  -H "Authorization: Bearer $VPNDB_KEY"

GET/api/v1/country/{cc}The infrastructure located in a country

Ask: A country by its two-letter code: which networks hold its exit addresses and which providers run there. A country is where DB-IP locates each address, not where its network is registered.

Answer: vpn and residential apart, each with observedIps, prefixes, providers (addresses, prefixes, share) and asns (addresses, prefixes, their three largest providers), largest first; unannouncedIps counts exits in no announced prefix.

Example request

curl -s "https://staging.vpndb.io/api/v1/country/DE" \
  -H "Authorization: Bearer $VPNDB_KEY"

GET/api/v1/countriesEvery country at a glance

Ask: All countries with known exit addresses — the data behind the world map.

Answer: countries, each with VPN exits, prefixes, providers, networks and residential exits, most VPN exits first.

Example request

curl -s "https://staging.vpndb.io/api/v1/countries" \
  -H "Authorization: Bearer $VPNDB_KEY"

Providers

GET/api/v1/service/{tag}A provider's profile

Ask: One provider by its tag (nordvpn, mullvad …): how large it is, where it runs and how current our view is.

Answer: status (ACTIVE, DEGRADED, DISCONTINUED), observedIps, networkCount and countries, geographicPresence by country, asns it exits from, the protocols seen, activity over time, coLocatedWith — providers sharing its networks — first and last sighting, and aggregatedAt.

Example request

curl -s "https://staging.vpndb.io/api/v1/service/nordvpn" \
  -H "Authorization: Bearer $VPNDB_KEY"

GET/api/v1/service/{tag}/networksEvery network a provider exits from

Ask: The reverse lookup for retro-hunting: all prefixes of one provider, to search a year of logs for them.

Answer: networks, each prefix with the provider's addresses there, a confidence and how many providers share it; nextCursor walks the whole set.

min_confidence	0–3; default 1.
size, cursor	Page size (1–1000) and continuation.

Example request

curl -s "https://staging.vpndb.io/api/v1/service/nordvpn/networks?size=3" \
  -H "Authorization: Bearer $VPNDB_KEY"

GET/api/v1/servicesEvery provider at a glance

Ask: The provider overview: all providers with their size.

Answer: providers, each with category (VPN or residential), exit addresses (all and last 30 days), prefixes, networks, countries, first and last sighting.

Example request

curl -s "https://staging.vpndb.io/api/v1/services" \
  -H "Authorization: Bearer $VPNDB_KEY"

Many addresses, search and the dataset

POST/api/v1/bulkMany addresses at once

Ask: Up to 10,000 addresses in one request — a log extract, an IOC list.

Answer: results, one row per address with provider, confidence, the computation behind it, method and last seen — the single lookup's answer, shortened; total, anonymous and unknown count the rows; byProvider and byAsn tally them.

Example request

curl -s -X POST "https://staging.vpndb.io/api/v1/bulk" \
  -H "Authorization: Bearer $VPNDB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips":["37.120.237.182","107.189.12.7","10.0.0.1"]}'

GET/api/v1/searchResolve free text

Ask: Any query — an address, a prefix, AS9009, a provider, a country — resolved to the entity it names.

Answer: resolvedAs and matches, each with a type, a label and the page it opens.

q	The query.

Example request

curl -s "https://staging.vpndb.io/api/v1/search?q=AS9009" \
  -H "Authorization: Bearer $VPNDB_KEY"

GET/api/v1/suggestSuggestions as you type

Ask: A partial name: providers, organisations, countries, networks, addresses.

Answer: suggestions, each with a type, a label, a note (country, networks, exits) and whether we hold observations behind it; more says how many are not shown.

q	What was typed.
limit	1–50, default 10.

Example request

curl -s "https://staging.vpndb.io/api/v1/suggest?q=nord&limit=3" \
  -H "Authorization: Bearer $VPNDB_KEY"

GET/api/v1/metaThe datasetno key needed

Ask: Version, size and freshness of the data — to cite with a result. No key needed.

Answer: datasetVersion, counts (exit addresses, providers, networks), coverage and freshness — what the data reaches and how current it is — and the external feeds loaded.

Example request

curl -s "https://staging.vpndb.io/api/v1/meta"

GET/api/v1/openapi.yamlThis specificationno key needed

Ask: The OpenAPI 3.1 document of the whole API, for Swagger UI, Postman or a client generator. No key needed.

Answer: YAML: every endpoint, parameter, response, error and both ways to authenticate.

Example request

curl -s "https://staging.vpndb.io/api/v1/openapi.yaml"

GET/api/v1/sourcesWhere the data comes fromadministrators only

Ask: Provenance of every external source, the pipeline's health and what was declined. Administrators only.

Answer: feeds with licence, clearance, age and records; health with each check's verdict; declined with the reason; notices that must ship with the data.

Example request

curl -s "https://staging.vpndb.io/api/v1/sources" \
  -H "Authorization: Bearer $VPNDB_KEY"

API

This page

All endpoints

API

Every response carries its own provenance

Every endpoint, with an example

Single lookups

Networks, organisations and countries

Providers

Many addresses, search and the dataset