Documentación para desarrolladores y agentes
API pública, especificación OpenAPI, negociación de contenido en Markdown y servidor MCP de Lee Sugano Digital Solutions.
Esta página describe todo lo que leesugano.com expone para uso programático: la API pública de contenido, la especificación OpenAPI que la describe, la representación en Markdown de cada página y el servidor MCP.
Nada de esto requiere clave de API ni registro. Los endpoints son públicos, con límite de tasa por IP, y todas las respuestas, incluidos los errores, son JSON.
Inicio rápido
Tres llamadas cubren la mayoría de los casos: leer la especificación, listar los artículos publicados y leer cualquier página del sitio en 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 los endpoints aceptan peticiones anónimas. Los esquemas completos de petición y respuesta están en la especificación OpenAPI.
| Método | Ruta | operationId | Qué hace |
|---|---|---|---|
| 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 en la misma URL
Cada página pública se sirve en HTML a los navegadores y en Markdown a los agentes, desde la misma URL, según la cabecera Accept y la convención de acceptmarkdown.com.
Las respuestas incluyen Vary: Accept, por lo que las CDN almacenan las dos representaciones por separado. Si prefieres una URL explícita, añade .md a la ruta.
curl -sI -H "Accept: text/markdown" https://leesugano.com/blog
curl -s https://leesugano.com/blog.mdFormato de error
Los errores nunca llegan en HTML. Cada fallo devuelve un objeto JSON con los campos siguientes y el estado HTTP correspondiente.
Basa tu lógica en code, que es estable, y no en el texto de error, que puede cambiar.
| Campo | Significado |
|---|---|
error | Mensaje legible por humanos. Puede cambiar sin aviso. |
code | Código estable en SCREAMING_SNAKE_CASE. Úsalo en tu lógica. |
requestId | Identificador de la petición, también en la cabecera x-request-id. |
details | Detalles de validación. Presente solo en desarrollo. |
Límites de tasa
Los 7 endpoints públicos aplican límite por IP en una ventana de 60 segundos.
Cada respuesta incluye RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Al superar el límite se devuelve un 429 con Retry-After en segundos. Autorregúlate con esas cabeceras en lugar de reintentar en bucle.
| Endpoint | Límite |
|---|---|
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
Hay un servidor Model Context Protocol en https://mcp.leesugano.com sobre transporte Streamable HTTP.
Está protegido con OAuth: el listado de herramientas está disponible tras la autorización, no de forma anónima.
Para agentes de IA
Las instrucciones operativas - para qué trabajos esta agencia es la opción correcta, para cuáles no, y qué llamada resuelve cada intención - están en /agents.md.
Los hechos canónicos sobre la empresa están en /llms.txt y, en versión ampliada, en /llms-full.txt.
Recursos legibles por máquina
Archivos estables, con caché y CORS abierto.