Catproxy Developer Documentation

Полные схемы запросов и ответов, а также возможность тестирования эндпоинтов доступны в Swagger UI.

Список прокси

Возвращает все прокси-листы аутентифицированного пользователя с полными деталями: тариф, лимиты, использование трафика и настройки.

GET /v1/proxy

Параметры запроса

Параметр	Тип	Обязательный	Описание
`status`	string	Нет	Фильтр по статусу. Через запятую: `active,pending`
`search`	string	Нет	Частичное совпадение по имени (без учёта регистра)
`limit`	integer	Нет	Элементов на страницу. По умолчанию: `100`
`page`	integer	Нет	Номер страницы начиная с `0`. По умолчанию: `0`
`order`	string	Нет	Направление сортировки: `asc` или `desc`. По умолчанию: `desc`
`order_by`	string	Нет	Поле сортировки: `name`, `status`, `tariff.name`, `traffic_used.total_used`, `total_spent`, `created_at`
`statistic_from`	string	Нет	Начальная дата периода статистики трафика (`YYYY-MM-DD`)
`statistic_to`	string	Нет	Конечная дата периода статистики трафика (`YYYY-MM-DD`)

Разрешение: 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())

Создать прокси

Создаёт новый прокси-лист.

POST /v1/proxy

Тело запроса

Поле	Тип	Обязательное	Описание
`name`	string	Да	Имя прокси. Только строчные буквы, цифры и знаки подчёркивания. Нельзя изменить после создания.
`proxy_type`	string	Да	`residential` или `mobile`
`tariff_id`	integer	Да	ID тарифного плана. Доступные планы: GET /v1/plans.
`countries`	integer[]	Нет	Список ID стран для таргетинга. ID стран: GET /v1/geo/countries.
`description`	string	Нет	Описание прокси
`ip_whitelist`	string[]	Нет	IP-адреса, которым разрешено подключение к этому прокси
`limits`	object	Нет	Лимиты расходов или трафика (см. ниже)
`limits.limit_type`	string	Нет	`money` или `traffic`
`limits.time_period`	string	Нет	`daily` или `monthly`
`limits.total_limit`	number	Нет	Значение лимита. Для `money` - USD. Для `traffic` - байты.

Разрешение: 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())

Пример ответа

{
  "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 /v1/proxy/{id}

Параметры пути

Параметр	Тип	Описание
`id`	string	ID прокси-листа (например, `86Rf07`)

Разрешение: 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())

Обновить прокси

Обновляет настройки существующего прокси-листа. Изменяются только поля, переданные в теле запроса.

PUT /v1/proxy/{id}

Параметры пути

Параметр	Тип	Описание
`id`	string	ID прокси-листа

Тело запроса

Поле	Тип	Описание
`countries`	integer[]	Заменить список стран таргетинга
`description`	string	Обновить описание
`status`	string	Статус прокси, например `active`
`ip_whitelist`	string[]	Заменить белый список IP
`limits`	object	Обновить лимиты расходов или трафика

Разрешение: 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 /v1/proxy/{id}

Параметры пути

Параметр	Тип	Описание
`id`	string	ID прокси-листа

Разрешение: proxies:write

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

Обновить лимиты прокси

Устанавливает или заменяет лимит расходов или трафика для прокси-листа.

PUT /v1/proxy/{id}/limits

Параметры пути

Параметр	Тип	Описание
`id`	string	ID прокси-листа

Тело запроса

Поле	Тип	Обязательное	Описание
`limit_type`	string	Да	`money` (USD) или `traffic` (байты)
`time_period`	string	Да	`daily` или `monthly`
`total_limit`	number	Да	Значение лимита

Разрешение: 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
  }'

Обновить белый список IP

Полностью заменяет белый список IP для прокси-листа. Подключение разрешено только IP-адресам из этого списка.

PUT /v1/proxy/{id}/whitelist

Параметры пути

Параметр	Тип	Описание
`id`	string	ID прокси-листа

Тело запроса

Поле	Тип	Обязательное	Описание
`ips`	string[]	Да	Полный список разрешённых IPv4-адресов. Передайте пустой массив для очистки.

Разрешение: 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 /v1/proxy/{id}/target-hosts-whitelist

Параметры пути

Параметр	Тип	Описание
`id`	string	ID прокси-листа

Разрешение: proxies:read

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

Установить белый список целевых хостов

Полностью заменяет белый список целевых хостов. При наличии списка прокси будет передавать трафик только на указанные хосты. Поддерживаются маски (например, *.example.com).

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

Параметры пути

Параметр	Тип	Описание
`id`	string	ID прокси-листа

Тело запроса

Поле	Тип	Обязательное	Описание
`target_hosts`	string[]	Да	Полный список хостов. Передайте пустой массив для снятия ограничения.

Разрешение: 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"]}'

Сгенерировать новый пароль

Генерирует новый пароль для прокси-листа и аннулирует старый. Все активные подключения со старым паролем будут разорваны.

POST /v1/proxy/{id}/password

Параметры пути

Параметр	Тип	Описание
`id`	string	ID прокси-листа

Разрешение: proxies:write

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

Пример ответа

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

​Список прокси

​Создать прокси

​Получить прокси

​Обновить прокси

​Удалить прокси

​Обновить лимиты прокси

​Обновить белый список IP

​Получить белый список целевых хостов

​Установить белый список целевых хостов

​Сгенерировать новый пароль

Список прокси

Создать прокси

Получить прокси

Обновить прокси

Удалить прокси

Обновить лимиты прокси

Обновить белый список IP

Получить белый список целевых хостов

Установить белый список целевых хостов

Сгенерировать новый пароль