Захищене читання та публічний статус
Захищене читання використовує 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 містять плоскі записи, що означає відсутність серверних дерев дискусій. Якщо записи містять ідентифікатори батьківських посилань, ви можете групувати їх локально у своїй програмі. Однак повна історія розмов не гарантується. Фільтрів запиту за parent_id або link_id немає. Відповіді містять 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 — обмеження частоти. Некоректні запити не списуються; збій джерела повертає резерв. Успішне отримання коштує один кредит, навіть порожнє й повторне. Втрата відповіді може приховувати оплачений успіх; локальна помилка не повертає його вартості. Збережіть відповідь до оновлення прогресу та враховуйте успішні повтори окремо.
