Admin API: реестры блокировок

Восемь методов управляют тем же, что вкладка Настройки → Реестр PL: списками заблокированных доменов, их проверкой и журналом автозамен. Всем методам нужен токен с доступом Полный доступ (full).

Авторизация описана на странице Admin API: обзор и авторизация, формат запросов и общие коды ошибок — на странице Формат запросов, ответов и ошибок. Как работает автозамена — на странице Реестр блокировок (PL) и автозамена домена.

Объект реестра

Методы списка, создания, изменения и проверки возвращают реестр в таком виде:

{
  "id": "5b1f0c1e-6f0a-4d0e-9a3b-2c7d8e9f0a11",
  "workspace_id": "0d9c8b7a-1234-4abc-8def-001122334455",
  "name": "Реестр PL",
  "url": "https://registry.example.com/domains.txt",
  "geo": "PL",
  "enabled": true,
  "auto_replace": true,
  "interval_min": 30,
  "reserve_group_id": "7a6b5c4d-3e2f-4a1b-8c9d-0e1f2a3b4c5d",
  "last_fetch_at": "2026-10-04T09:30:00Z",
  "last_error": "",
  "entry_count": 48213,
  "created_at": "2026-10-01T12:00:00Z"
}

Реестры

Список реестров

GET /api/v1/blocklist-sources

Возвращает все реестры команды. Параметров нет.

Ответ — код 200 и массив объектов реестра по дате создания, старые первыми. Если реестров нет, приходит пустой массив.

Добавить реестр

POST /api/v1/blocklist-sources

Создаёт реестр. Включённый реестр трекер проверит сам по расписанию; чтобы не ждать, вызовите проверку.

Ответ — код 201 и объект реестра.

curl -X POST https://panel.example.com/api/v1/blocklist-sources \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Реестр PL","url":"https://registry.example.com/domains.txt","geo":"PL","interval_min":30,"reserve_group_id":"7a6b5c4d-3e2f-4a1b-8c9d-0e1f2a3b4c5d"}'

Ошибки:

Изменить реестр

PUT /api/v1/blocklist-sources/{id}

Заменяет настройки реестра. {id} — идентификатор реестра.

Тело — те же поля, что при создании, url обязателен. Запись заменяется целиком, поэтому передавайте все поля, а не только изменённые:

• без name название становится пустым;
• без enabled и auto_replace оба переключателя включаются;
• без interval_min интервал становится 30;
• без reserve_group_id резервная группа сбрасывается;
• без geo или с пустой строкой код страны остаётся прежним.

Ответ — код 200 и объект реестра. Поля last_fetch_at, last_error и entry_count при изменении сохраняются.

Ошибки — те же, что при создании, 404 not_found, если реестра с таким {id} нет, и 400 bad_request, если {id} не в формате UUID.

Удалить реестр

DELETE /api/v1/blocklist-sources/{id}

Удаляет реестр. Записи журнала замен остаются.

Ответ — код 204 без тела. Если реестра нет — 404 not_found, если {id} не в формате UUID — 400 bad_request.

Проверка и пробная загрузка

На оба метода действует ограничение частоты.

Проверить реестр сейчас

POST /api/v1/blocklist-sources/{id}/check

Скачивает список, сверяет с ним домены и, если у реестра включена автозамена, меняет домены в потоках. То же делает кнопка Проверить в строке реестра. Метод работает и для реестра с enabled: false. Тело запроса не нужно.

Ответ приходит после окончания проверки — код 200 и объект реестра с обновлёнными last_fetch_at, entry_count и last_error.

Код 200 не означает, что проверка прошла без замечаний. Прочитайте last_error: в нём остаётся предупреждение, например автозамена не выполнена: не выбрана резервная группа доменов — менять не на что. Тексты разобраны в разделе Если не получилось.

Ошибки:

Примеры message при коде 502:

• реестр ответил 404 Not Found — сервер списка вернул не код 200;
• ответ реестра больше 64 МиБ — принимать нельзя, снимок был бы неполным;
• в ответе реестра не найдено ни одного домена — источник отдал не тот формат или заглушку;
• Get "https://registry.example.com/domains.txt": … — сетевая ошибка, после двоеточия идёт её текст, например слишком много редиректов.

Пробная загрузка списка

POST /api/v1/blocklist-sources/test

Скачивает список по адресу и показывает, что в нём распознано и какие домены команды в нём есть. Ничего не сохраняет и не меняет. В панели это кнопка Проверить рядом с полем Адрес списка.

Ответ — код 200:

curl -X POST https://panel.example.com/api/v1/blocklist-sources/test \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://registry.example.com/domains.txt"}'

{
  "total": 48213,
  "sample": ["blocked-one.example", "blocked-two.example"],
  "matched": ["go.example.com"]
}

Если total равен 0, по адресу нет списка доменов в распознаваемом формате.

Ошибки:

Журнал замен

Список замен

GET /api/v1/domain-replacements

Возвращает записи об автоматических заменах домена в потоках, новые первыми.

Ответ — код 200 и массив записей. Если замен не было, приходит пустой массив.

Откатить замену

POST /api/v1/domain-replacements/{id}/revert

Возвращает в поток прежний домен и снимает с него метку «в реестре». {id} — идентификатор записи журнала. Тело запроса не нужно.

В ссылке потока меняется только домен. Запись журнала получает reverted: true. Если домен по-прежнему есть в списке, следующая проверка снова пометит и заменит его.

Ответ — код 204 без тела.

Ошибки:

Ограничение частоты

POST /api/v1/blocklist-sources/{id}/check и POST /api/v1/blocklist-sources/test принимают не больше 10 запросов в минуту с одного IP-адреса. Счётчик общий для обоих методов. В него попадают и нажатия кнопки Проверить в панели с того же IP-адреса, а также запросы активации лицензии и сохранения настроек IP2Proxy. При превышении приходит код 429:

{"code": "rate_limited", "message": "слишком много запросов, попробуйте позже"}

Повторите запрос через минуту. На остальные методы группы ограничение не действует.