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