Proxy Presets API

Proxy presets are named, reusable snapshots of the Advanced Proxy Setup form. Each preset stores a data object with two sub-objects — form (connection, session, protocol and output settings) and location (country/region/city/ISP targeting) — so you can save a configuration once and reapply it later. Presets are scoped to the authenticated user, and each preset name must be unique within that account.

All Proxy Presets endpoints return the standard resource envelope: { "success", "payload", "errors", "description" }. On success payload holds the preset (or an array of presets); on failure success is false, errors holds the validation or error messages, and description is a human-readable summary.

A preset id is a UUID string (e.g. 3f0c8b1e-...), not an integer. There is no "get single preset" endpoint — GET /proxy-presets/{id} is not implemented. Use List Proxy Presets and match on id client-side.

The data object

Both create and update accept a data object. It must contain a form array and a location array, and every key listed below must be present — the service validates for the presence of each key and silently drops any key that is not on the allowed list. Values are stored verbatim; they are the same values the Advanced Setup form produces.

data.form keys

data.form

Name	Type	Required	Description
connectionType	string	Required	Exit pool type, e.g. "residential" or "mobile".
sessionType	string	Required	Session behaviour, e.g. "sticky" (pinned IP) or "rotating" (new IP per request).
sessionDuration	number	Required	Sticky-session duration as shown in the UI (e.g. minutes).
sessionDurationSec	number	Required	Sticky-session duration expressed in seconds.
protocol	string	Required	Connection protocol, e.g. "http" or "socks5".
outputFormat	string	Required	Credential output template, e.g. "host:port:user:pass".
template	string	Required	Selected output template identifier.
customTemplate	string	Required	Custom template string (empty string when a built-in template is used).
count	number	Required	Number of proxy lines to generate.
host	string	Required	Gateway host the generated proxies point at.
port	number	Required	Gateway port.
aiFilter	string	Required	AI quality/speed filter: "filter-high", "filter-medium", "filter-high-speed-fast", "filter-medium-speed-fast", or "none" to opt out.

data.location keys

data.location

Name	Type	Required	Description
country	string	Required	ISO country code (lowercased) or "any".
region	string	Required	State/region slug, or "any".
city	string	Required	City slug, or "any".
isp	string	Required	ISP slug, or "any".
zipcode	string	Required	ZIP/postal code, or empty string.

List Proxy Presets

GET /v1/proxy-presets Requires Auth

List Proxy Presets

Retrieve all proxy presets belonging to the authenticated user, ordered by creation date (newest first).

No input needed — runs live with your key

curl https://api.proxyhat.com/v1/proxy-presets \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://api.proxyhat.com/v1/proxy-presets",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
)

result = response.json()
for preset in result["payload"]:
    print(preset["id"], preset["name"])

const response = await fetch("https://api.proxyhat.com/v1/proxy-presets", {
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Accept": "application/json",
  },
});

const result = await response.json();
result.payload.forEach(p => console.log(p.id, p.name));

req, _ := http.NewRequest("GET", "https://api.proxyhat.com/v1/proxy-presets", nil)
req.Header.Set("Authorization", "Bearer __API_KEY__")
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 []map[string]interface{} `json:"payload"`
}
json.NewDecoder(resp.Body).Decode(&result)
for _, p := range result.Payload {
    fmt.Println(p["id"], p["name"])
}

Create Proxy Preset

POST /v1/proxy-presets Requires Auth

Create Proxy Preset

Create a new preset for the authenticated user. Returns 201 with the created preset. The name must be unique within your account — a duplicate name returns 422 with errors.name.

Example request: name data.form.connectionType data.location.country

Request Body

Name	Type	Required	Description
name	string	Required	Preset name. Max 100 characters, unique per user.
data	object	Required	Preset payload. Must contain form and location objects.
data.form	object	Required	Connection/session/output settings. See data.form keys above.
data.location	object	Required	Location targeting. See data.location keys above.

curl -X POST https://api.proxyhat.com/v1/proxy-presets \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "US residential sticky",
    "data": {
      "form": {
        "connectionType": "residential",
        "sessionType": "sticky",
        "sessionDuration": 10,
        "sessionDurationSec": 600,
        "protocol": "http",
        "outputFormat": "host:port:user:pass",
        "template": "default",
        "customTemplate": "",
        "count": 1,
        "host": "gate.proxyhat.com",
        "port": 8080,
        "aiFilter": "filter-medium"
      },
      "location": {
        "country": "us",
        "region": "any",
        "city": "any",
        "isp": "any",
        "zipcode": ""
      }
    }
  }'

import requests

payload = {
    "name": "US residential sticky",
    "data": {
        "form": {
            "connectionType": "residential",
            "sessionType": "sticky",
            "sessionDuration": 10,
            "sessionDurationSec": 600,
            "protocol": "http",
            "outputFormat": "host:port:user:pass",
            "template": "default",
            "customTemplate": "",
            "count": 1,
            "host": "gate.proxyhat.com",
            "port": 8080,
            "aiFilter": "filter-medium",
        },
        "location": {
            "country": "us",
            "region": "any",
            "city": "any",
            "isp": "any",
            "zipcode": "",
        },
    },
}

response = requests.post(
    "https://api.proxyhat.com/v1/proxy-presets",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
    json=payload,
)

print(response.json()["payload"]["id"])

const payload = {
  name: "US residential sticky",
  data: {
    form: {
      connectionType: "residential",
      sessionType: "sticky",
      sessionDuration: 10,
      sessionDurationSec: 600,
      protocol: "http",
      outputFormat: "host:port:user:pass",
      template: "default",
      customTemplate: "",
      count: 1,
      host: "gate.proxyhat.com",
      port: 8080,
      aiFilter: "filter-medium",
    },
    location: {
      country: "us",
      region: "any",
      city: "any",
      isp: "any",
      zipcode: "",
    },
  },
};

const response = await fetch("https://api.proxyhat.com/v1/proxy-presets", {
  method: "POST",
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify(payload),
});

const result = await response.json();
console.log(result.payload.id);

payload := map[string]interface{}{
    "name": "US residential sticky",
    "data": map[string]interface{}{
        "form": map[string]interface{}{
            "connectionType":     "residential",
            "sessionType":        "sticky",
            "sessionDuration":    10,
            "sessionDurationSec": 600,
            "protocol":           "http",
            "outputFormat":       "host:port:user:pass",
            "template":           "default",
            "customTemplate":     "",
            "count":              1,
            "host":               "gate.proxyhat.com",
            "port":               8080,
            "aiFilter":           "filter-medium",
        },
        "location": map[string]interface{}{
            "country": "us",
            "region":  "any",
            "city":    "any",
            "isp":     "any",
            "zipcode": "",
        },
    },
}

body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", "https://api.proxyhat.com/v1/proxy-presets", 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 map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["payload"])

Update Proxy Preset

PUT /v1/proxy-presets/{id} Requires Auth

Update Proxy Preset

Update a preset by its UUID, taken from the URL path. Both name and data are optional, but if you send data it must include both data.form and data.location. Returns the updated preset.

Example request: name

Path Parameters

Name	Type	Required	Description
id	string (UUID)	Required	The UUID of the preset to update.

Request Body

Name	Type	Required	Description
name	string	Optional	New preset name. Max 100 characters, unique per user.
data	object	Optional	New preset payload. When present, data.form and data.location are both required.
data.form	object	Optional	Required when data is supplied. See data.form keys above.
data.location	object	Optional	Required when data is supplied. See data.location keys above.

curl -X PUT https://api.proxyhat.com/v1/proxy-presets/3f0c8b1e-7d2a-4c9f-9e11-1a2b3c4d5e6f \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "US residential rotating"
  }'

import requests

preset_id = "3f0c8b1e-7d2a-4c9f-9e11-1a2b3c4d5e6f"

response = requests.put(
    f"https://api.proxyhat.com/v1/proxy-presets/{preset_id}",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
    json={"name": "US residential rotating"},
)

print(response.json()["payload"]["name"])

const presetId = "3f0c8b1e-7d2a-4c9f-9e11-1a2b3c4d5e6f";

const response = await fetch(`https://api.proxyhat.com/v1/proxy-presets/${presetId}`, {
  method: "PUT",
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({ name: "US residential rotating" }),
});

const result = await response.json();
console.log(result.payload.name);

presetID := "3f0c8b1e-7d2a-4c9f-9e11-1a2b3c4d5e6f"
url := fmt.Sprintf("https://api.proxyhat.com/v1/proxy-presets/%s", presetID)

body, _ := json.Marshal(map[string]string{"name": "US residential rotating"})
req, _ := http.NewRequest("PUT", url, 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 map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["payload"])

Delete Proxy Preset

DELETE /v1/proxy-presets/{id} Requires Auth

Delete Proxy Preset

Permanently delete a preset by its UUID, taken from the URL path. Returns success with a null payload.

Example request: id

Path Parameters

Name	Type	Required	Description
id	string (UUID)	Required	The UUID of the preset to delete.

curl -X DELETE https://api.proxyhat.com/v1/proxy-presets/3f0c8b1e-7d2a-4c9f-9e11-1a2b3c4d5e6f \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"

import requests

preset_id = "3f0c8b1e-7d2a-4c9f-9e11-1a2b3c4d5e6f"

response = requests.delete(
    f"https://api.proxyhat.com/v1/proxy-presets/{preset_id}",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
)

print(response.json()["description"])

const presetId = "3f0c8b1e-7d2a-4c9f-9e11-1a2b3c4d5e6f";

const response = await fetch(`https://api.proxyhat.com/v1/proxy-presets/${presetId}`, {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Accept": "application/json",
  },
});

const result = await response.json();
console.log(result.description);

presetID := "3f0c8b1e-7d2a-4c9f-9e11-1a2b3c4d5e6f"
url := fmt.Sprintf("https://api.proxyhat.com/v1/proxy-presets/%s", presetID)

req, _ := http.NewRequest("DELETE", url, nil)
req.Header.Set("Authorization", "Bearer __API_KEY__")
req.Header.Set("Accept", "application/json")

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

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["description"])