> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catproxy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Прокси

> Создание, настройка и удаление прокси-листов. Необходимые разрешения: proxies:read и/или proxies:write.

<Info>
  Полные схемы запросов и ответов, а также возможность тестирования эндпоинтов доступны в [Swagger UI](https://api.catproxy.io/swagger/index.html).
</Info>

***

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

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

```http theme={null}
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`

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.catproxy.io/v1/proxy \
    -H "X-API-Key: cat_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

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

***

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

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

```http theme={null}
POST /v1/proxy
```

**Тело запроса**

| Поле                 | Тип        | Обязательное | Описание                                                                                             |
| :------------------- | :--------- | :----------- | :--------------------------------------------------------------------------------------------------- |
| `name`               | string     | Да           | Имя прокси. Только строчные буквы, цифры и знаки подчёркивания. Нельзя изменить после создания.      |
| `proxy_type`         | string     | Да           | `residential` или `mobile`                                                                           |
| `tariff_id`          | integer    | Да           | ID тарифного плана. Доступные планы: [GET /v1/plans](/ru/public-api/balance#get-plans).              |
| `countries`          | integer\[] | Нет          | Список ID стран для таргетинга. ID стран: [GET /v1/geo/countries](/ru/public-api/geo#get-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`

<CodeGroup>
  ```bash cURL theme={null}
  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
      }
    }'
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

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

```json theme={null}
{
  "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"
  }
}
```

***

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

Возвращает полные сведения об одном прокси-листе.

```http theme={null}
GET /v1/proxy/{id}
```

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

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

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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.catproxy.io/v1/proxy/86Rf07 \
    -H "X-API-Key: cat_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

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

***

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

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

```http theme={null}
PUT /v1/proxy/{id}
```

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

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

**Тело запроса**

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

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

***

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

Мягкое удаление прокси-листа. Прокси немедленно перестаёт принимать подключения.

```http theme={null}
DELETE /v1/proxy/{id}
```

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

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

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

```bash theme={null}
curl -X DELETE https://api.catproxy.io/v1/proxy/86Rf07 \
  -H "X-API-Key: cat_YOUR_API_KEY"
```

***

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

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

```http theme={null}
PUT /v1/proxy/{id}/limits
```

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

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

**Тело запроса**

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

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

```bash theme={null}
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-адресам из этого списка.

```http theme={null}
PUT /v1/proxy/{id}/whitelist
```

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

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

**Тело запроса**

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

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

```bash theme={null}
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"]}'
```

***

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

Возвращает список целевых хостов, к которым данный прокси разрешено подключаться. Пустой список означает отсутствие ограничений.

```http theme={null}
GET /v1/proxy/{id}/target-hosts-whitelist
```

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

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

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

```bash theme={null}
curl https://api.catproxy.io/v1/proxy/86Rf07/target-hosts-whitelist \
  -H "X-API-Key: cat_YOUR_API_KEY"
```

***

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

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

```http theme={null}
POST /v1/proxy/{id}/target-hosts-whitelist
```

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

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

**Тело запроса**

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

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

```bash theme={null}
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"]}'
```

***

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

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

```http theme={null}
POST /v1/proxy/{id}/password
```

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

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

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

```bash theme={null}
curl -X POST https://api.catproxy.io/v1/proxy/86Rf07/password \
  -H "X-API-Key: cat_YOUR_API_KEY"
```

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

```json theme={null}
{
  "result": true,
  "data": {
    "id": "86Rf07",
    "password": "newpassword123"
  }
}
```