Публичный API

API отдаёт то же, что видно в кабинете. Управлять режимом защиты через него намеренно нельзя: включение блокировки — решение, которое человек должен принимать осознанно, увидев перед этим предупреждения.

Токен

Выпускается в разделе «Аккаунт». Значение показывается один раз: мы храним только хэш, поэтому подсмотреть его позже не сможем даже мы.

Токен бывает двух видов: только на чтение и на чтение с изменением списков. По умолчанию — только чтение.

Передавайте его заголовком:

Authorization: Bearer bb_api_...

Ограничение частоты — 120 запросов в минуту.

Список сайтов

GET /api/v1/sites

Возвращает сайты аккаунта: идентификатор, домен, статус, выбранный и фактический режим защиты.

Обратите внимание на пару protection_mode и effective_mode. Первое — что выбрали вы, второе — что движок делает на самом деле. Они расходятся, пока домен не подтверждён, если исчерпан лимит тарифа или тариф не разрешает блокировку. Значение status у подтверждённого сайта в наблюдении — learning: так исторически назывался срок обучения, которого больше нет.

Статистика

GET /api/v1/sites/{uuid}/stats?period=24h

Период: 24h, 7d или 30d. Возвращает показатели за период и ряды для графика.

Поле would_block — сколько визитов движок признал бы ботами. Пока сайт в режиме наблюдения, blocked равно нулю, а would_block показывает то, что было бы.

Журнал визитов

GET /api/v1/sites/{uuid}/visits?period=24h&verdict=block&limit=100

По каждому визиту приходит не только вердикт, но и разбор: какие признаки сработали и сколько добавил каждый. Это то же, что видно в журнале кабинета. Повторы пойманного адреса за час свёрнуты в одну запись: repeats — ещё столько запросов той же страницы, overflow — к другим страницам сверх лимита, last_repeat_at — время последнего. Чтобы посчитать запросы, а не записи, складывайте 1 + repeats + overflow.

Адреса ботов

GET /api/v1/sites/{uuid}/bot-ips?period=30d

Список пойманных адресов с числом запросов. В ответе есть поле excluded — сколько адресов мы намеренно не отдали и почему.

Не игнорируйте его. Из списка вычищаются адреса общих сетей операторов связи: за одним таким адресом стоят тысячи абонентов, и вносить его в чёрный список рекламного кабинета нельзя.

Список для файрвола

GET /api/v1/sites/{uuid}/firewall?format=ipset

Форматы: plain (по записи в строке, по умолчанию), nginx, apache, ipset. Ответ — текст, а не JSON: его забирает скрипт на сервере сайта и сразу передаёт ipset или nginx. Число записей — в заголовке X-BotBan-Entries. Что входит в список и как настроить обновление — в статье «Список для файрвола и fail2ban».

Изменение списков

POST /api/v1/sites/{uuid}/lists
Content-Type: application/json

{"list": "whitelist_ips", "value": "203.0.113.7"}

Значения list: whitelist_ips, whitelist_paths, blacklist_ips. Требует токен с правом записи.

Ошибки

401 — токен не передан, не найден или отозван. 403 — токену не хватает прав. 404 — сайт не найден или принадлежит другому аккаунту (сайты, открытые вам только для просмотра, через API недоступны). 429 — превышена частота запросов.