Sub-User Groups API — ProxyHat API Documentation

GET /v1/sub-user-groups Requires Auth

List Groups

Retrieve all sub-user groups associated with the authenticated account. Returns an array of group objects including the number of sub-users in each group.

curl https://api.proxyhat.com/v1/sub-user-groups \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"

import requests

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

groups = response.json()["payload"]
for group in groups:
    print(f"{group[\"name\"]} — {group[\"sub_users_count\"]} sub-users")

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

const { payload: groups } = await response.json();
groups.forEach(g => console.log(`${g.name} — ${g.sub_users_count} sub-users`));

req, _ := http.NewRequest("GET", "https://api.proxyhat.com/v1/sub-user-groups", 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["payload"])

Response 200

{
  "success": true,
  "payload": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production",
      "description": "Production proxies",
      "sub_users_count": 5,
      "created_at": "2026-01-20T10:00:00Z"
    }
  ],
  "meta": {},
  "errors": [],
  "description": ""
}

Response

POST /v1/sub-user-groups Requires Auth

Create Group

Create a new sub-user group. After creating a group, you can assign sub-users to it by updating the sub-user's sub_user_group_id field.

Request Body

Name	Type	Required	Description
name	string	Required	The display name for the group.
description	string	Optional	An optional description of the group's purpose.

curl -X POST https://api.proxyhat.com/v1/sub-user-groups \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Development",
    "description": "Dev environment proxies"
  }'

import requests

response = requests.post(
    "https://api.proxyhat.com/v1/sub-user-groups",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={
        "name": "Development",
        "description": "Dev environment proxies",
    },
)

group = response.json()["payload"]
print(f"Created: {group[\"name\"]}")

const response = await fetch("https://api.proxyhat.com/v1/sub-user-groups", {
  method: "POST",
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({
    name: "Development",
    description: "Dev environment proxies",
  }),
});

const { payload: group } = await response.json();
console.log(`Created: ${group.name}`);

payload := strings.NewReader(`{
  "name": "Development",
  "description": "Dev environment proxies"
}`)

req, _ := http.NewRequest("POST", "https://api.proxyhat.com/v1/sub-user-groups", payload)
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"])

Response 201

{
  "success": true,
  "payload": {
    "id": "660f9500-f30c-52e5-b827-557766550000",
    "name": "Development",
    "description": "Dev environment proxies",
    "sub_users_count": 0,
    "created_at": "2026-01-25T14:30:00Z"
  },
  "meta": {},
  "errors": [],
  "description": ""
}

Request Body (JSON)

Response

GET /v1/sub-user-groups/{sub_user_group} Requires Auth

Get Group

Retrieve a single sub-user group by its ID. Returns the group object along with an array of sub-users that belong to the group.

Path Parameters

Name	Type	Required	Description
sub_user_group	string	Required	The UUID of the group to retrieve.

curl https://api.proxyhat.com/v1/sub-user-groups/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"

import requests

group_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.get(
    f"https://api.proxyhat.com/v1/sub-user-groups/{group_id}",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
)

group = response.json()["payload"]
print(f"{group[\"name\"]} — {len(group[\"sub_users\"])} sub-users")

const groupId = "550e8400-e29b-41d4-a716-446655440000";

const response = await fetch(`https://api.proxyhat.com/v1/sub-user-groups/${groupId}`, {
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Accept": "application/json",
  },
});

const { payload: group } = await response.json();
console.log(`${group.name} — ${group.sub_users.length} sub-users`);

groupID := "550e8400-e29b-41d4-a716-446655440000"
url := fmt.Sprintf("https://api.proxyhat.com/v1/sub-user-groups/%s", groupID)

req, _ := http.NewRequest("GET", 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["payload"])

Response 200

{
  "success": true,
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production",
    "description": "Production proxies",
    "sub_users_count": 5,
    "created_at": "2026-01-20T10:00:00Z",
    "sub_users": [
      {
        "uuid": "770a0600-g41d-63f6-c938-668877660000",
        "proxy_username": "user_abc123",
        "lifecycle_status": "Active",
        "name": "Main proxy"
      }
    ]
  },
  "meta": {},
  "errors": [],
  "description": ""
}

sub_user_group (path)

Response

PUT /v1/sub-user-groups/{sub_user_group} Requires Auth

Update Group

Update an existing sub-user group's name or description. Only the fields you include in the request body will be updated.

Path Parameters

Name	Type	Required	Description
sub_user_group	string	Required	The UUID of the group to update.

Request Body

Name	Type	Required	Description
name	string	Optional	A new display name for the group.
description	string	Optional	A new description for the group.

curl -X PUT https://api.proxyhat.com/v1/sub-user-groups/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Staging",
    "description": "Staging environment proxies"
  }'

import requests

group_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.put(
    f"https://api.proxyhat.com/v1/sub-user-groups/{group_id}",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={
        "name": "Staging",
        "description": "Staging environment proxies",
    },
)

group = response.json()["payload"]
print(f"Updated: {group[\"name\"]}")

const groupId = "550e8400-e29b-41d4-a716-446655440000";

const response = await fetch(`https://api.proxyhat.com/v1/sub-user-groups/${groupId}`, {
  method: "PUT",
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({
    name: "Staging",
    description: "Staging environment proxies",
  }),
});

const { payload: group } = await response.json();
console.log(`Updated: ${group.name}`);

groupID := "550e8400-e29b-41d4-a716-446655440000"
url := fmt.Sprintf("https://api.proxyhat.com/v1/sub-user-groups/%s", groupID)

payload := strings.NewReader(`{
  "name": "Staging",
  "description": "Staging environment proxies"
}`)

req, _ := http.NewRequest("PUT", url, payload)
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"])

Response 200

{
  "success": true,
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Staging",
    "description": "Staging environment proxies",
    "sub_users_count": 5,
    "created_at": "2026-01-20T10:00:00Z"
  },
  "meta": {},
  "errors": [],
  "description": ""
}

sub_user_group (path)

Request Body (JSON)

Response

DELETE /v1/sub-user-groups/{sub_user_group} Requires Auth

Delete Group

Delete a sub-user group by its ID. Any sub-users currently assigned to this group will have their group_id set to null. The sub-users themselves are not deleted.

Path Parameters

Name	Type	Required	Description
sub_user_group	string	Required	The UUID of the group to delete.

curl -X DELETE https://api.proxyhat.com/v1/sub-user-groups/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"

import requests

group_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.delete(
    f"https://api.proxyhat.com/v1/sub-user-groups/{group_id}",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
)

result = response.json()
print(f"Deleted: {result[\"success\"]}")

const groupId = "550e8400-e29b-41d4-a716-446655440000";

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

const result = await response.json();
console.log(`Deleted: ${result.success}`);

groupID := "550e8400-e29b-41d4-a716-446655440000"
url := fmt.Sprintf("https://api.proxyhat.com/v1/sub-user-groups/%s", groupID)

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["payload"])

Response 200

{
  "success": true,
  "payload": {
    "deleted": true
  },
  "meta": {},
  "errors": [],
  "description": ""
}

sub_user_group (path)

Response