Толкдокументы

Обновлено 11 сентября 2026

API «Толка»

Редакция 1.0. Базовый адрес: https://tolk-bot.ru/api/v1

Авторизация

Ключ выпускается в панели управления, раздел «API». Показывается один раз —

в базе хранится только хеш.

Authorization: Bearer tolk_xxxxxxxxxxxxxxxxxxxx

Права: read < write < admin. Ограничение — 120 запросов в минуту на ключ,

при превышении приходит 429.

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

{ "ok": true,  "data": { } }
{ "ok": false, "error": { "code": "not_found", "message": "Пользователя нет" } }

Коды ошибок: no_key, bad_key, forbidden, rate_limit, bad_request,

not_found, not_allowed, vk_error.

Методы

GET /health

Без авторизации. Проверка живости.

GET /stats · read

Сводка: пользователи, подписчики, выручка и расход на ИИ за сутки.

GET /users/{vk_id} · read

Профиль: тариф, срок, количество ответов, статус гейта и блокировки.

GET /users/{vk_id}/quota · read

Остатки по всем видам действий: дневной, месячный и догенерации.

POST /users/{vk_id}/grant · write

{ "kind": "tariff", "tariff": "pro", "days": 30, "reason": "приз конкурса" }

kind: "trial" выдаёт пробный период — он доступен один раз за всю жизнь аккаунта.

POST /users/{vk_id}/quota · write

{ "kind": "img", "amount": 20, "reason": "компенсация" }

kind ∈ img, fast, sticker. Начисляется как догенерации: не сгорает.

POST /users/{vk_id}/message · write

{ "text": "Ваш заказ готов" }

Вернёт 409, если человек запретил сообщения от сообщества.

GET /templates · read

Параметры: ?group=greet или ?q=день рождения.

POST /promo · write

{ "code": "VESNA", "kind": "percent", "value": 20, "max_uses": 100, "source": "блогер" }

Без code сгенерируется свой.

POST /broadcast · admin

{ "title": "Новые шаблоны", "text": "...", "segment": "paying" }

Сегменты: all, free, paying, expiring, expired, asleep, bought_day.

GET /segments/{name} · admin

Состав сегмента: количество и до 1000 идентификаторов.

Пример

curl -s https://tolk-bot.ru/api/v1/stats \
  -H "Authorization: Bearer $TOLK_KEY" | jq