Authentication and access control
Protected retrieval uses GET under https://api.redditgateway.com with X-API-Key: <key> or Authorization: Bearer <key>. Either header is valid. Authentication relies on API keys rather than Reddit OAuth. Store the key in protected server configuration, such as an environment variable or secret manager, and keep it out of frontend bundles and diagnostic logs. The account panel's Secure HttpOnly session cookie is separate from retrieval authentication.
/v1/status is the public exception: no key is required and no credit is charged. It returns a static service-scope disclosure and establishes only that the HTTP application responds. It does not test the search backend, inspect record availability or show balance. Keep this observation separate from your own measurements of authenticated requests; never infer search readiness from a status response.
HTTP 400 means invalid parameters, 401 a missing or invalid key, 402 insufficient credits and 429 a request-frequency limit. Handle each cause separately. Inspect configuration after 401, pause paid work after 402 and bound delayed retries after 429. A successful empty retrieval is not an authentication error. Do not repeatedly rotate keys merely because a search has no matches.
Core routes and filtering logic
/v1/search searches posts and comments. /v1/posts and /v1/comments additionally constrain the record kind. They accept q, subreddit, author, kind, from, to, min_score, limit and page, but not id. kind accepts the literal values post or comment; omit it to search both kinds through search. q performs text search, without arbitrary query DSL, sentiment classification or server-side custom analytics.
/v1/item?id=... requires id and looks for one record. It does not walk replies or ancestors. /v1/subreddits accepts only prefix and limit for community-name discovery; prefix is not a content-route filter. Aggregation counts are not guaranteed globally exact. None of these routes accepts an arbitrary Reddit URL to crawl or forwards Reddit OAuth permissions.
from and to require YYYY-MM-DD dates in UTC and filter created_utc, not archive ingestion time. The final day to is fully inclusive. min_score is a numeric score threshold, not a quality classifier or ordering option. Responses contain data, pagination and credits. Document fields can vary; preserve missing text and unresolved references instead of manufacturing values required by a downstream schema.
Pagination totals and archive behavior
limit and page range from 1 to 100, with one page per request. Internal _doc order does not mean insertion time, chronology, relevance or score order. Local sorting only reorders received records. Smaller date windows can organize work but cannot establish full coverage or unique results. The archive does not guarantee fixed coverage dates, repeat-query stability, immutability or permanent availability.
Read pagination.total with pagination.relation: eq means an exact query total, gte a lower bound and unknown no reliable total, possibly null. An exact count does not establish that all matches were downloaded or that Reddit history is fully represented. Preserve has_more and window_exhausted as returned boundary signals. Flat records with present parent_id or link_id can be grouped locally; neither field is a query filter or a completeness guarantee.
A successful retrieval costs one credit, including an empty response. Invalid requests do not debit; upstream failures return reservations. A client timeout or disconnected socket may happen after a billable success. A successful retry is charged again, and failure in your own database does not turn the remote success into a refund. Persist a received response before advancing local progress.
