Documentação para desenvolvedores e agentes
API pública, especificação OpenAPI, negociação de conteúdo em Markdown e servidor MCP da Lee Sugano Digital Solutions.
Esta página descreve tudo o que o leesugano.com expõe para ser consumido por programa: a API pública de conteúdo, a especificação OpenAPI que a descreve, a representação Markdown das páginas do site e o servidor MCP.
Nada aqui exige chave de API nem cadastro. Os endpoints são públicos, com limite de taxa por IP, e todas as respostas (inclusive erros) são JSON.
Começo rápido
Três chamadas cobrem a maior parte dos casos: ler a especificação, listar os posts publicados e ler qualquer página do site em Markdown.
# OpenAPI
curl -s https://leesugano.com/openapi.json
# listPublishedPosts
curl -s "https://leesugano.com/api/posts?limit=5&locale=en"
# Markdown
curl -s -H "Accept: text/markdown" https://leesugano.com/blogEndpoints públicos
Todos os endpoints abaixo aceitam requisições anônimas. Os schemas completos de requisição e resposta estão na especificação OpenAPI.
| Método | Caminho | operationId | O que faz |
|---|---|---|---|
| GET | /api/posts | listPublishedPosts | List published blog posts |
| GET | /api/categories | listCategories | List blog categories |
| GET | /api/tags | listTags | List blog tags |
| GET | /api/posts/{id}/reactions | getPostReactions | Read a post's reactions |
| POST | /api/posts/{id}/reactions | reactToPost | Add, switch or remove a reaction |
| POST | /api/newsletter | subscribeToNewsletter | Subscribe an email to the newsletter |
| POST | /api/start/recommend | recommendSolution | Recommend a solution from a business profile |
| GET | /api/og | renderOpenGraphImage | Render a 1200x630 Open Graph image |
Markdown na mesma URL
Toda página pública é servida em HTML para navegadores e em Markdown para agentes, na mesma URL, decidido pelo header Accept conforme a convenção do acceptmarkdown.com.
As respostas trazem Vary: Accept, então CDNs guardam as duas representações separadamente. Se preferir uma URL explícita, basta acrescentar .md ao caminho.
curl -sI -H "Accept: text/markdown" https://leesugano.com/blog
curl -s https://leesugano.com/blog.mdFormato de erro
Erro nunca vem em HTML. Toda falha devolve um objeto JSON com os campos abaixo, e o status HTTP correspondente.
Escreva sua lógica em cima de code, que é estável, e não do texto de error, que pode mudar.
| Campo | Significado |
|---|---|
error | Mensagem legível por humanos. Pode mudar sem aviso. |
code | Código estável em SCREAMING_SNAKE_CASE. Use este na sua lógica. |
requestId | Identificador da requisição, também no header x-request-id. |
details | Detalhes de validação. Presente apenas em ambiente de desenvolvimento. |
Limites de taxa
Os 7 endpoints públicos aplicam limite por IP numa janela de 60 segundos.
Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Quando o limite estoura, a resposta é 429 com Retry-After em segundos. Use esses headers para se autorregular em vez de tentar de novo em loop.
| Endpoint | Limite |
|---|---|
GET /api/posts | 60 req/min por IP / 60s |
GET /api/categories | 60 req/min por IP / 60s |
GET /api/tags | 60 req/min por IP / 60s |
GET /api/posts/{id}/reactions | 60 req/min por IP / 60s |
POST /api/posts/{id}/reactions | 20 req/min por IP / 60s |
POST /api/newsletter | 10 req/min por IP / 60s |
POST /api/start/recommend | 8 req/min por IP / 60s |
Servidor MCP
Há um servidor Model Context Protocol em https://mcp.leesugano.com, sobre transporte Streamable HTTP.
Ele é protegido por OAuth: a listagem de ferramentas fica disponível após a autorização, não anonimamente.
Para agentes de IA
As instruções operacionais - em que trabalhos a agência é a escolha certa, em quais não é, e qual chamada resolve cada intenção - estão em /agents.md.
Os fatos canônicos sobre a empresa estão em /llms.txt e, na versão expandida, em /llms-full.txt.
Recursos legíveis por máquina
Arquivos estáveis, com cache e CORS liberado.