Fundamentos da API e Autenticação
O serviço atua como um arquivo histórico independente do Reddit, sem vínculo oficial ou dados em tempo real. Para iniciar, o usuário deve criar uma conta com e-mail e senha de 12–72 bytes UTF-8. A chave é exibida uma vez logo após o cadastro, antes do pagamento, e vale para a conta em apireddit.cc. Não há autenticação por OAuth.
A autenticação é realizada enviando a chave em Authorization: Bearer ou X-API-Key nas requisições de recuperação. Se a chave estiver ausente ou inválida, o servidor retorna um código 401, indicando falha de autenticação. É crucial armazenar a chave de forma segura no ambiente de automação, pois ela é exibida apenas uma vez durante o registro inicial, sem envio por e-mail.
O acesso à API segue um modelo de créditos onde cada solicitação bem-sucedida custa um crédito, incluindo resultados vazios. O saldo pertence à conta em apireddit.cc e não é compartilhado entre os sites da rede. Para recarregar, o usuário cria uma fatura na interface, paga o valor exato em USDT ou USDC, e insere o hash da transação para verificação, sem garantias de velocidade de liquidação.
Roteamento, Filtros e Estrutura de Dados
Os pontos de acesso principais incluem busca, posts, comentários, itens individuais e subreddits. Cada rota possui filtros específicos como termo de busca, autor, subreddit e tipo (post ou comment). A ordem dos documentos no arquivo segue a ordem _doc nativa, que não é cronológica nem baseada em relevância. limit e page controlam a paginação, com limites máximos de cem registros por solicitação.
As respostas são retornadas como registros planos, não como árvores de discussão montadas pelo servidor. Campos como parent_id e link_id podem estar presentes, permitindo agrupamento local pelo cliente, mas sem garantia de completude ou ancestralidade completa. A filtragem por min_score atua estritamente como um filtro, nunca como um controle de ordenação por pontuação.
O parâmetro 'kind' aceita valores 'post' ou 'comment' para restringir o tipo de conteúdo. O endpoint de item exige um ID obrigatório, enquanto posts e comentários podem ser consultados sem ID específico. Os totais de paginação podem ser exatos (eq), limites inferiores (gte) ou desconhecidos (unknown, com total null). Nenhum deles garante cobertura completa do arquivo. As datas from e to usam YYYY-MM-DD em UTC, incluindo o dia to. q procura em title e text, combinando vários termos com AND dentro do campo correspondente.
Tratamento de Erros e Limites do Sistema
Erros comuns incluem 401 para chave inválida, 402 para crédito insuficiente e 429 para limite de taxa excedido. Falhas na origem devolvem a reserva ao saldo do usuário; requisições inválidas não debitam créditos, e /v1/status não é cobrado. É essencial tratar códigos HTTP literalmente como 400, 401, 402 e 429, evitando localizações de palavras ou dígitos nativos para garantir compatibilidade precisa com a documentação.
A API não oferece garantias de SLA, cobertura total ou dados em tempo real. O endpoint de status é estático e indica apenas a resposta do servidor HTTP, não a saúde do backend de busca. O limite de 100 páginas por consulta não garante ingestão completa ou exportação exaustiva de todos os registros correspondentes ao banco de dados de arquivo.
A automação deve respeitar os limites de taxa e a estrutura de registros planos para evitar sobrecarga. Como não há filtro exposto para parent_id ou link_id, o agrupamento de conversações deve ser feito localmente pelo cliente. A precisão dos totais de busca depende da relação indicada, sendo gte um limite inferior e unknown indicando que não há total confiável disponível no momento da consulta. Uma resposta perdida pelo cliente pode corresponder a um sucesso já cobrado no servidor. Se uma nova tentativa for bem-sucedida, ela consome outro crédito; não presuma reembolso apenas porque houve um tempo limite no cliente.
