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

# Публичный API

> Автоматизируйте управление прокси, отслеживайте трафик и запрашивайте геоданные через REST API Catproxy.

Публичный API Catproxy предоставляет программный доступ ко всему, что доступно в дашборде: создание и настройка прокси, отслеживание использования, управление балансом и поиск геоданных - всё через HTTPS с JSON.

<CardGroup cols={2}>
  <Card title="Интерактивный Swagger UI" icon="code" href="https://api.catproxy.io/swagger/index.html">
    Изучайте и тестируйте каждый эндпоинт прямо в браузере.
  </Card>

  <Card title="Коллекция Postman" icon="circle-down" href="/downloads/catproxy-public-api.postman_collection.json" download>
    Импортируйте готовую коллекцию и начните делать запросы за несколько минут.
  </Card>
</CardGroup>

***

## Базовый URL

Все запросы к API отправляются на:

```
https://api.catproxy.io
```

***

## Аутентификация

API использует **API-ключи**, передаваемые в заголовке запроса. Каждый запрос должен содержать:

```http theme={null}
X-API-Key: cat_YOUR_API_KEY
```

**Как получить API-ключ:**

1. Откройте [Панель управления](https://catproxy.io/app) и перейдите в раздел **API-ключи** в боковом меню.
2. Нажмите **Создать API‑ключ** и выберите необходимые разрешения.
3. Скопируйте ключ - он отображается только один раз.

<Warning>
  API-ключи являются секретными данными. Не коммитьте их в репозиторий и не используйте в клиентском коде. При утечке ключа немедленно его отзовите.
</Warning>

### Разрешения

Каждый API-ключ содержит одно или несколько разрешений, ограничивающих доступ к группам эндпоинтов. Запрашивайте только те разрешения, которые нужны вашей интеграции.

| Разрешение      | Предоставляет доступ к                                            |
| :-------------- | :---------------------------------------------------------------- |
| `proxies:read`  | Просмотр списков прокси и их настроек                             |
| `proxies:write` | Создание, изменение и удаление прокси                             |
| `stats:read`    | Просмотр статистики трафика и экспорт отчётов об использовании    |
| `balance:read`  | Просмотр баланса аккаунта, истории транзакций и доступных тарифов |
| `geo:read`      | Доступ к геокаталогу (страны, штаты, города, ZIP‑коды)            |

`proxies:write` **не включает** `proxies:read` - разрешения независимы.

***

## Формат запроса

Для эндпоинтов, принимающих тело запроса (`POST`, `PUT`), отправляйте JSON и указывайте заголовок `Content-Type`:

```http theme={null}
Content-Type: application/json
```

***

## Формат ответа

Все ответы возвращаются в виде JSON со стандартной обёрткой:

```json theme={null}
{
  "result": true,
  "data": { ... },
  "error": "",
  "error_type": "",
  "meta": {}
}
```

| Поле         | Тип            | Описание                                         |
| :----------- | :------------- | :----------------------------------------------- |
| `result`     | boolean        | `true` при успехе, `false` при ошибке            |
| `data`       | object / array | Полезная нагрузка ответа                         |
| `error`      | string         | Читаемое сообщение об ошибке (пустое при успехе) |
| `error_type` | string         | Машиночитаемый код ошибки (пустой при успехе)    |
| `meta`       | object         | Пагинация и прочие метаданные                    |

***

## Обработка ошибок

Ответы с ошибками используют стандартные HTTP-коды статуса:

```json theme={null}
{
  "result": false,
  "error": "API key not found or expired",
  "error_type": "unauthorized"
}
```

| HTTP-статус        | Значение                                                   |
| :----------------- | :--------------------------------------------------------- |
| `400 Bad Request`  | Некорректный запрос - проверьте тело запроса или параметры |
| `401 Unauthorized` | Отсутствующий или недействительный API-ключ                |
| `403 Forbidden`    | Действительный ключ, но недостаточно разрешений            |
| `404 Not Found`    | Запрошенный ресурс не существует                           |

***

## Быстрый пример

Получите список всех своих прокси одним запросом `curl`:

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

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