Публичный API

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

Токен

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

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

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

Authorization: Bearer bb_api_...

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

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

GET /api/v1/sites

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

Обратите внимание на пару protection_mode и effective_mode. Первое — что выбрали вы, второе — что движок делает на самом деле. Они расходятся, пока идёт неделя обучения, пока домен не подтверждён или если исчерпан лимит тарифа.

Статистика

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

По каждому визиту приходит не только вердикт, но и разбор: какие признаки сработали и сколько добавил каждый. Это то же, что видно в журнале кабинета.

Адреса ботов

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

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

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

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

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 — сайт не найден или принадлежит другому аккаунту. 429 — превышена частота запросов.