Proxy Descriptors API

Generate a ready-to-use proxy descriptor — a fully assembled connection string with host, port, username, and password — for one of your active sub-users. This is the recommended way to hand a downstream customer a working proxy: you pick the sub-user, protocol, geo-targeting, session behaviour, and AI filter, and the API returns a single url your customer can drop straight into any client. Responses are wrapped in the standard {success, payload, errors, description} envelope.

Generate Proxy Descriptor

curl -X POST https://api.proxyhat.com/v1/proxy-descriptors \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "sub_user_uuid": "7c9f2a1b-4d3e-4f5a-9b6c-1e2d3f4a5b6c",
    "protocol": "http",
    "location": { "country": "US", "region": "California", "city": "Los Angeles" },
    "session": { "mode": "sticky", "ttl": "30m" },
    "filter": "filter-medium"
  }'

import requests

response = requests.post(
    "https://api.proxyhat.com/v1/proxy-descriptors",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={
        "sub_user_uuid": "7c9f2a1b-4d3e-4f5a-9b6c-1e2d3f4a5b6c",
        "protocol": "http",
        "location": {"country": "US", "region": "California", "city": "Los Angeles"},
        "session": {"mode": "sticky", "ttl": "30m"},
        "filter": "filter-medium",
    },
)

descriptor = response.json()["payload"]
print(descriptor["url"])

const response = await fetch("https://api.proxyhat.com/v1/proxy-descriptors", {
  method: "POST",
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({
    sub_user_uuid: "7c9f2a1b-4d3e-4f5a-9b6c-1e2d3f4a5b6c",
    protocol: "http",
    location: { country: "US", region: "California", city: "Los Angeles" },
    session: { mode: "sticky", ttl: "30m" },
    filter: "filter-medium",
  }),
});

const { payload } = await response.json();
console.log(payload.url);

payload := map[string]interface{}{
    "sub_user_uuid": "7c9f2a1b-4d3e-4f5a-9b6c-1e2d3f4a5b6c",
    "protocol":      "http",
    "location":      map[string]string{"country": "US", "region": "California", "city": "Los Angeles"},
    "session":       map[string]string{"mode": "sticky", "ttl": "30m"},
    "filter":        "filter-medium",
}
body, _ := json.Marshal(payload)

req, _ := http.NewRequest("POST", "https://api.proxyhat.com/v1/proxy-descriptors", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer __API_KEY__")
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result struct {
    Payload struct {
        URL string `json:"url"`
    } `json:"payload"`
}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result.Payload.URL)

Two things that will surprise you

Response Fields

On success the payload carries everything a downstream client needs. Hand the customer either the ready-made url, or the individual host / port / username / password parts.

How the username is assembled

The username starts from the sub-user's base proxy username and appends tokens for each option you set:

• -country-<country> — always present; uses any when no country is given.
• -region-<region> — only when location.region is set.
• -city-<city> — only when location.city is set together with location.region. A city given without a region is refused with 422 rather than silently widened to the whole region or country.
• -isp-<isp> — only when location.isp is set.
• -type-mobile — only when connection_type is "mobile". "residential" (the default) adds no token.
• -ipv4-true — only when ipv4_only is true.
• -sid-<8-32-hex>-ttl-<ttl> — only when session.mode is sticky. A random 16-hex sid is generated if you don't supply one; ttl defaults to 30m. Set the window with either session.ttl ("30m"/"12h") or session.ttl_seconds (60-86400) — not both. The response's ttl_effective_seconds reports the window actually granted, since an arbitrary second count can be truncated on the way to the humanized ttl string.
• -<filter> — the filter tier (e.g. -filter-medium); omitted entirely when filter is none.

Send location codes, not display names. Values are passed through to the gateway exactly as you supply them, apart from being lower-cased — so use the code field from the locations endpoints (los_angeles, comcast_cable), not the human label ("Los Angeles", "Comcast Cable"). Codes legitimately contain characters like ., (, ) and / (for example the real ISP codes cbvision_s.a. and telenor_a/s), and these reach the gateway intact.

Two characters are refused with a 422 rather than rewritten: a hyphen, because - separates the username's tokens and a value containing one would inject an extra token into your credential; and whitespace, which no real location code contains and which almost always means a display name was sent instead of a code.

The returned username and password are the literal credential — use those. The url field is a convenience rendering and percent-encodes its user:pass@ section, so a code containing :, @ or / cannot re-cut the host and port; decode it with any standard URL parser. For the full grammar and how to build these usernames yourself, see Connecting to the Proxy.