Skip to content
VPNDetection

Download

get/api/v1/database/download

Redirects (302) to a time-limited link to the database file. The link only has to be valid when the download starts, so a long one isn't cut off when it expires.

Authorization

apiKeyQueryapikey in query

?apikey=<key>. Convenient in a browser; prefer a header elsewhere.

apiKeyHeaderX-Api-Key in header

X-Api-Key: <key>.

bearerAuthbearer token

Authorization: Bearer <key>.

Query parameters

idrequiredstring

Dataset ID, e.g. vpn_ip_extended_v1

formatrequired"csvgz" | "mmdb"

Not every database is built in every format. The _provider catalogs are keyed by provider ID rather than by IP range, so no MMDB exists for them.

buildstring

One build of the database, by the name a database.updated webhook gives it, so the file is the one whose sha256 the webhook carries. Without it, the build that is live.

Match ^[0-9]{8}\.[a-z0-9]{6}$ · Example 20261105.0t53s5

Responses

302

Follow the Location header to object storage

400application/json

The database is not built in the requested format (INVALID_FORMAT), or build is not a build's name (INVALID_BUILD)

rcrequiredstring
TypeScript type
ts
{
  rc: string;
}
401application/json

Missing or invalid key, or the key lacks the db.download scope

rcrequiredstring
TypeScript type
ts
{
  rc: string;
}
403application/json

Your organization holds no license for this database, or its term has ended

rcrequiredstring
TypeScript type
ts
{
  rc: string;
}
404application/json

No such database

rcrequiredstring
TypeScript type
ts
{
  rc: string;
}
410application/json

The build named in build is no longer kept (BUILD_GONE); builds are kept 7 days. Download without build for the live one

rcrequiredstring
TypeScript type
ts
{
  rc: string;
}
503application/json

Licensed, but today's copy has not been published yet

rcrequiredstring
TypeScript type
ts
{
  rc: string;
}