Catalog, locations, and proxy generation

Packages describe what can be sold. Orders describe access already purchased or assigned. Location endpoints describe what the selected package can target now.

A package can combine multiple compatible upstream or privately operated sources when its configured providers support the required gateway protocol. Product labels are commercial; actual targeting and protocol capabilities come from the package catalog and eligible upstreams.

Packages

Product definitions, pricing-related metadata, and targeting capabilities available to the authenticated account.

Orders

Active account or user access, credentials, and data context tied to a package.

Locations

Continents, countries, regions, cities, ASNs, and ISPs available for a selected package.

Generation

A request that combines eligible access with the chosen targeting to return ready-to-use proxy data.

DATA FLOW

Generate access from catalog state

1. 01

   Select a package

   Read package capabilities instead of assuming every product supports every target.

   GET /packages
2. 02

   Resolve access

   Read the main-user or sub-user orders and identify the active order for that package.

   GET /orders
3. 03

   Load targeting choices

   Retrieve countries first, then narrower location or network choices as the UI needs them.

   GET /locations/countries
4. 04

   Validate the intersection

   Keep package, order, and location identifiers from the same deployment context.

5. 05

   Generate proxy data

   Send the documented package/order and targeting fields, then store only what the customer must receive.

   POST /proxies/generate

Generate your first connection

Complete one of the owner or reseller quickstarts first. You need usable access, not only a visible package. Replace {api_host}, {api_key} and {package_id} with your values.

−+×

RequestGET /locations/countries

cURL

curl 'https://{api_host}/api/v1/locations/countries' \
  --get \
  --header 'Authorization: Static {api_key}' \
  --data-urlencode 'package_id={package_id}'

JS / TS

import { ProxyRequestClient } from "@proxyrequest/sdk";

const client = ProxyRequestClient.withApiKey(
  "{api_key}", { baseUrl: "https://{api_host}/api/v1" }
);

const result = await client.locations.listCountries({
  packageId: "{package_id}",
});

Python

from uuid import UUID
from proxyrequest_sdk import Client

with Client.with_api_key(
    "{api_key}", base_url="https://{api_host}/api/v1"
) as client:
    result = client.locations.list_countries(
        package_id=UUID("{package_id}"),
    )

PHP

<?php
require __DIR__ . '/vendor/autoload.php';

use ProxyRequest\Client;

$client = Client::withApiKey(
    '{api_key}', 'https://{api_host}/api/v1'
);

$result = $client->locations()->listCountries(
    packageId: '{package_id}',
);

−+×

Response200 OK

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "us",
      "code": "us",
      "count": 100,
      "name": "United States",
      "original_name": "United States",
      "isps": [],
      "asns": []
    }
  ]
}

Replace placeholders in braces with your values. Responses use synthetic example data.Install SDKsAPI reference →

Country, region, and city list and detail responses always contain asns, which defaults to an empty array. Request include_asns=true to populate it. In JavaScript and PHP SDK calls, the option is named includeAsns; in Python it is include_asns (SDK 4.1.0 or later).

−+×

RequestGET /locations/countries

cURL

curl 'https://{api_host}/api/v1/locations/countries' \
  --get \
  --header 'Authorization: Static {api_key}' \
  --data-urlencode 'package_id={package_id}' \
  --data-urlencode 'include_asns=true'

JS / TS

import { ProxyRequestClient } from "@proxyrequest/sdk";

const client = ProxyRequestClient.withApiKey(
  "{api_key}", { baseUrl: "https://{api_host}/api/v1" }
);

const result = await client.locations.listCountries({
  packageId: "{package_id}",
  includeAsns: true,
});

Python

from uuid import UUID
from proxyrequest_sdk import Client

with Client.with_api_key(
    "{api_key}", base_url="https://{api_host}/api/v1"
) as client:
    result = client.locations.list_countries(
        package_id=UUID("{package_id}"),
        include_asns=True,
    )

PHP

<?php
require __DIR__ . '/vendor/autoload.php';

use ProxyRequest\Client;

$client = Client::withApiKey(
    '{api_key}', 'https://{api_host}/api/v1'
);

$result = $client->locations()->listCountries(
    packageId: '{package_id}',
    includeAsns: true,
);

−+×

Response200 OK

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "us",
      "code": "us",
      "count": 100,
      "name": "United States",
      "original_name": "United States",
      "isps": [],
      "asns": [
        {
          "code": "15169",
          "name": "Example network",
          "count": 100
        }
      ]
    }
  ]
}

Replace placeholders in braces with your values. Responses use synthetic example data.Install SDKsAPI reference →

That option does not affect the standalone /locations/asn endpoint or compact proxy-node responses. The standalone ASN list always returns country_codes, while geo is empty by default. Request include_geo=true when you need detailed country, region, or city scopes. SDK 4.3.0 exposes this as includeGeo in JavaScript and PHP and include_geo in Python.

−+×

RequestPOST /proxies/generate

cURL

curl --request POST 'https://{api_host}/api/v1/proxies/generate' \
  --header 'Authorization: Static {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
  "package_id": "{package_id}",
  "quantity": 1,
  "connection": {
    "protocol": "http"
  }
}'

JS / TS

import { ProxyRequestClient } from "@proxyrequest/sdk";

const client = ProxyRequestClient.withApiKey(
  "{api_key}", { baseUrl: "https://{api_host}/api/v1" }
);

// Keep format tokens unchanged; the generator expands them.
const result = await client.proxies.generate({
  body: {
      "package_id": "{package_id}",
      "quantity": 1,
      "connection": {
          "protocol": "http",
          "format": "{protocol}://{username}:{password}@{host}:{port}"
      }
  },
});

Python

from proxyrequest_sdk.models import GenerateProxyRequest
from proxyrequest_sdk import Client

with Client.with_api_key(
    "{api_key}", base_url="https://{api_host}/api/v1"
) as client:
    result = client.proxies.generate(
        body=GenerateProxyRequest.from_dict({
            "package_id": "{package_id}",
            "quantity": 1,
            "connection": {
                "protocol": "http"
            }
        }),
    )

PHP

<?php
require __DIR__ . '/vendor/autoload.php';

use ProxyRequest\Client;
use ProxyRequest\Dto\GenerateProxyRequest;
use ProxyRequest\Dto\ProxyGenerationConnectionRequest;

$client = Client::withApiKey(
    '{api_key}', 'https://{api_host}/api/v1'
);

$result = $client->proxies()->generate(
    generateProxyRequest: new GenerateProxyRequest([
        'packageId' => '{package_id}',
        'quantity' => 1,
        'connection' => new ProxyGenerationConnectionRequest([
            'protocol' => 'http'
        ])
    ]),
);

−+×

Response201 Created

{
  "count": 1,
  "proxies": [
    {
      "host": "proxy.example.test",
      "port": 8000,
      "protocol": "http",
      "username": "package-elite",
      "password": "example-proxy-password",
      "connection_string": "http://package-elite:[email protected]:8000"
    }
  ]
}

Replace placeholders in braces with your values. Responses use synthetic example data.Install SDKsAPI reference →

The first request loads package-specific choices. Include package_id in location requests, including detail lookups such as GET /locations/countries/{id}: availability belongs to the selected package, not to a global account-wide catalog. The second request generates one rotating-eligible proxy for the authenticated account without narrowing its location. For a managed customer, also send its user_id; a package ID alone does not select that customer.

The target must be the caller’s own sub-user. Superuser status does not bypass this generation rule. For a top-level account, generate with that account’s own credential and omit user_id.

Generation returns 201 with count and a proxies array. Each entry includes host, port, protocol, username, password and connection_string. Use the returned connection string in a real proxy request as shown in the quickstarts; do not infer connectivity from generation success. Never log that response unredacted.

To request the United States, add targeting: { "country": "us" } only if the catalog supports it. For continent targeting, use targeting: { "continent": "eu" } and omit country, region, city, ASN and ISP. Region/city selections require their parent context. Catalog detail endpoints resolve selected identifiers; ASNs and ISPs provide network choices, not free-form labels.

Add session: { "ttl": 3600 } for generated sticky access; keep the returned session credentials for related requests. This is not a request to the unavailable /sessions management API. To use SOCKS, request connection.protocol: "socks5" and use a client supporting proxy-side DNS when required.

Package commissions are available through /packages/commissions for the permitted context. Use them for pricing/commission presentation, not to infer that the caller already owns data.

Cache the catalog safely

• Cache package and location lists by deployment and package context.
• Invalidate related locations when the selected package changes.
• Refresh after a generation validation error that indicates stale inventory.
• Do not call every location endpoint before every proxy request.
• Do not reuse catalog data across white-label deployments unless their IDs and configuration are proven identical.

Labels are presentation; IDs are integration

A location or network label can change formatting. Use the API-provided identifier or exact value required by the generation schema, and keep the label only for display.

Progressive location UI

1. Let the customer choose a package.
2. Load countries supported by that package.
3. Load regions only after a country is selected.
4. Load cities only when the workflow requires city precision.
5. Offer ASN filters as advanced network constraints with an availability warning.

For connection-string targeting after generation, see targeting. For provider eligibility and failure behavior, see routing and failures.

Filter the published location catalog

All location lists accept package_id, exact code and name, search, ordering, limit and offset. Regions, cities, ASNs and ISPs also accept country__code; cities accept region__code. Search is case-insensitive substring matching: separate terms with spaces or commas, or quote a phrase. Every term must match code or name. Ordering accepts comma-separated supported fields with - for descending order; use code or name for all lists. Follow the returned pagination links.

Countries, regions, cities, ASNs and ISPs accept optional min_count and max_count. Both boundaries are inclusive and either can be omitted:

curl --get 'https://{api_host}/api/v1/locations/countries' \
  --header 'Authorization: Static {api_key}' \
  --data-urlencode 'package_id={package_id}' \
  --data-urlencode 'min_count=50' \
  --data-urlencode 'max_count=500' \
  --data-urlencode 'include_asns=true'

Each record’s numeric count is its published node quantity; unknown quantities, including older dictionary data, are zero. The page envelope’s count is the number of matching records. These are dictionary quantities, not live healthy-node measurements or guaranteed available connections. For networks, a country filter also scopes the returned quantity.

Filtering precedes ordering and pagination. Nested ASN/ISP lists, geographic parents and ASN geo are not filtered by the bounds. Country, region and city detail requests accept the same bounds and return 404 when the selected record falls outside them. Continents do not apply node-count bounds.

Bounds must contain decimal digits from 0 through 18446744073709551615; surrounding whitespace is ignored. Empty values, signs, fractions, overflow and a minimum greater than the maximum return 400 with a detail message. Preserve large bounds as decimal text in query strings rather than rounding them through a JavaScript number.

For ASN queries, global=true selects globally targetable records only when country__code is absent. A country filter takes precedence. include_geo=true expands geographic scopes; it does not enable or disable geographic filtering. include_asns=true populates nested networks in geographic responses, independently of the standalone ASN list.

Successful searches identify the published snapshot in X-Locations-Generation and return Cache-Control: no-store. Each request uses one snapshot; separate pages can observe a newer generation. If building a consistent selection UI, clear dependent selections and reload when the generation changes. An unavailable or unready location index returns 503; retry later. There is no automatic fallback to a different catalog.