Autenticación y rutas de lectura
Las rutas de recuperación utilizan GET en https://api.redditstreamapi.com. Puedes autenticarte con X-API-Key: <clave> o Authorization: Bearer <clave>. Ambas cabeceras están admitidas. Guarda el secreto en tu servidor. La cookie Secure HttpOnly mantiene la sesión del panel de cuenta y no sustituye la cabecera necesaria para consultar datos desde tu aplicación.
/v1/search busca publicaciones y comentarios; /v1/posts restringe la búsqueda a publicaciones y /v1/comments a comentarios. Estas rutas no reciben id como filtro. Para consultar un registro identificado utiliza /v1/item?id=...: requiere ese identificador y no devuelve automáticamente sus respuestas, sus descendientes o todos los mensajes de la misma conversación.
/v1/subreddits admite prefix y limit para descubrir comunidades. El prefijo no es un filtro de las consultas de contenido. Sus recuentos no deben tratarse como un censo global exacto. /v1/status es público y no consume créditos: describe estáticamente el servicio y confirma que responde la aplicación HTTP, sin comprobar el buscador ni la disponibilidad de registros.
Filtros y forma de la respuesta
En search, posts y comments los parámetros admitidos son q, subreddit, author, kind, from, to, min_score, limit y page. kind acepta post o comment, conservando esos valores literales. q realiza una búsqueda textual, no ejecuta un lenguaje arbitrario de consultas ni clasifica sentimientos. Combina filtros deliberadamente para no excluir mensajes que después necesites como contexto.
Las fechas from y to usan YYYY-MM-DD en UTC y se aplican a created_utc. El día to se incluye completo; no es un instante de exclusión a medianoche. Estos parámetros no expresan horas ni segundos. min_score es un umbral numérico de puntuación, no un selector de respuestas correctas ni un criterio de ordenación.
Las respuestas devuelven registros planos que no representan árboles de hilos ensamblados por el servidor. Aunque los objetos pueden contener campos como parent_id y link_id, el cliente debe agruparlos localmente si desea reconstruir conversaciones. No hay garantía de que estos campos estén presentes en todos los registros recuperados. La agrupación local no garantiza una conversación completa. No hay filtros de consulta para parent_id o link_id. La respuesta contiene data, pagination y credits; referencias presentes pueden apuntar a registros no recibidos.
Paginación, errores y cobro
En /v1/search, /v1/posts y /v1/comments, limit y page admiten valores de 1 a 100, con una página por solicitud. La entrega sigue _doc, un orden interno sin ordenación cronológica, por relevancia o puntuación. /v1/subreddits solo acepta prefix y limit, sin page. Ordenar localmente o dividir períodos no demuestra cobertura exhaustiva, unicidad o estabilidad entre consultas.
Interpreta pagination.total junto con relation: eq expresa un total exacto de la consulta, gte una cota inferior y unknown un total no fiable, que puede ser null. Un total exacto tampoco prueba haber descargado todos los registros ni que el archivo contenga toda la historia. Conserva los indicadores has_more y window_exhausted para documentar los límites de la respuesta.
HTTP 400 indica parámetros inválidos, 401 una clave ausente o inválida, 402 saldo insuficiente y 429 un límite de frecuencia. Una recuperación exitosa, incluso vacía, consume un crédito. Las solicitudes inválidas no descuentan saldo; los fallos del origen devuelven la reserva. Una desconexión del cliente puede ocultar un éxito cobrado y una repetición exitosa se cobra de nuevo. Guarda las respuestas antes de actualizar el progreso local.
Rutas de la API
| Método | Ruta | Parámetros |
|---|---|---|
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 | — |
Parámetros de consulta
| Parámetro | Valor / tipo / intervalo |
|---|---|
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);