Основы

Адрес и версии

Все пути — под https://soroka.tools/v1. Версия — в пути. Внутри v1 изменения только совместимые: новые пути, новые необязательные поля запроса, новые поля ответа, новые значения kind и code в ошибках. Поэтому незнакомые поля ответа нужно игнорировать, а незнакомый kind обрабатывать как platform_unknown.

Несовместимое — только в /v2. Путь, который уходит, получает заголовки Deprecation и Sunset не меньше чем за 90 дней; дата и замена — в журнале изменений.

Ключи и права

Каждый запрос несёт ключ в заголовке:

Authorization: Bearer <ключ>

• Ключ показывается полностью один раз, у нас хранится только его отпечаток. Потерялся — выпустите новый, старый отзовите.
• Один ключ — один сервис. Нужны разные права — разные ключи.
• Ключу можно задать срок жизни и список разрешённых адресов (CIDR): запрос с другого адреса получит 403 ip_not_allowed.
• Ключ — в секретах сервиса, не в коде и не в логах. В логах допустим только префикс.

Права ключа (scopes):

Нет права — 403 auth_failed, code=no_scope, в поле missing — каких прав не хватает. Действующие права ключа показывает GET /v1/me.

Форматы

• Запросы и ответы — JSON в UTF-8. Потоки — NDJSON (application/x-ndjson, объект на строку) и SSE (text/event-stream).
• Время — ISO-8601 в UTC (2026-09-22T19:00:00Z), длительности — целые секунды.
• Наши идентификаторы (подписки, задачи) — UUID строкой, события — целое строкой ("18446").
• Канал или чат в запросе: @name, https://t.me/name или peer_id числом (канал — -100…).
• Тело запроса — не больше 1 МБ, больше — 413 payload_too_large.

Пагинация

Списки отдаются страницами по курсору:

GET https://soroka.tools/v1/jobs?limit=50&cursor=eyJpZCI6…
→ {"items": [...], "next_cursor": "eyJpZCI6…"}

limit — от 1 до 500 (по умолчанию 50). Курсор непрозрачный: не разбирайте и не собирайте его сами, он живёт сутки. next_cursor: null — страниц больше нет. Порядок — от новых к старым. События подписок листаются не курсором, а after — номером последнего события.

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

Подробно о лимитах, квотах и кредитах — «Лимиты и кредиты».

Задачи

Задача — долгий сбор, который мы выполняем целиком: POST /v1/jobs отвечает сразу (202, job_id), дальше задача идёт queued → running → done (или failed, cancelled). Готовый результат — GET /v1/jobs/{job_id}/result?format=json|csv|xlsx. Цену «от–до» до запуска показывает POST /v1/jobs/estimate; сколько списано — result_summary.credits в карточке.

Шаблоны сбора ("kind": "parser.preset", ключ шаблона — в params.preset):

У всех шаблонов Telegram — ref (до 20 каналов через пробел или запятую), у ВКонтакте — ссылка на сообщество в ref или слова в query. limit — потолок записей.

Подписки на события

Подписка — список каналов и способ доставки. Она не привязана ни к чему, кроме ключа: как и откуда читать каналы, решаем мы, и при сбоях догоняем пропущенное сами. Каждое сообщение приходит один раз.

События: new — новое сообщение, post — пост целиком (альбом склеен в один), edit, delete, action — служебное. Обычно берут либо new, либо post. События хранятся 7 дней. Пример события:

{"id": "18446", "kind": "post",
 "chat": {"peer_id": -1005678901234, "username": "telegram", "title": "Telegram News"},
 "message": {"id": 512, "date": "2026-09-23T09:15:00+00:00", "text": "…", "views": 18400, "media": []},
 "source": "poll", "received_at": "2026-09-23T09:15:02Z"}

Закрытые чаты — по приглашению в chats[].ref; как подписка решает, нужно ли вступать, — в разделе справочника «Вступления».