Обзор API¶

Версия API указывается в пути (/v1/...), API работает с JSON поверх HTTP и не требует аутентификации. Документ OpenAPI 3.1 отдаётся по адресу /openapi.json и отображается как Swagger UI на /api (оба можно отключить через DISABLE_DOCS).

Те же данные доступны и через GraphQL API на /graphql, где клиенты выбирают только нужные поля и могут объединять несколько запросов в один.

Соглашения¶

Каналы — это публичные имена пользователей без @: 5–32 символа, начинаются с буквы, дальше буквы, цифры или _ (^[a-zA-Z][a-zA-Z0-9_]{3,31}$). Всё остальное отклоняется с 422 ещё до обращения к t.me.

ID и позиции постов — целые числа от 1 до 10 000 000.

Текст в двух формах. Везде, где Telegram показывает форматированный текст, API возвращает объект со string (простой текст, переводы строк как \n) и html (исходная разметка):

{"string": "Pavel Durov", "html": "Pavel Durov"}

Счётчики — это строки ровно в том виде, в каком их форматирует Telegram ("10.3M", "14.2K", "10 281 023 subscribers"); API их не переинтерпретирует.

Отсутствующие значения — null. Необязательные поля всегда присутствуют в ответах и равны null, если Telegram их не предоставляет, так что клиенты могут рассчитывать на стабильную структуру.

Даты — строки ISO-8601 со смещением плюс Unix-время:

{"string": "2026-10-20T10:00:00+00:00", "unix": 1792490400}

Заголовки ответа¶

Заголовок	Когда	Значение
`X-App-Node`	всегда	Имя хоста сервера, который ответил, — удобно за балансировщиком нагрузки
`X-Process-Time`	всегда	Время, проведённое в приложении, например `3 ms`
`Cache-Control`	запросы с заголовком `CF-RAY` (Cloudflare)	`public, max-age=10, stale-while-revalidate=10` (`normal`) или `public, max-age=120, stale-while-revalidate=240` (`aggressive`); для `off` не отправляется
`X-RateLimit-Limit`, `X-RateLimit-Remaining`	включено ограничение частоты запросов	Лимит на IP на текущую минуту
`Retry-After`	ответы `429`	Сколько секунд ждать (всегда `60`)

CORS открыт (Access-Control-Allow-Origin повторяет origin запроса), если он не ограничен через CORS_ALLOW_ORIGINS.

Свежесть данных¶

Ответы приходят из кэша, который живёт от нескольких секунд до часа в зависимости от эндпоинта и CACHE_MODE:

Эндпоинт	`off`	`normal`	`aggressive`
`/v1/body`, `/v1/post`, `/v1/more`	всегда актуально	10 с	120 с
`/v1/preview`, `/v1/previews`	`PREVIEW_CACHE_TTL` (1 ч)	так же	так же
`/v1/feed`	см. Лента

Одинаковые запросы, пришедшие, пока идёт обращение к t.me, разделяют этот единственный запрос к источнику.

Коды статуса¶

Код	Значение
`200`	Успех
`404`	Канал или пост не существует (или канал приватный)
`422`	Некорректный ввод — см. Ошибки
`429`	Превышен лимит запросов
`502`	t.me вернул страницу, которую парсер не смог разобрать
`503`	t.me недоступен или ответил ошибкой, либо функция отключена

Все тела ошибок описаны в разделе Ошибки.