Autenticação e rotas
As consultas de recuperação usam GET em https://api.redditapicloud.com. Envie X-API-Key: <chave> ou Authorization: Bearer <chave>; ambas as opções são válidas. Guarde o segredo no seu servidor. O painel da conta usa uma sessão com cookie Secure HttpOnly, independente dos cabeçalhos de autenticação exigidos para que o seu aplicativo recupere dados do arquivo.
/v1/search pesquisa publicações e comentários, enquanto /v1/posts restringe a seleção a publicações e /v1/comments a comentários. Essas três rotas não aceitam id como filtro. Para um identificador conhecido, /v1/item?id=... consulta um registro individual. A operação não recupera automaticamente os comentários filhos, a cadeia de antecessores nem todos os registros de uma discussão.
/v1/subreddits aceita apenas prefix e limit, sem page. Busca prefixos de nomes de comunidades, não temas do conteúdo, e suas contagens não são um censo global exato. /v1/status é público e não cobra créditos: declara o escopo estático e confirma a resposta HTTP, sem testar o mecanismo de busca, a chave ou o saldo.
Filtros e dados devolvidos
Os parâmetros de search, posts e comments são q, subreddit, author, kind, from, to, min_score, limit e page. kind aceita os valores literais post e comment. q faz busca textual, sem executar uma linguagem arbitrária de consultas e sem classificar sentimentos. A escolha de filtros precisa considerar que um comentário relevante pode depender de outro texto excluído pela seleção.
from e to usam YYYY-MM-DD em UTC e filtram created_utc. O dia indicado em to é incluído por inteiro. Esses parâmetros não recebem horários ou segundos e não representam a data de inclusão no arquivo. min_score define um limiar numérico de pontuação, sem ordenar os resultados nem identificar automaticamente respostas mais úteis para a sua aplicação.
As respostas da API são registros planos, o que significa que não há árvores de thread montadas pelo servidor. Quando os campos de identificação pai ou link estão presentes, o cliente pode agrupá-los localmente, mas não há garantia de completude ou ancestralidade garantida para todas as conversas. Não existem filtros de consulta expostos para esses campos relacionais, mantendo a simplicidade e a previsibilidade das consultas realizadas via interface padrão. A resposta contém data, pagination e credits. Campos podem faltar ou apontar para registros não recebidos; valide-os antes de exibi-los.
Limites e tratamento de falhas
limit e page aceitam valores entre 1 e 100. Os resultados seguem _doc, uma ordem interna que não expressa cronologia, relevância ou pontuação. Uma ordenação local só reorganiza o conjunto já recebido. Dividir datas ou percorrer páginas ajuda a organizar o trabalho, mas não comprova cobertura completa, unicidade dos registros ou estabilidade entre solicitações remotas.
Leia pagination.total junto com relation. eq indica um total exato para a consulta; gte informa um limite inferior; unknown indica que não há total confiável, possivelmente null. Nenhuma dessas relações comprova a presença de toda a história da comunidade. Mesmo um total exato não demonstra que você baixou todos os resultados. Preserve também os indicadores de paginação retornados.
HTTP 400 indica parâmetros inválidos, 401 uma chave ausente ou inválida, 402 saldo insuficiente e 429 limite de frequência. Cada recuperação bem-sucedida custa um crédito, mesmo vazia. Solicitações inválidas não descontam saldo; falhas do serviço de origem devolvem a reserva. Perder a resposta no cliente pode ocultar um sucesso cobrado. Uma nova tentativa bem-sucedida consome outro crédito; grave a resposta antes de avançar seu controle local.
