API Documentation

Visión General

Autenticación

Todos los endpoints públicos documentados aquí son accesibles sin autenticación. Los endpoints de administración (/api/admin/*) requieren sesión NextAuth y no son parte de la API pública.

Versionado y Deprecación

curl "https://nexolatam.org/api/version"
{
  "current": "v1",
  "latest": "v1",
  "status": "stable",
  "versioning": { "strategy": "uri-path", "example": "https://nexolatam.org/api/v1/blog" },
  "deprecationPolicy": {
    "noticePeriodDays": 180,
    "headers": ["Deprecation", "Sunset"]
  }
}

Rate Limits

Los endpoints públicos aplican un límite de 60 solicitudes por minuto por IP. Cada respuesta de la API incluye encabezados estándar (RFC draft RateLimit) para que los agentes puedan auto-regularse:

# Respuesta 429 (límite excedido)
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Demasiadas solicitudes. Intenta de nuevo más tarde.",
    "hint": "Respeta el encabezado Retry-After antes de reintentar.",
    "documentation": "https://nexolatam.org/docs"
  }
}

Respuestas de Error

Todos los errores devuelven un objeto JSON estructurado con el mismo envelope:

{
  "error": {
    "code": "NOT_FOUND",          // Código de error legible por máquina
    "message": "Post no encontrado",  // Descripción en español
    "hint": "Verifica el slug y consulta /api/blog.", // Sugerencia de acción
    "documentation": "https://nexolatam.org/docs"
  }
}

Blog

curl "https://nexolatam.org/api/blog?page=1&limit=5&category=liderazgo"

curl "https://nexolatam.org/api/blog/nexo-transforma-jovenes"

# Respuesta 404 (structured)
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Post no encontrado",
    "hint": "Verifica el slug y consulta /api/blog para ver todos los recursos disponibles.",
    "documentation": "https://nexolatam.org/docs"
  }
}

Newsletter

curl -X POST "https://nexolatam.org/api/subscribe" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "María",
    "lastName": "García",
    "email": "[email protected]",
    "country": "México",
    "source": "newsletter_home"
  }'

# Respuesta 200
{ "success": true, "message": "¡Gracias por suscribirte! Pronto recibirás nuestros recursos." }

# Respuesta 400 (campos faltantes)
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Nombre y email son requeridos",
    "hint": "Incluye los campos firstName y email en el cuerpo JSON de la solicitud.",
    "documentation": "https://nexolatam.org/docs"
  }
}

Contenido Markdown

Devuelve el contenido de las páginas en formato Markdown puro. Diseñado para agentes de IA y scrapers que prefieren texto plano sobre HTML. Páginas desconocidas devuelven HTTP 404 con un mapa del sitio en Markdown para facilitar la navegación del agente.

# Obtener sobre NEXO en Markdown
curl -H "Accept: text/markdown" "https://nexolatam.org/api/markdown/about"

# Responde con Content-Type: text/markdown; charset=utf-8
# y Vary: Accept, Accept-Encoding

Health Checks

curl "https://nexolatam.org/api/health/simple"
# { "status": "ok", "timestamp": "2026-09-10T00:00:00.000Z" }

CLI Oficial

@nexolatam/cli es una herramienta de línea de comandos oficial (Node.js 18+, sin dependencias) para consumir la API desde la terminal o scripts de automatización.

# Instalación global
npm install -g @nexolatam/cli

# O sin instalar, con npx
npx @nexolatam/cli health

# Comandos disponibles
nexo health                 # Estado del servicio
nexo version                # Versión de la API y política de deprecación
nexo openapi                # Descargar el spec OpenAPI
nexo blog:list --limit 5    # Listar posts publicados
nexo blog:get <slug>        # Obtener un post por slug
nexo subscribe --email [email protected] --firstName Ana

# Opciones globales
--base <url>   # Base URL (default https://nexolatam.org/api/v1)
--json         # Salida JSON cruda
--help         # Ayuda

Recursos para Agentes