REST API v1

Публичный REST API MaxBotStat позволяет читать аналитику и отправлять сообщения от имени бота из вашего кода. Его используют:

• интеграции с CRM (передача новых контактов и диалогов);
• BI-дэшборды (выгрузка стат);
• автоматизированные рассылки и ответы;
• регулярный экспорт данных.

Базовый URL

https://capybara.maxbotstat.ru/api/v1

Все эндпоинты возвращают application/json.

Авторизация

Используется API-ключ в заголовке X-API-Key. Альтернативно — Bearer:

X-API-Key: mbs_AbCd...EfGh
# или
Authorization: Bearer mbs_AbCd...EfGh

Подробнее: Аутентификация.

Scope (права)

Каждый ключ имеет один или оба scope:

Scope	Что разрешено
read	чтение списков, контактов, сообщений, статистики
write	отправка сообщений и рассылок

Все GET-эндпоинты требуют read. POST /broadcast, POST /send — требуют write.

Эндпоинты

Метод	Путь	Описание
GET	/me	Профиль владельца ключа и активные scope
GET	/bots	Список всех ваших ботов
GET	/bots/{id}	Карточка бота
GET	/bots/{id}/contacts	Контакты бота (с пагинацией)
GET	/bots/{id}/contacts/{userId}	Карточка контакта
GET	/bots/{id}/messages	История сообщений (фильтры по дате/пользователю)
GET	/bots/{id}/dialogs	Лента диалогов (как в кабинете)
GET	/bots/{id}/stats	Сводная статистика бота
GET	/bots/{id}/stats/timeline	Таймлайн по дням (in/out/новые контакты)
GET	/bots/{id}/sources	Источники UTM с количеством контактов
GET	/bots/{id}/intents	Список intent'ов с метриками
POST	/bots/{id}/send	Отправить сообщение пользователю
POST	/bots/{id}/broadcast	Запустить рассылку

Идентификаторы

Везде используется публичный UUID бота, например 5d4e3a2b-.... Внутренние числовые id через API не отдаются.

В заголовке HTTP подойдёт и числовой id (для обратной совместимости), но публичные интеграции должны использовать UUID.

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

Списки

{ "data": [ ... ], "total": 412, "limit": 100, "offset": 0 }

Один объект

{ "id": "uuid", "name": "...", ... }

Ошибки

{ "message": "Описание ошибки на русском" }

HTTP-статус: 4xx для ошибок клиента, 5xx для серверных. См. Коды ошибок.

Пагинация

Все списочные эндпоинты принимают:

• limit — размер страницы. По умолчанию 100, максимум 1000.
• offset — смещение. По умолчанию 0.

Поле total в ответе — общее количество элементов на сервере (не зависит от limit/offset).

Производительность

Для больших выборок используйте limit=1000 и идите по страницам. Поддержки cursor-пагинации пока нет.

Лимиты запросов

В текущем релизе лимиты не строгие:

• ~60 запросов в минуту на ключ (мягкий троттлинг через nginx);
• 100 одновременных открытых соединений на инстанс.

Если упираетесь — пишите в поддержку, расширим квоту.

Версионирование

Текущая версия — v1, она stable. При появлении breaking changes мы:

1. выпустим v2 параллельно;
2. оставим v1 минимум на 6 месяцев;
3. предупредим всех, у кого last_used_at ключа попадает в v1-эндпоинты.

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

# 1. выпустите ключ в кабинете (Настройки → API)
# 2. сохраните в переменную
export MBS_KEY="mbs_..."

# 3. получите список своих ботов
curl "https://capybara.maxbotstat.ru/api/v1/bots" \
     -H "X-API-Key: $MBS_KEY"

# 4. возьмите id первого бота и попросите его статистику
curl "https://capybara.maxbotstat.ru/api/v1/bots/<botId>/stats" \
     -H "X-API-Key: $MBS_KEY"