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.

Select a package
Read package capabilities instead of assuming every product supports every target.
GET /packages
Resolve access
Read the main-user or sub-user orders and identify the active order for that package.
GET /orders
Load targeting choices
Retrieve countries first, then narrower location or network choices as the UI needs them.
GET /locations/countries
Validate the intersection
Keep package, order, and location identifiers from the same deployment context.
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 'https://{api_host}/api/v1/locations/countries' \
  --get \
  --header 'Authorization: Static {api_key}' \
  --data-urlencode 'package_id={package_id}'

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}",
});

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
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",
      "name": "United States",
      "original_name": "United States",
      "isps": [],
      "asns": []
    }
  ]
}

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

RequestPOST /proxies/generate

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"
  }
}'

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}"
      }
  },
});

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
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 SDKs API 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.

Progressive location UI

Let the customer choose a package.
Load countries supported by that package.
Load regions only after a country is selected.
Load cities only when the workflow requires city precision.
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.

Catalog, locations, and proxy generation

Generate access from catalog state

Select a package

Resolve access

Load targeting choices

Validate the intersection

Generate proxy data

Generate your first connection

Cache the catalog safely

Progressive location UI