> ## 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

> Create, configure, and delete proxy lists. Required scopes: proxies:read and/or proxies:write.

<Info>
  See the [Swagger UI](https://api.catproxy.io/swagger/index.html) for live request/response schemas and to try endpoints directly in your browser.
</Info>

***

## List proxies

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

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

<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>

***

## Create proxy

Provisions a new proxy list.

```http theme={null}
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](/public-api/balance#get-plans).                   |
| `countries`          | integer\[] | No       | List of country IDs to target. Get IDs from [GET /v1/geo/countries](/public-api/geo#get-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`

<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>

**Example response**

```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"
  }
}
```

***

## Get proxy

Returns full details for a single proxy list.

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

**Path parameters**

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

**Scope:** `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>

***

## Update proxy

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

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

<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>

***

## Delete proxy

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

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

**Path parameters**

| Parameter | Type   | Description   |
| :-------- | :----- | :------------ |
| `id`      | string | Proxy list ID |

**Scope:** `proxies:write`

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

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

```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
  }'
```

***

## Update IP whitelist

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

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

```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"]}'
```

***

## Get target hosts whitelist

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

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

**Path parameters**

| Parameter | Type   | Description   |
| :-------- | :----- | :------------ |
| `id`      | string | Proxy list ID |

**Scope:** `proxies:read`

```bash theme={null}
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`).

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

```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"]}'
```

***

## 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.

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

**Path parameters**

| Parameter | Type   | Description   |
| :-------- | :----- | :------------ |
| `id`      | string | Proxy list ID |

**Scope:** `proxies:write`

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

**Example response**

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