Build the first request around the reader’s question

Put your backend between the app and the archive

For the illustrative hiking feature, the mobile or web client sends the phrase offline maps to your own backend. Your backend validates the request, applies the app’s limits and calls the archive with a saved service key. Return only the fields your reading screen needs. The example is a design starting point, not a claim that this tenant has returned hiking records.

Use GET https://api.redditapp.com/v1/search?q=offline%20maps&subreddit=hiking&limit=3&page=1. Send either X-API-Key: YOUR_SAVED_KEY or Authorization: Bearer YOUR_SAVED_KEY as a header from your backend. Keep credentials out of URLs, client bundles and public logs. The account page’s session cookie does not replace retrieval authentication.

Choose filters the service actually accepts

Search accepts q, subreddit, author, kind, from, to, min_score, limit and page. q applies AND matching across title and text; it is not a promise of exact-phrase or semantic matching. kind accepts post or comment. Subreddit and author are exact field filters. min_score filters records; it does not sort them.

Use from and to as YYYY-MM-DD dates in UTC. The to date includes that whole UTC day. For example, from=2025-01-01 and to=2025-12-31 define a date range without asking for date sorting. Do not send ISO datetime strings, arbitrary query DSL, a sort parameter, or parent_id/link_id filters. Unsupported parameters are rejected.

Pick the endpoint for the task

GET /v1/posts and GET /v1/comments restrict the kind and accept the search filters; they do not require an id. GET /v1/item?id=RECORD_ID looks up an available record by its id. GET /v1/subreddits?prefix=hik&limit=3 returns a bounded subreddit aggregation; its counts are not a guarantee of global exactness.

GET /v1/status is public and uncharged. It returns a static historical-archive disclosure and shows that the HTTP handler responds. It does not query the search backend, establish content coverage or measure archive health. None of these endpoints provides posting, voting, messages, account bookmarks or a complete conversation tree.

Read the pagination fields before adding Show more

Retrieval responses contain data, pagination and credits. Records in data are flat upstream source objects; a chosen title, author, date or permalink may be missing. The archive uses _doc order, not chronological, relevance or score order. Local sorting can reorder the fetched subset but cannot make it the globally newest or highest-ranked subset.

Keep the same filters and limit when incrementing pagination.page. pagination.has_more uses a lookahead record when available. When it is false, do not offer an automatic next request. pagination.window_exhausted identifies the bounded final-page condition; reaching it is not proof that all matching archive material was retrieved.

Limits are 1–100 records and pages 1–100. pagination.total must be read with pagination.relation: eq is exact for the response’s count semantics, gte is a lower bound, and unknown provides no reliable total, which may be null. An empty page beyond page one cannot prove a total. A full page 100 at limit 100 has no spare lookahead and is a lower bound; has_more is false at the page cap. For subreddit aggregation, total is unknown and pagination.truncated flags omitted aggregation buckets.

Handle billing and failures explicitly

A successful retrieval costs one credit, including an empty data array. Validate input before sending it, and do not fetch pages just to animate a loading indicator. HTTP 400 indicates invalid input; 401 a missing or invalid service key; 402 insufficient credits; 429 a rate limit. Those rejected requests do not reserve a retrieval credit.

A failed upstream request is reported as HTTP 502 and releases the reserved credit, or reports pending refund reconciliation. A lost response at your app boundary leaves the outcome uncertain; do not assume it was free. Keep query state, respect Retry-After and let the user choose a retry when appropriate. Credential and balance work belongs to the operator, not to the walker.

Map the response to an honest reading screen

Escape record prose before rendering it. Preserve source identity and a source link when available, label missing dates as unknown, and distinguish record creation time from the time your app fetched it. Parent and link identifiers can support local grouping when present, but they do not supply missing ancestors.

Interface states develops the proposed loading, empty and failure messages. The Field notes on App walkthrough cover cards, local saved references and request budgeting. Key and credits contains both account setup and pricing. Review and test your own implementation; these examples do not establish live functionality or current trail advice.