Desenvolvedores e agentes

Quando usar

Use estes recursos quando um agente, uma integração ou um pesquisador precisar do acervo editorial público em formato compacto e com atribuição. Para leitura visual, ações de assinante e recursos interativos, use o site normal.

Pontos de descoberta

• Índice para LLMs: mapa resumido do site público e orientações de uso.
• Índice completo para LLMs: o mesmo mapa com o endereço de todas as páginas públicas.
• Descrição OpenAPI: formatos e códigos de resposta dos documentos públicos.
• Catálogo de APIs do TheAgent: o catálogo RFC 9727 das APIs publicadas por este domínio, em JSON linkset. É o ponto de partida registrado quando você não sabe o que este site oferece.
• Declaração de confiança: compromissos editoriais e de privacidade.
• Fale conosco: canal público de contato editorial e de privacidade.
• Servidor MCP do TheAgent: Model Context Protocol sobre Streamable HTTP. Exige autenticação: responde com um desafio OAuth no initialize e não lista ferramentas para quem não se identifica. Todo o conteúdo público está disponível sem credenciais pelos endereços acima.

Negociação de conteúdo

As páginas públicas respondem conforme o cabeçalho Accept. Accept: text/markdown devolve uma versão compacta em Markdown; Accept: application/json devolve o mesmo documento tipado de GET /v1/document, de modo que a página pode ser lida como dado sem uma segunda requisição; qualquer outro formato aceito devolve o HTML do site sem mudança. A resposta sempre varia conforme Accept. Conteúdo exclusivo para assinantes nunca entra numa versão para máquinas, e uma requisição JSON nunca recebe página de erro em HTML.

Atribuição

Preserve o endereço oficial, o nome da publicação e os dados de autor e data quando existirem. Não apresente trechos como artigos completos nem sugira endosso do TheAgent.

API pública de conteúdo

Operações somente de leitura devolvem o acervo publicado em JSON. Todas estão descritas no documento OpenAPI, com identificador, descrição e esquema tipado de cada resposta.

• GET /v1/index.json: todos os endereços públicos, com tipo e data da última modificação.
• GET /v1/document?path=/alguma-pagina/: uma página pública, com endereço oficial, título e corpo em Markdown.
• GET /v1/versions.json: todas as versões publicadas, sua situação e o prazo de aviso que esta API garante.

Cite o endereço oficial que a API devolve, nunca o endereço da requisição à API. Conteúdo exclusivo para assinantes nunca é devolvido, e as requisições são lidas sem seus cookies ou credenciais.

Política de descontinuação

A versão fica no caminho, e toda resposta de /v1/ traz o cabeçalho TheAgent-Api-Version e um cabeçalho Link com rel="deprecation" apontando para esta seção. Mudança incompatível sai sob um novo prefixo /vN/; o prefixo anterior continua respondendo durante todo o prazo de aviso, para que nenhuma integração quebre sem aviso.

O prazo de aviso é de 180 dias. Uma versão marcada para sair é anunciada desde o dia em que é descontinuada: suas respostas trazem Deprecation (RFC 9745) com a data da descontinuação, Sunset (RFC 8594) com a data em que deixa de responder e um cabeçalho Link com rel="sunset". A versão atual não traz nenhum deles, só o link da política.

A situação de cada versão pode ser lida por máquina em /v1/versions.json, que também traz esta política como dado. O serviço se recusa a iniciar se alguma versão for marcada para sair com aviso menor que o publicado aqui.

Limite de requisições

As operações de /v1/ aceitam 60 requisições a cada 60 segundos por cliente e informam a situação nos cabeçalhos RateLimit e RateLimit-Policy, além do trio RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. A resposta 429 também traz Retry-After. As páginas publicadas, os sitemaps e os índices para LLMs não têm limite.

Erros

Toda falha da API é um documento application/problem+json (RFC 9457) com um código estável, um detalhe legível e uma solução que diz o que mudar. Decida pelo código, nunca pelo texto. A API nunca devolve página de erro em HTML.

Erro: invalid request

400. Falta algo que a operação exige, como o parâmetro de caminho. Solução: leia a operação no documento OpenAPI e envie o parâmetro que falta.

Erro: invalid path

400. O caminho não é o de uma página pública ou aponta para algo que esta API não lê. Solução: envie o caminho exatamente como aparece em /v1/index.json, começando com barra e sem parâmetros de consulta.

Erro: not found

404. Não existe documento público nem operação da API nesse endereço. Solução: use um caminho listado em /v1/index.json ou consulte no documento OpenAPI as operações desta versão.

Erro: members only

403. A página é exclusiva para assinantes e nunca é exposta por esta API. Solução: leia o acervo público. Conteúdo exclusivo exige sessão de assinante no próprio site.

Erro: not acceptable

406. A requisição não aceita HTML, Markdown nem JSON para um documento público. Solução: envie um cabeçalho Accept que admita text/html, text/markdown ou application/json.

Erro: method not allowed

405. A API é somente de leitura e a requisição usou método diferente de GET ou HEAD. Solução: use GET.

Erro: rate limited

429. Chegaram mais requisições deste cliente do que a janela permite. Solução: espere os segundos indicados em Retry-After, tente de novo e regule o ritmo por RateLimit-Remaining.

Erro: upstream unavailable

502. O acervo ou o documento não pôde ser lido na origem. Nada é inventado no lugar. Solução: tente de novo em instantes. Falha repetida é nossa, não da requisição.