Защищённое чтение и публичный статус
Защищённое чтение использует GET на https://api.redditapicloud.com с X-API-Key: <ключ> либо Authorization: Bearer <ключ>. Оба варианта передают ключ архива этого домена, а не токен Reddit OAuth. Храните секрет на сервере. Cookie Secure HttpOnly личного кабинета относится к отдельной сессии и не заменяет заголовок получения данных. Пользовательские сессии вашего продукта и проверки прав остаются ответственностью приложения.
/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 — внутренний порядок документов, не хронология, релевантность или оценка. Локальная перестановка полученных записей является решением приложения и не доказывает полного охвата или стабильности повторного результата. Сохраняйте поля источника отдельно от меток и вычислений собственной функции исследования, чтобы не приписывать архиву выводы, сделанные вашим кодом.
Возвращаемые данные представляют собой плоские записи, а не серверные деревья ветвлений. Вы можете самостоятельно группировать данные по идентификаторам на клиенте, так как полнота цепочки родительских записей не гарантируется сервером. Фильтры по идентификаторам ссылки или родителя недоступны на уровне API. Ответ содержит data, pagination и credits. Поля могут различаться или отсутствовать; проверяйте полученное вместо предположения о фиксированной схеме.
Границы страниц, итоги и обработка сбоев
Маршруты содержимого принимают limit и page от 1 до 100, по одной странице за запрос. Серия обращений не гарантирует 10000 разных записей или полный набор. page=101 не поддерживается. Пользовательское действие может вызвать несколько платных обращений, если приложение добавляет страницы или отдельные элементы. Ограничивайте их самостоятельно: архив не задаёт роли клиентов вашего SaaS или их бюджеты.
Читайте pagination.total вместе с relation: eq — точный итог запроса, gte — нижняя граница, unknown — отсутствие надёжного итога, возможно null. Пустая страница после первой может вернуть unknown, а не число ноль. Точный итог не доказывает скачивания всех совпадений или наличия всей истории в архиве. Сохраняйте has_more и window_exhausted как признаки границ, не токены неограниченного экспорта.
HTTP 400 относится к неправильным параметрам, 401 — к отсутствующему или недействительному ключу, 402 — к нехватке кредитов, 429 — к ограничению частоты. Некорректные запросы не списываются; сбой источника возвращает резерв. Успешное получение стоит один кредит, даже пустое и повторное. Потеря ответа может скрывать оплаченный успех; локальная ошибка не возвращает его стоимость. Сохраните ответ до обновления прогресса и учитывайте успешные повторы отдельно.
