Community discovery and individual items
All protected retrieval routes use GET under https://api.redditapihub.com. Authenticate using X-API-Key: <key> or Authorization: Bearer <key>. Both are supported alternatives carrying this domain's archive key, not Reddit OAuth credentials. Store the secret server-side. The Secure HttpOnly session cookie for the account panel is separate from data retrieval and does not replace a key header in your application.
/v1/subreddits accepts prefix and limit only. An optional prefix restricts community names, not post text. When supplied, it uses 1–64 ASCII letters, digits or underscores. limit ranges from 1 to 100 and caps community entries. Each entry contains subreddit and count, without a globally exact count guarantee. This route has no page, author, date or content query filter; it does not expose an exhaustive community-catalogue cursor.
/v1/item?id=... requires a record identifier and looks for one archived item. It accepts id only, not a Reddit URL or a request for a complete thread. The record may be absent. Inspect identifiers in actual records rather than assuming a transformation used by another client. /v1/status is public, needs no key and costs no credits. Its static disclosure confirms an HTTP application response without probing the search backend, archive availability or balance.
Content routes and supported filters
/v1/search searches posts and comments. /v1/posts adds a post-kind constraint and /v1/comments adds a comment-kind constraint. All three accept q, subreddit, author, kind, from, to, min_score, limit and page, not id or prefix. kind accepts post or comment; omit it to allow both kinds through search. q is text search, not arbitrary query DSL, sentiment analysis or custom server-side statistics.
from and to require YYYY-MM-DD in UTC and filter created_utc, not ingestion time. The complete final to day is included. min_score is a numeric score threshold, without score sorting or quality assessment. Results follow internal _doc order, not insertion time, chronology, relevance or score. You may sort or analyze the received sample locally, while preserving the fact that missing records remain outside that sample.
Retrieval responses contain data, pagination and credits. Content documents are flat and their fields may vary. Present parent_id and link_id allow local relationships, but neither field is an exposed query filter. Local grouping does not guarantee every parent, reply or complete conversation. Keep absent fields and unresolved references visible instead of silently filling them with fabricated source values.
Pagination, errors and credit accounting
Content searches allow limit and page from 1 to 100, one page per request. This is not pagination for /v1/subreddits. Read pagination.total with relation: eq means an exact query total, gte a lower bound and unknown no reliable total, possibly null. Discovery uses an unknown total; its truncated signal can indicate omitted aggregation buckets without giving a way to page through them.
An exact total does not prove a complete download or full archive coverage. Dividing periods, iterating pages or removing duplicates locally does not prove exhaustive or unique retrieval. There is no fixed coverage date, immutable snapshot or permanent-record guarantee. Keep returned has_more, window_exhausted and truncated indicators with the response, interpreting each in the context of the route rather than inventing a cursor from them.
HTTP 400 means invalid parameters, 401 a missing or invalid key, 402 insufficient credits and 429 a frequency limit. Invalid requests do not debit; upstream failures refund reservations. Successful retrieval costs one credit even when empty. A timeout or lost client response may follow a charged success, and another successful attempt costs another credit. A failure in your own storage or transformation does not refund a successful archive request.
