Kanalist API · v1

Свежая нормализованная база как рабочий инструмент.

API построен вокруг публичных агрегатов, verified-профилей и прозрачного происхождения данных. Raw message archive не предоставляется.

01 · Принципы

Rights-aware API

Каждый объект содержит источник, время проверки и доступный scope публикации. Данные без права на экспорт не попадают в публичный ответ.

02 · Endpoints

Доступные маршруты

GET/api/v1/catalog

Три каталога через type=channels|bots|chats и фильтры q, category, language, minTrust.

POST/api/v1/submissions

Добавление @username или t.me URL с receipt ID.

POST/api/v1/reports

Жалоба или исправление с обязательным evidence.

GET/api/v1/health

Состояние приложения, хранилища и коннекторов.

POST/api/v1/telegram/refresh

Защищённое обновление публичного профиля через Bot API.

POST/api/v1/ingestion/jobs/claim

Выдача MTProto collector очередной порции due-заданий.

POST/api/v1/ingestion/snapshots

Идемпотентный приём агрегатов каналов, ботов и чатов.

POST/api/v1/ingestion/jobs/fail

Возврат задания в очередь с FloodWait-aware задержкой.

GET/api/v1/auth/telegram/start

Запуск Telegram OpenID Connect с PKCE и anti-CSRF state.

GET/api/v1/auth/me

Текущий аккаунт, роли, scope и эффективные permissions.

POST/api/v1/auth/logout

Отзыв серверной сессии и удаление HttpOnly cookie.

GET / POST/api/v1/claims

Заявки пользователя на подтверждение владения ресурсом.

GET/api/v1/moderation/queue

Защищённая очередь жалоб и ownership claims.

PUT / DELETE/api/v1/admin/users/:id/roles

Scope-aware выдача и отзыв ролей с audit trail.

03 · Пример

Поиск по каталогу

GET /api/v1/catalog?type=channels&q=product&language=RU

{
  "data": [
    {
      "slug": "product-compass",
      "name": "Product Compass",
      "type": "channels",
      "kind": "Канал",
      "signals": {
        "health": 96,
        "trust": 94,
        "reach": 89,
        "momentum": 82
      },
      "provenance": {
        "source": "owner_connected",
        "checkedAt": "2026-07-29T10:12:00Z"
      }
    }
  ],
  "meta": { "total": 1, "safeSearch": true }
}

04 · Лимиты

Безопасность и квоты

Free: 60 запросов в минуту.
Agency: 600 запросов в минуту и batch endpoints.
Идемпотентность для write-запросов.
Audit log и отзыв API-ключа.
Raw Telegram content не возвращается.