Protected reads and the public status exception
Protected reads use GET under https://api.redditstreamapi.com with X-API-Key: <key> or Authorization: Bearer <key>. Both alternatives carry this domain's archive key, not a Reddit OAuth token. Keep the secret server-side. The account panel's Secure HttpOnly session cookie is separate from retrieval authentication. The service provides discrete JSON responses rather than a live SSE stream, WebSocket connection or subscription to Reddit events.
/v1/search searches posts and comments. /v1/posts constrains results to posts and /v1/comments to comments. All three accept q, subreddit, author, kind, from, to, min_score, limit and page, not id. kind accepts post or comment; omit it to allow both through search. q is text search, without arbitrary query DSL, sentiment classification or server-side custom analytics.
/v1/item?id=... requires id only and looks for one archived record, which may be absent. It does not walk parents or replies. /v1/subreddits accepts prefix and limit only for community-name discovery, without page traversal or guaranteed globally exact counts. /v1/status is public and uncharged: its static scope disclosure confirms that the HTTP application responds, without checking search availability, record freshness, key validity or balance.
Date windows, fields and document order
from and to accept YYYY-MM-DD in UTC and filter created_utc, not when a record entered the archive. The complete final to day is included. These are day filters, not intraday cursor values. If you divide work by date, record the actual bounds and distinguish your job's processing time from source creation time. Such partitioning does not prove exhaustive retrieval or a schedule of archive updates.
min_score sets a numeric score threshold without sorting or assessing advice quality. Retrieval follows internal _doc order, not insertion time, chronology, relevance or score. The last record on a page is therefore not a guaranteed chronological watermark. Local sorting can organize the received records, but cannot establish that every earlier record was received or every later record will appear in a future request.
Content records are flat and fields can vary. Present parent_id and link_id may support local grouping, without complete ancestry or conversations. Neither is an exposed query filter. Responses contain data, pagination and credits. Validate the received data and preserve missing fields and unresolved references instead of inventing values needed by your destination schema. A successful empty data array is not an authentication error.
Page boundaries, totals and failure handling
Content routes accept limit and page from 1 to 100, one page per request. page=2 does not return pages one and two together. Page numbering is not a stable cursor or event sequence, and there is no supported page=101 for the same query. Smaller windows and local deduplication may organize a batch, without proving complete coverage, unique records or unchanged repeated results.
Read pagination.total with relation: eq means an exact query total, gte a lower bound and unknown no reliable total, possibly null. An empty page after page one can return unknown rather than a count of zero. An exact total does not prove that all matches were downloaded or that the archive contains all history. Preserve returned has_more and window_exhausted as boundary signals, not unlimited-export tokens.
HTTP 400 concerns 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. Every successful retrieval costs one credit, even empty or repeated. Response loss may conceal a billed success, and a local processing failure does not refund it. Save the received response before advancing local progress and budget successful retries separately.
API routes
| Method | Route | Parameters |
|---|---|---|
GET | /v1/search | q, subreddit, author, kind, from, to, min_score, limit, page |
GET | /v1/posts | q, subreddit, author, kind, from, to, min_score, limit, page |
GET | /v1/comments | q, subreddit, author, kind, from, to, min_score, limit, page |
GET | /v1/item | id |
GET | /v1/subreddits | prefix |
GET | /v1/status | — |
Query parameters
| Parameter | Value / type / range |
|---|---|
q | text |
subreddit | keyword |
author | keyword |
kind | post | comment |
from | ISO date |
to | ISO date |
min_score | integer |
limit | 1–100 |
page | 1–100 |
id | item ID |
prefix | subreddit prefix |
curl -H "Authorization: Bearer YOUR_API_KEY" 'https://api.redditstreamapi.com/v1/search?q=research&limit=10'
import json, urllib.request
request = urllib.request.Request('https://api.redditstreamapi.com/v1/search?q=research&limit=10', headers={"Authorization": "Bearer YOUR_API_KEY"})
with urllib.request.urlopen(request) as response:
print(json.load(response))
fetch("https://api.redditstreamapi.com/v1/search?q=research&limit=10", {headers: {Authorization: "Bearer YOUR_API_KEY"}})
.then(response => response.json()).then(console.log);