Catalog and geo

Scope: catalog:read.

GET /api/v1/products

What is on sale, priced for the key owner. The list holds only what can be bought right now; a slug outside the list answers 400 unknown_product.

Field	Meaning
slug	passed in product when quoting and buying: residential, ipv4
family	product kind: traffic_gateway (traffic) or dedicated (fixed addresses)
unit	unit of sale: gb or ip
unit_price	your price per gigabyte; for ipv4 - null, the price depends on the country and period
monthly_price_from	for ipv4: your lowest price of one address per month; for traffic - null
min_volume, volume_presets, volume_discounts	traffic purchase volume: minimum, hints for the interface, volume ladder in percent

The final amount is calculated by POST /api/v1/quote.

Product options

GET /api/v1/products/{product}/options - what can be chosen when buying fixed addresses. For the traffic product countries is empty: it is bought by volume only.

curl "https://ipv.rent/api/v1/products/ipv4/options" \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "type": "ipv4",
  "countries": [
    {
      "code": "us",
      "name": "United States",
      "periods": ["week", "2_weeks", "month", "2_months", "3_months"],
      "quantity_max": null,
      "plans": [
        {
          "id": "dc",
          "traffic_gb": null,
          "periods": ["week", "2_weeks", "month", "2_months", "3_months"],
          "operators": [
            {
              "id": "united-states",
              "name": "United States",
              "available": 374
            }
          ]
        }
      ]
    }
  ]
}

Field	Where it goes in the purchase	Meaning
countries[].code	country	country, ISO 3166-1 alpha-2
countries[].periods	period	terms the country is sold for
countries[].quantity_max	quantity	how many addresses one purchase can take; null - no separate limit
plans[].id	plan	plan; can be omitted if the country has only one
plans[].operators[].id	operator	location: the whole country or a city; required
plans[].operators[].available	-	how many addresses in the location are free right now

Re-read the options before buying rather than storing them on your side: the set of countries and the stock change.

Errors: 400 unknown_product (unknown slug or the product is not on sale).

Geo catalog

Residential only: where a traffic package can exit. Four levels, and each of them:

• takes a required product - today residential;
• supports If-None-Match and answers 304 with no body;
• returns version and ignores the case of codes.

ETag is an opaque hash of the version; the same version in readable form is the version field.

Route	Parameters	Response
GET /api/v1/geo/countries	product	countries[] with code, name, pool (thin | normal | deep)
GET /api/v1/geo/states	product, country	states[] with code and name
GET /api/v1/geo/cities	product, country, state (optional)	cities[] with code and name
GET /api/v1/geo/asns	product, country	asns[] with code and name

curl "https://ipv.rent/api/v1/geo/countries?product=residential" \
  -H 'Authorization: Bearer YOUR_API_KEY'

Without state, cities returns all cities of the country. A country that is no longer served gives an empty list, not an error.

Errors: 400 validation_failed (product or country not passed), unknown_product (unknown slug or the product is not on sale); 503 catalog_unavailable.

The codes from these responses are what geo accepts when issuing connections; a value outside the catalog gets 422 invalid_targeting.