Документация API

REST API v1 для поиска и выгрузки Telegram-каналов. JSON, пагинация курсором, одна схема фильтров с интерфейсом и выгрузками. Машиночитаемая схема — OpenAPI бэкенда (/openapi.json).

Авторизация

Ключ создаётся в кабинете → Ключи API (тарифы Premium и Super). Формат ключа: mk_live_<prefix>_<secret>, показывается один раз. Передавайте его в заголовке:

Authorization: Bearer mk_live_ab12cd34_xxxxxxxxxxxxxxxx
# или
X-API-Key: mk_live_ab12cd34_xxxxxxxxxxxxxxxx

Скоупы: read (по умолчанию) и export — для POST /v1/exports. Не больше двух активных ключей: так ключ можно ротировать без простоя.

Тарификация

Платите за отданные данные, а не за вызовы. Всё списывается кредитами: 1 кредит = $0,001.

Каждый платный запрос — 1 кредит ($1 за 1 000 запросов).
Каждая строка канала — по ставке набора полей: Base 0,5 кредита, +Metrics 1,5, +Ads 2, History 3.
Пост — 0,5 кредита.
Канал, за который этот ключ уже платил за последние 30 дней, отдаётся бесплатно.
/count и фасеты — только плата за запрос.

Сколько списано за запрос — в заголовке X-Credits-Charged. Баланс и расход — GET /v1/usage. Цены выгрузок — на странице тарифов.

Эндпоинты

Метод	Путь	Что делает	Списание
GET	/v1/categories	Дерево категорий	бесплатно
GET	/v1/languages	Языки и число каналов	бесплатно
GET	/v1/usage	Баланс, расход по дням, лимиты	бесплатно
POST	/v1/channels/search	Фильтры + q, курсор, до 100 на страницу	запрос + строки
POST	/v1/channels/count	Счётчики и фасеты по запросу	запрос
GET	/v1/channels/{id\|username}	Карточка канала (?fields=base,metrics,ads)	запрос + строка
GET	/v1/channels/{id}/history	Ряд подписчиков и метрик по дням (?days=)	запрос + History
GET	/v1/channels/{id}/posts	Последние посты (?limit= до 100)	запрос + посты
GET	/v1/channels/{id}/references	Кто цитирует и кого цитирует	запрос + строки
POST	/v1/posts/search	Полнотекстовый поиск по постам	запрос + посты
POST	/v1/exports	Асинхронная выгрузка (scope export)	по прайсу выгрузки
GET	/v1/exports/{id}	Статус и ссылка на файл	бесплатно

Фильтры (ChannelQuery)

Объект query одинаков для /channels/search, /channels/count и /exports. Пустые поля можно не передавать.

q	string	текст: название, username, описание, посты
category_ids / exclude_category_ids	int[]	категории (области или подкатегории)
channel_ids	int[]	конкретные каналы
languages	string[]	коды языков: ru, en, uk…
kind	all \| channel \| group	тип
subscribers_min / subscribers_max	int	подписчики
avg_views_min, reach_24h_min	number	просмотры и охват 24 ч
er_min, err_24h_min	number	ER / ERR, %
growth_7d_min, growth_30d_min, growth_pct_30d_min	number	прирост
posts_30d_min, last_post_after	int, date	активность
created_after / created_before	date	дата создания
has_ads_contact, ad_share_max	bool, 0..1	реклама
fraud_max	0..1	порог fraud-score
verified_only, exclude_scam	bool	флаги (exclude_scam=true по умолчанию)
sort, order	string	relevance, subscribers, growth_7d, growth_30d, growth_pct_30d, reach_24h, avg_views, er, citation_index, created_at, last_post_at; desc\|asc

Примеры

Поиск каналов

curl -X POST https://api.tgmarket.example/v1/channels/search \
  -H "Authorization: Bearer $MK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {"q": "нейросети", "languages": ["ru"], "subscribers_min": 5000, "sort": "growth_30d"},
    "fields": ["base", "metrics"],
    "limit": 100
  }'

Ответ:

{
  "items": [{"id": 2365318039, "username": "GPTronhub", "title": "…", "subscribers": 169432, "er": 0.16, …}],
  "total": 605,
  "next_cursor": "eyJoIjoi…"   // передайте в следующем запросе как cursor
}

Счётчик без строк

curl -X POST https://api.tgmarket.example/v1/channels/count -H "Authorization: Bearer $MK_KEY" \
  -H "Content-Type: application/json" -d '{"query": {"category_ids": [21]}}'

Карточка и история

curl "https://api.tgmarket.example/v1/channels/durov?fields=base,metrics" -H "Authorization: Bearer $MK_KEY"
curl "https://api.tgmarket.example/v1/channels/1006503122/history?days=90" -H "Authorization: Bearer $MK_KEY"

Выгрузка

curl -X POST https://api.tgmarket.example/v1/exports -H "Authorization: Bearer $MK_KEY" -H "Content-Type: application/json" \
  -d '{"query": {"q": "крипта"}, "fields": ["base","metrics"], "format": "csv", "row_limit": 20000}'
# → {"export_id": "…", "rows": 20000, "price_credits": 32000, "status": "queued"}

curl https://api.tgmarket.example/v1/exports/<export_id> -H "Authorization: Bearer $MK_KEY"
# → {"status": "done", "progress": 100, "download_url": "https://…", …}

Лимиты

Premium — 1 запрос в секунду, Super — 10, Enterprise — по договору.
Каждый ответ содержит заголовки X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Глубже 10 000 результатов по одному запросу — используйте /v1/exports.
Жёсткий суточный потолок уникальных каналов на ключ; при переборе ключ замораживается до ручной проверки.

Ошибки

Все ошибки — в едином формате:

{"error": {"code": "payment_required", "message": "…"}}

401 invalid_api_key — неверный или отозванный ключ
402 payment_required / 402 insufficient_funds — баланс исчерпан, пополните в кабинете (в ответе need/have)
403 api_not_in_plan, 403 scope_required, 403 key_frozen, 403 ip_not_allowed
429 rate_limited — превышен RPS; подождите столько секунд, сколько указано в Retry-After
400 too_deep, 400 bad_cursor, 422 — ошибка в параметрах