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.

You never build the username by hand. The descriptor endpoint bakes the geo, session, and filter tokens into the username for you (e.g. -country-, -region-, -city-, -sid-, -ttl-, -filter-medium). If you would rather assemble the username yourself, see the raw connection grammar — but for handing a finished proxy to a customer, this endpoint is the safer path.

Generate Proxy Descriptor

POST /v1/proxy-descriptors Requires Auth

Generate Proxy Descriptor

Build a ready-to-use proxy descriptor for one of your active sub-users. The sub-user must belong to your account and be in the "active" lifecycle state, otherwise the endpoint returns 404. Geo-targeting, session stickiness, and the AI filter are all optional; the returned username has every requested token pre-assembled.

We filled these in for you: sub_user_uuid auto protocol location.country session.mode filter

Tweak any value if you like — or just press Try.

Request Body

Name	Type	Required	Description
sub_user_uuid	uuid	Required	UUID of the sub-user to generate the descriptor for. Must be a sub-user you own whose lifecycle_status is "active".
protocol	string	Required	Proxy protocol. One of "http" or "socks5". Determines the returned port (8080 for http, 1080 for socks5).
location	object	Optional	Optional geo-targeting object. Omit for a random location (the username uses country "any").
location.country	string	Optional	Country to target, e.g. "US". Max 32 chars. Slugified into the -country- token; defaults to "any" when omitted.
location.region	string	Optional	Region/state to target, e.g. "California". Max 128 chars. Adds a -region- token.
location.city	string	Optional	City to target, e.g. "Los Angeles". Max 128 chars. Adds a -city- token.
session	object	Optional	Optional session-control object. Omit for a rotating (per-request) IP.
session.mode	string	Optional	Session mode: "rotating" (default — new IP each request) or "sticky" (hold one IP). Only "sticky" adds -sid-/-ttl- tokens.
session.ttl	string	Optional	Sticky-session lifetime. One of "30m" or "12h". Defaults to "30m". Only applied when mode is "sticky".
session.id	string	Optional	Sticky-session identifier: exactly 16 hexadecimal characters. If omitted while mode is "sticky", a random 16-hex id is generated for you.
filter	string	Optional	AI filter tier. One of "filter-high", "filter-high-speed-fast", "filter-medium", "filter-medium-speed-fast", or "none". Defaults to "filter-medium". "none" leaves the filter token off entirely.

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)

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.

payload

Field	Type	Description
provider_id	string	Always `"proxyhat"`.
sub_user_uuid	uuid	The sub-user this descriptor was generated for.
protocol	string	Echoes the requested protocol (`http` or `socks5`).
filter	string	The applied AI filter (defaults to `filter-medium` when not specified).
host	string	Gateway hostname — always `gate.proxyhat.com`.
port	integer	`8080` for http, `1080` for socks5.
username	string	The sub-user's proxy username with all geo, session, and filter tokens baked in.
password	string	The sub-user's proxy password.
url	string	Fully assembled connection URL: `protocol://username:password@host:port`.
host_socks5	string	Convenience `host:port` string for SOCKS5 (`gate.proxyhat.com:1080`), regardless of the requested protocol.
host_http	string	Convenience `host:port` string for HTTP (`gate.proxyhat.com:8080`), regardless of the requested protocol.

Sub-user must be active and yours. If sub_user_uuid does not match an active sub-user owned by the authenticated account, the endpoint returns 404 in the standard envelope: { "success": false, "payload": null, "errors": ["Sub-user not found"], "description": "Sub-user not found" }. Suspended, deleting, or deleted sub-users are treated the same as non-existent.

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.
-sid-<16-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.
-<filter> — the filter tier (e.g. -filter-medium); omitted entirely when filter is none.

Location values are slugified (lower-cased, non-alphanumeric runs collapsed to _), so "Los Angeles" becomes los_angeles. For the full grammar and how to build these usernames yourself, see Connecting to the Proxy.