Portal para desarrolladores y agentes

Tres llamadas y ya tienes el mapa completo: comprueba que la API responde, léela desde su especificación y pide el perfil.

curl -s https://sgomez.dev/api/v1/health
curl -s https://sgomez.dev/openapi.json
curl -s https://sgomez.dev/api/v1/profile

No hay sandbox aparte ni claves de prueba: la API es de solo lectura y todo su contenido ya es público, así que el entorno de producción ES el entorno de pruebas. No hay nada que puedas romper con un GET.

Las colecciones aceptan limit (1–100) y offset (0–1000). search acepta q (obligatorio) y limit (1–50). Toda respuesta correcta va envuelta en { "data": …, "meta": … }, y meta incluye count, total, self y documentation_url.

Los errores también son JSON, con el mismo sobre siempre. code es estable y se puede usar en un switch; hint dice qué hacer para arreglarlo, que es lo que a un agente le falta cuando recibe un 404 vacío.

{
  "error": {
    "status": 404,
    "code": "not_found",
    "message": "No project with slug \"nope\".",
    "hint": "Known slugs: nudaui, sortlab, … List them with GET /api/v1/projects.",
    "documentation_url": "https://sgomez.dev/developers"
  }
}

• 400 invalid_parameter — un parámetro falta o está fuera de rango.
• 404 not_found — el recurso o el endpoint no existe. Cualquier ruta desconocida bajo /api responde JSON, nunca HTML.
• 405 method_not_allowed — la API es de solo lectura; la respuesta incluye la cabecera Allow.

No hay autenticación ni claves de API: no existe ningún dato privado detrás, así que una clave solo sería un trámite. Tampoco hay límite de peticiones por cliente más allá de la protección ordinaria de la CDN. A cambio, las respuestas se sirven cacheadas (Cache-Control: public, max-age=300, s-maxage=3600): si necesitas el catálogo entero, una llamada por colección basta, y repetir la misma llamada en bucle no te dará datos más frescos.

CORS está abierto a cualquier origen (Access-Control-Allow-Origin: *) para GET, HEAD y OPTIONS, así que la API se puede llamar desde el navegador. Los datos se publican bajo licencia CC BY 4.0: úsalos citando la fuente.

La especificación es OpenAPI 3.1 y se genera desde el mismo código que sirve los endpoints, así que no puede describir una ruta que ya no existe. Cada operación tiene operationId único, summary, description, parámetros tipados y un esquema de respuesta por código, que es justo lo que necesita un cliente de function calling para convertirla en herramientas.

• /openapi.json — Ubicación canónica.
• /api/openapi.json — El mismo documento bajo /api.
• /api/openapi.yaml — El mismo documento en YAML.

Las páginas de contenido se sirven en markdown cuando la petición lo pide, siguiendo la convención de acceptmarkdown.com. La URL canónica no cambia y la respuesta lleva Vary: Accept, para que una CDN no le dé a un agente la variante HTML que guardó para un navegador.

curl -s -H "Accept: text/markdown" https://sgomez.dev/about

# o, si prefieres una URL explícita:
curl -s https://sgomez.dev/about.md

Funciona en /, /about, /contact, /privacy, /developers y /lab. Las rutas que ya son markdown (/llms.txt, /agents.md) se sirven tal cual. Una ruta que no existe devuelve 404 con un cuerpo markdown que dice a dónde ir, en vez de una página de error que un agente no sabe leer.

• /llms.txt — Resumen factual del sitio, con la sección «when to use this».
• /agents.md — Instrucciones de uso: para qué sirve este sitio y cómo llamarlo.
• /sitemap.xml — Todas las URLs publicadas.
• /robots.txt — Crawlers de IA explícitamente permitidos.
• /manifest.webmanifest — Manifiesto de la aplicación web.

La versión va en la ruta (/api/v1). Dentro de v1 solo se añaden campos y endpoints: quitar un campo o renombrar un operationId sería un cambio incompatible y saldría en /api/v2. Los code de error forman parte del contrato y no se renombran.