Translate read requests to the archive’s documented contract

Authentication and the operation map

Retrieval uses GET at https://api.redditproxy.com with X-API-Key: <key> or Authorization: Bearer <key>. Either header is valid. Bearer is a supported way to transmit the archive key, not Reddit OAuth compatibility. Keep the real key in backend configuration. The website account panel’s Secure HttpOnly session cookie is separate from these headers and does not authenticate your application’s retrieval calls.

/v1/search searches archived posts and comments. /v1/posts and /v1/comments restrict retrieval to their respective types. These three routes accept q, subreddit, author, kind, from, to, min_score, limit and page. kind accepts post or comment, with the specialized route already fixing its own type. They do not accept id, a target URL for forwarding or undocumented parameters from a previous client.

/v1/item requires id and accepts no other query filters. It looks up an individual item rather than a complete discussion. /v1/subreddits accepts only prefix and limit for community-name lookup; aggregation counts are not guaranteed globally exact. /v1/status is public and uncharged. Its static response describes the service and confirms the HTTP application responds, without testing search health, record availability or account balance.

Dates, flat records and page semantics

API responses contain flat records, not server-assembled thread trees. When parent_id and link_id fields are present in returned records, clients may group them locally to reconstruct conversations. This local grouping is optional and does not imply a complete conversation or ancestry guarantee from the server side.

q performs text search, not an arbitrary query language or sentiment analysis. subreddit and author restrict matching records. from and to use strict YYYY-MM-DD dates in UTC and apply to created_utc rather than ingestion time. The to day is fully included. Do not transfer an old timestamp or local-time convention unchanged; handle intraday comparisons locally using record timestamps when available. min_score applies a numeric score threshold without changing order. Internal archive document order _doc is not document-ID order, ingestion time, publication chronology, relevance or score rank. limit and page accept 1–100. Every request retrieves one page of at most 100 records, and one query permits at most 100 pages. Partitioning requests can organize work but does not guarantee an exhaustive or duplicate-free collection. A successful retrieval contains data, pagination and credits. Validate the data array and fields your application needs before conversion. Fields can vary or be absent, and parent_id and link_id are not query filters. Read pagination.total with pagination.relation: eq exact query total, gte lower bound, unknown no reliable total, possibly null. Even an exact total does not prove all matches were downloaded or the archive contains every historical record.

HTTP outcomes and credit use

HTTP 400 means invalid parameters, 401 missing or invalid authentication, 402 insufficient credits and 429 rate limiting. Correct parameter, credential or balance problems before repeating those requests. A bounded delay policy may be useful for 429; it is your client’s choice rather than an availability guarantee. Network-wide trial eligibility does not establish the cause or scope of a particular rate-limit response.

Invalid requests do not debit credits and upstream failures refund reservations. One successful retrieval costs one credit, even empty. Your client can lose a response after billable server success; a successful repeat costs another credit. Keep response validation errors in your own adapter separate from the archive’s HTTP result, so a local mapping failure does not become an assumed upstream refund.

Use the account panel for balances, invoices and key regeneration, not a public status poll. Sign in and explicitly create an invoice before paying its displayed exact amount and recipient, then paste the transaction hash for verification. The invoice expires in one hour and settlement timing is not guaranteed. Payment verification can remain pending during provider outages; that state does not call for a second payment.