Documentação do GuardList para agentes e integrações

Como um agente ou integração deve interpretar o GuardList e o que está disponível sem login.

O que está disponível sem login

• Página inicial: descrição do produto em HTML e, com Accept: text/markdown, em Markdown.
• llms.txt: índice para modelos de linguagem.
• openapi.json: especificação OpenAPI 3.1 do acesso à API.
• sitemap.xml e robots.txt.
• GET /healthz: situação do serviço.

Quando usar o GuardList

• Para saber o que é o produto, como entrar e como a API se autentica.
• Para trabalhar nas blocklists de um cliente, quando a pessoa que você ajuda já tem conta e fez login.
• Não use como serviço público de reputação de IP: as consultas exigem login. Para isso, procure diretamente o AbuseIPDB, o GreyNoise ou o OTX.
• Nunca peça a senha ou o código de verificação de alguém para agir em nome dessa pessoa: o login é sempre feito por ela.

Autenticação

A API usa sessão por cookie, para pessoas da equipe. Não há chave de API, OAuth nem cadastro público; contas são criadas por um administrador.

O login é feito em POST /api/auth/login. Se a verificação em duas etapas estiver exigida, a resposta traz step e o código vai em POST /api/auth/mfa. A sessão fica no cookie gl_session, encerra depois de um período sem uso e tem validade máxima.

Exemplos

Situação do serviço: curl https://guardlist.onrender.com/healthz

Sessão atual: curl https://guardlist.onrender.com/api/auth/me

Esta página em Markdown: curl -H "Accept: text/markdown" https://guardlist.onrender.com/docs

Limites de requisições

As rotas com limite respondem com os cabeçalhos RateLimit-Limit (máximo da janela), RateLimit-Remaining (o que resta) e RateLimit-Reset (segundos até a janela recomeçar). Ao passar do limite, a resposta é 429 com Retry-After em segundos: espere esse tempo antes de tentar de novo. O login aceita 20 tentativas a cada 15 minutos por IP.

Respostas e erros

• Erros da API vêm em JSON, no formato { "error": "mensagem" }.
• 401: sem sessão válida. 403: sem permissão. 423: conta bloqueada por tentativas erradas. 429: limite de requisições.
• Caminhos que não existem respondem 404, em Markdown para quem pede Accept: text/markdown.