Catproxy Developer Documentation

See the Swagger UI for live request/response schemas and to try endpoints directly in your browser.

List proxies

Returns all proxy lists owned by the authenticated user with full details: tariff, limits, traffic usage, and settings.

GET /v1/proxy

Query parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status. Comma-separated: `active,pending`
`search`	string	No	Partial name match (case-insensitive)
`limit`	integer	No	Items per page. Default: `100`
`page`	integer	No	Page number starting from `0`. Default: `0`
`order`	string	No	Sort direction: `asc` or `desc`. Default: `desc`
`order_by`	string	No	Sort field: `name`, `status`, `tariff.name`, `traffic_used.total_used`, `total_spent`, `created_at`
`statistic_from`	string	No	Start date for traffic statistics period (`YYYY-MM-DD`)
`statistic_to`	string	No	End date for traffic statistics period (`YYYY-MM-DD`)

Scope: proxies:read

curl https://api.catproxy.io/v1/proxy \
  -H "X-API-Key: cat_YOUR_API_KEY"

import requests

r = requests.get(
    "https://api.catproxy.io/v1/proxy",
    headers={"X-API-Key": "cat_YOUR_API_KEY"}
)
print(r.json())

Create proxy

Provisions a new proxy list.

POST /v1/proxy

Request body

Field	Type	Required	Description
`name`	string	Yes	Proxy name. Lowercase letters, digits, and underscores only. Immutable after creation.
`proxy_type`	string	Yes	`residential` or `mobile`
`tariff_id`	integer	Yes	Plan ID. Get available plans from GET /v1/plans.
`countries`	integer[]	No	List of country IDs to target. Get IDs from GET /v1/geo/countries.
`description`	string	No	Human-readable label
`ip_whitelist`	string[]	No	IP addresses allowed to connect to this proxy
`limits`	object	No	Spending or traffic limits (see below)
`limits.limit_type`	string	No	`money` or `traffic`
`limits.time_period`	string	No	`daily` or `monthly`
`limits.total_limit`	number	No	Limit value. For `money` - USD. For `traffic` - bytes.

Scope: proxies:write

curl -X POST https://api.catproxy.io/v1/proxy \
  -H "X-API-Key: cat_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myproxylist01",
    "proxy_type": "residential",
    "tariff_id": 1,
    "countries": [84],
    "description": "My personal proxy list",
    "ip_whitelist": ["192.168.1.1"],
    "limits": {
      "limit_type": "money",
      "time_period": "monthly",
      "total_limit": 100
    }
  }'

import requests

r = requests.post(
    "https://api.catproxy.io/v1/proxy",
    headers={"X-API-Key": "cat_YOUR_API_KEY"},
    json={
        "name": "myproxylist01",
        "proxy_type": "residential",
        "tariff_id": 1,
        "countries": [84],
        "description": "My personal proxy list"
    }
)
print(r.json())

Example response

{
  "result": true,
  "data": {
    "id": "86Rf07",
    "name": "myproxylist01",
    "description": "My personal proxy list",
    "host": "proxy.catproxy.io",
    "port": 5555,
    "password": "1jw9j7zwwur",
    "status": "active",
    "type": "residential",
    "user_id": 123,
    "created_at": "2026-01-01T10:00:00Z",
    "updated_at": "2026-01-01T10:00:00Z"
  }
}

Get proxy

Returns full details for a single proxy list.

GET /v1/proxy/{id}

Path parameters

Parameter	Type	Description
`id`	string	Proxy list ID (e.g. `86Rf07`)

Scope: proxies:read

curl https://api.catproxy.io/v1/proxy/86Rf07 \
  -H "X-API-Key: cat_YOUR_API_KEY"

import requests

r = requests.get(
    "https://api.catproxy.io/v1/proxy/86Rf07",
    headers={"X-API-Key": "cat_YOUR_API_KEY"}
)
print(r.json())

Update proxy

Updates settings for an existing proxy list. Only fields included in the request body are changed.

PUT /v1/proxy/{id}

Path parameters

Parameter	Type	Description
`id`	string	Proxy list ID

Request body

Field	Type	Description
`countries`	integer[]	Replace the country targeting list
`description`	string	Update the description
`status`	string	Proxy status, e.g. `active`
`ip_whitelist`	string[]	Replace the IP whitelist
`limits`	object	Update spending or traffic limits

Scope: proxies:write

curl -X PUT https://api.catproxy.io/v1/proxy/86Rf07 \
  -H "X-API-Key: cat_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "countries": [84],
    "description": "Updated description",
    "status": "active"
  }'

import requests

r = requests.put(
    "https://api.catproxy.io/v1/proxy/86Rf07",
    headers={"X-API-Key": "cat_YOUR_API_KEY"},
    json={"description": "Updated description", "status": "active"}
)
print(r.json())

Delete proxy

Soft-deletes a proxy list. The proxy stops accepting connections immediately.

DELETE /v1/proxy/{id}

Path parameters

Parameter	Type	Description
`id`	string	Proxy list ID

Scope: proxies:write

curl -X DELETE https://api.catproxy.io/v1/proxy/86Rf07 \
  -H "X-API-Key: cat_YOUR_API_KEY"

Update proxy limits

Sets or replaces the spending or traffic limit for a proxy list.

PUT /v1/proxy/{id}/limits

Path parameters

Parameter	Type	Description
`id`	string	Proxy list ID

Request body

Field	Type	Required	Description
`limit_type`	string	Yes	`money` (USD) or `traffic` (bytes)
`time_period`	string	Yes	`daily` or `monthly`
`total_limit`	number	Yes	The limit value

Scope: proxies:write

curl -X PUT https://api.catproxy.io/v1/proxy/86Rf07/limits \
  -H "X-API-Key: cat_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit_type": "money",
    "time_period": "monthly",
    "total_limit": 100
  }'

Update IP whitelist

Replaces the full IP whitelist for a proxy list. Only IPs on this list are allowed to connect.

PUT /v1/proxy/{id}/whitelist

Path parameters

Parameter	Type	Description
`id`	string	Proxy list ID

Request body

Field	Type	Required	Description
`ips`	string[]	Yes	Full replacement list of authorized IPv4 addresses. Send an empty array to clear.

Scope: proxies:write

curl -X PUT https://api.catproxy.io/v1/proxy/86Rf07/whitelist \
  -H "X-API-Key: cat_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["1.2.3.4"]}'

Get target hosts whitelist

Returns the list of target hosts this proxy is allowed to connect to. An empty list means no restriction.

GET /v1/proxy/{id}/target-hosts-whitelist

Path parameters

Parameter	Type	Description
`id`	string	Proxy list ID

Scope: proxies:read

curl https://api.catproxy.io/v1/proxy/86Rf07/target-hosts-whitelist \
  -H "X-API-Key: cat_YOUR_API_KEY"

Set target hosts whitelist

Replaces the target hosts whitelist. When set, the proxy will only forward traffic to the listed hosts. Supports wildcards (e.g. *.example.com).

POST /v1/proxy/{id}/target-hosts-whitelist

Path parameters

Parameter	Type	Description
`id`	string	Proxy list ID

Request body

Field	Type	Required	Description
`target_hosts`	string[]	Yes	Full replacement list. Send an empty array to remove the restriction.

Scope: proxies:write

curl -X POST https://api.catproxy.io/v1/proxy/86Rf07/target-hosts-whitelist \
  -H "X-API-Key: cat_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_hosts": ["example.com"]}'

Regenerate password

Generates a new password for a proxy list and invalidates the old one. All active connections using the old password will be dropped.

POST /v1/proxy/{id}/password

Path parameters

Parameter	Type	Description
`id`	string	Proxy list ID

Scope: proxies:write

curl -X POST https://api.catproxy.io/v1/proxy/86Rf07/password \
  -H "X-API-Key: cat_YOUR_API_KEY"

Example response

{
  "result": true,
  "data": {
    "id": "86Rf07",
    "password": "newpassword123"
  }
}

​List proxies

​Create proxy

​Get proxy

​Update proxy

​Delete proxy

​Update proxy limits

​Update IP whitelist

​Get target hosts whitelist

​Set target hosts whitelist

​Regenerate password

List proxies

Create proxy

Get proxy

Update proxy

Delete proxy

Update proxy limits

Update IP whitelist

Get target hosts whitelist

Set target hosts whitelist

Regenerate password