Защищённое чтение и публичный статус
Защищённое чтение использует GET на https://api.redditdatastream.com с X-API-Key: <ключ> либо Authorization: Bearer <ключ>. Оба варианта передают ключ архива этого домена, а не токен Reddit OAuth. Храните секрет на сервере. Cookie Secure HttpOnly панели счёта относится к отдельной сессии. Сервис возвращает отдельные JSON-ответы, а не живой SSE-поток, соединение WebSocket или подписку на события Reddit.
/v1/search ищет публикации и комментарии. /v1/posts ограничивает выдачу публикациями, /v1/comments — комментариями. Все три принимают q, subreddit, author, kind, from, to, min_score, limit и page, но не id. kind принимает post и comment; для обоих типов через search не задавайте его. q — текстовый поиск без произвольного языка запросов, классификации тональности и собственной серверной аналитики.
/v1/item?id=... требует только id и ищет одну архивную запись, которая может отсутствовать. Родители и ответы автоматически не обходятся. /v1/subreddits принимает только prefix и limit для поиска названий сообществ, без постраничного обхода и гарантии глобально точных счётчиков. /v1/status публичен и бесплатен: статическое описание подтверждает ответ HTTP-приложения, не проверяя доступность поиска, свежесть записей, действительность ключа или баланс.
Даты, порядок документов и локальная сериализация
from и to принимают YYYY-MM-DD в UTC и фильтруют created_utc, а не момент попадания записи в архив. Последний день to включается целиком. Это фильтры дней, а не значения курсора с точностью до времени суток. При делении работы по датам сохраняйте фактические границы и различайте время обработки задания и создания записи. Разбиение не доказывает полноты получения или расписания обновления архива.
Поле min_score выполняет исключительно функцию фильтра и никогда не используется для сортировки результатов по убыванию или возрастанию. Порядок _doc — внутренний порядок документов, не время вставки, хронология, релевантность или оценка. Последняя запись страницы не является гарантированной временной отметкой прогресса. Локальная сортировка организует полученное, но не доказывает, что все более ранние записи уже загружены, а поздние появятся в будущем обращении.
Записи содержимого плоские, поля могут различаться. Присутствующие parent_id и link_id допускают локальную группировку без полной цепочки родителей или беседы. Ни один из этих идентификаторов не является фильтром запроса. Ответ содержит data, pagination и credits. Приложение может сериализовать отдельные записи data в локальный JSONL, сохраняя пагинацию и кредиты отдельно. Это локальная обработка, не серверный поток, переключатель экспорта или гарантия фиксированной схемы источника.
Границы страниц, итоги и обработка сбоев
Маршруты содержимого принимают limit и page от 1 до 100, по одной странице за запрос. page=3 не возвращает три страницы вместе. Нумерация не является стабильным курсором или последовательностью событий; page=101 для той же выборки не поддерживается. Дробление окон и локальное удаление дублей организуют работу без доказательства полного охвата, уникальности или неизменности повторного результата. Локальная контрольная точка не гарантирует продолжения без потерь.
Читайте pagination.total вместе с relation: eq — точный итог запроса, gte — нижняя граница, unknown — отсутствие надёжного итога, возможно null. Пустая страница после первой может вернуть unknown, а не число ноль. Точный итог не доказывает скачивания всех совпадений или наличия всей истории в архиве. Сохраняйте has_more и window_exhausted как признаки границ, не токены неограниченного экспорта.
HTTP 400 относится к неправильным параметрам, 401 — к отсутствующему или недействительному ключу, 402 — к нехватке кредитов, 429 — к ограничению частоты. Некорректные запросы не списываются; сбой источника возвращает резерв. Успешное получение стоит один кредит, даже пустое и повторное. Потеря ответа может скрывать оплаченный успех; локальная ошибка не возвращает его стоимость. Сохраните ответ до обновления прогресса и учитывайте успешные повторы отдельно.
