# 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.

```bash
# 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/blog
```

## Endpoints 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 |

[OpenAPI JSON](https://leesugano.com/openapi.json) · [OpenAPI YAML](https://leesugano.com/openapi.yaml)

## 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.

```bash
curl -sI -H "Accept: text/markdown" https://leesugano.com/blog
curl -s https://leesugano.com/blog.md
```

## Formato 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.

- [agents.md](https://leesugano.com/agents.md)
- [llms.txt](https://leesugano.com/llms.txt)
- [llms-full.txt](https://leesugano.com/llms-full.txt)

---

- Versión HTML: https://leesugano.com/es/docs
- Lee Sugano Digital Solutions - contact@leesugano.com

## Dónde buscar

- [Inicio](https://leesugano.com/es)
- [Sobre la empresa](https://leesugano.com/es/about)
- [Servicios](https://leesugano.com/es/servicos)
- [Portafolio](https://leesugano.com/es/portfolio)
- [Blog](https://leesugano.com/es/blog)
- [Preguntas frecuentes](https://leesugano.com/es/faq)
- [Documentación para desarrolladores y agentes](https://leesugano.com/es/docs)
- [Contacto](https://leesugano.com/es/contact)
- [Política de Privacidad](https://leesugano.com/es/privacidade)
- [Términos de Uso](https://leesugano.com/es/termos)
- [Ley de Transacciones Comerciales Especificadas](https://leesugano.com/es/tokushoho)

## Otros idiomas

- [pt](https://leesugano.com/docs)
- [en](https://leesugano.com/en/docs)
- [ja](https://leesugano.com/ja/docs)

## Recursos legibles por máquina

- [Resumen canónico para IA (llms.txt)](https://leesugano.com/llms.txt)
- [Instrucciones para agentes (cuándo usarnos)](https://leesugano.com/agents.md)
- [Especificación OpenAPI de la API pública](https://leesugano.com/openapi.json)
- [Documentación para desarrolladores y agentes](https://leesugano.com/es/docs)
- [Mapa del sitio (XML)](https://leesugano.com/sitemap.xml)
- [Feed RSS del blog](https://leesugano.com/feed.xml)
