Para desenvolvedores e agentes

API pública de Antonio Alves

Todos os textos publicados neste site podem ser lidos por máquina. A API é somente leitura, não pede chave nem cadastro e responde em JSON. Os textos estão em português e o corpo vem em Markdown.

Quando usar (when to use)

Citar ou resumir um ensaio de Antonio Alves com o texto integral e o link original.
Responder perguntas sobre Schopenhauer, liberdade, existência, política e cultura a partir dos textos do autor.
Listar os livros do autor, com editora, ano e onde comprar.
Encontrar textos por assunto ou por palavra.

Endereço base (base URL)

https://antonioalvesfilosofia.com.br/api/v1

Especificação completa em /openapi.json (OpenAPI 3.1). Cada operação tem um operationId pronto para function calling.

Rotas (endpoints)

Rota	operationId	O que faz
`GET /ensaios`	`listarTextos`	Lista os textos publicados. Filtros opcionais: `categoria=ensaio
`GET /ensaios/{slug}`	`obterTexto`	Um texto completo, com o corpo em Markdown.
`GET /buscar?q=<termo>`	`buscarTextos`	Busca no título, no resumo e no corpo. Até 50 resultados.
`GET /livros`	`listarLivros`	Livros publicados pelo autor. Filtro opcional: `ano=<AAAA>`.
`GET /tags`	`listarAssuntos`	Assuntos dos textos, com a contagem de cada um. Filtro opcional: `min_textos=<n>`.

Referência das rotas (endpoint reference)

GET /ensaios — listarTextos

Lista todos os textos publicados, do mais recente ao mais antigo, sem o corpo.

categoria (opcional, texto): ensaio, conto ou artigo. Outro valor devolve 400 categoria-invalida.
tag (opcional, texto): slug de um assunto, como devolvido por GET /tags.
Resposta 200: { total, ensaios: [ResumoTexto] }. Cada item traz slug, titulo, categoria, data, excerto, tags, imagem, url e url_api.

GET /ensaios/{slug} — obterTexto

Devolve um texto publicado inteiro. O corpo vem em conteudo_md, em Markdown com notas de rodapé no formato GFM ([^1]).

slug (obrigatório, no caminho): o mesmo final da URL pública /ensaios/{slug}/.
Resposta 200: os campos de ResumoTexto mais data_publicacao_original, tempo_leitura_minutos e conteudo_md.
Resposta 404: ensaio-nao-encontrado quando o slug não existe ou o texto ainda é rascunho.

GET /buscar — buscarTextos

Procura o termo no título, no resumo e no corpo dos textos publicados. Devolve até 50 resultados.

q (obrigatório, texto, mínimo 2 caracteres). Sem ele, a resposta é 400 termo-ausente.
Resposta 200: { termo, total, ensaios: [ResumoTexto] }.

GET /livros — listarLivros

Lista os livros publicados pelo autor, do mais recente ao mais antigo.

ano (opcional, inteiro): só livros daquele ano. Valor que não é inteiro devolve 400 parametro-invalido.
Resposta 200: { total, livros: [Livro] }, com titulo, subtitulo, autor, ano, editora, paginas, capa, descricao_md e link_compra.

GET /tags — listarAssuntos

Lista os assuntos dos textos publicados, do mais frequente ao menos frequente.

min_textos (opcional, inteiro): só assuntos com pelo menos esse número de textos.
Resposta 200: { total, tags: [Assunto] }, com slug, rotulo, total_textos e url.

Exemplos de requisição (example requests)

curl https://antonioalvesfilosofia.com.br/api/v1/ensaios?categoria=ensaio
curl https://antonioalvesfilosofia.com.br/api/v1/buscar?q=schopenhauer
curl https://antonioalvesfilosofia.com.br/api/v1/ensaios/<slug>
curl https://antonioalvesfilosofia.com.br/api/v1/tags?min_textos=3

Resposta de GET /buscar?q=schopenhauer (resumida):

{
  "termo": "schopenhauer",
  "total": 1,
  "ensaios": [
    {
      "slug": "<slug>",
      "titulo": "<título>",
      "categoria": "ensaio",
      "data": "2024-05-10",
      "excerto": "<resumo>",
      "tags": [{ "slug": "schopenhauer", "rotulo": "Schopenhauer" }],
      "url": "https://antonioalvesfilosofia.com.br/ensaios/<slug>/",
      "url_api": "https://antonioalvesfilosofia.com.br/api/v1/ensaios/<slug>"
    }
  ]
}

As páginas do site também respondem em Markdown quando o pedido traz Accept: text/markdown:

curl -H 'Accept: text/markdown' https://antonioalvesfilosofia.com.br/
curl -H 'Accept: text/markdown' https://antonioalvesfilosofia.com.br/ensaios/<slug>/

Autenticação (authentication)

Nenhuma: não há chave, token nem OAuth. Todas as rotas de /api/v1/ são públicas e aceitam CORS de qualquer origem. As rotas fora de /api/v1/ são do painel do autor e respondem 401.

Limites (rate limits)

Até 20 requisições a cada 10 segundos por IP. Toda resposta traz o cabeçalho RateLimit-Policy: "padrao";q=20;w=10. Acima do limite, a resposta é 429 com Retry-After em segundos. As respostas ficam em cache por 60 segundos.

Política de versionamento e descontinuação (versioning and deprecation policy)

A versão vai no caminho: /api/v1/.
Dentro da v1, campos só são acrescentados, nunca renomeados ou removidos.
Uma mudança incompatível abre a /api/v2/. A v1 continua no ar por pelo menos 6 meses depois disso.
Durante esse prazo, as respostas da v1 trazem os cabeçalhos Deprecation (RFC 9745) e Sunset (RFC 8594) com a data de desligamento, e esta seção registra o cronograma.
Cronograma atual: nenhuma versão descontinuada.

Erros (errors)

Erros seguem a RFC 9457 (application/problem+json), com code estável e resolution dizendo o que fazer.

{
  "type": "https://antonioalvesfilosofia.com.br/docs/#erro-termo-ausente",
  "title": "Termo de busca ausente",
  "status": 400,
  "detail": "O parâmetro q precisa ter ao menos 2 caracteres.",
  "instance": "/api/v1/buscar",
  "code": "termo-ausente",
  "resolution": "Envie GET /api/v1/buscar?q=schopenhauer (ou outro termo).",
  "documentation_url": "https://antonioalvesfilosofia.com.br/docs/"
}

code	Status	Quando acontece
`categoria-invalida`	400	O parâmetro `categoria` não é ensaio, conto nem artigo.
`parametro-invalido`	400	Um parâmetro numérico (`ano`, `min_textos`) não é um inteiro válido.
`termo-ausente`	400	A busca veio sem `q`, ou com menos de 2 caracteres.
`nao-autorizado`	401	A rota é do painel administrativo. Use as rotas de `/api/v1/`.
`ensaio-nao-encontrado`	404	Nenhum texto publicado com esse slug.
`rota-inexistente`	404	A rota não existe na API v1.

Uso dos textos

Os textos são de Antonio Alves Pereira Junior. Cite o autor e linke a página original (url em cada resposta). Para outros usos, escreva pela página de contato.

Outros recursos

/llms.txt — guia curto para modelos de linguagem.
/sitemap.xml — todas as páginas públicas.
/rss.xml — feed dos textos novos.