MuntrumeAI DocsReferencia API REST & SSE
MUNTRUME AI DOCS · OPEN SOURCE (MIT)

Referencia API REST & SSE

Base URL de producción: https://ai.muntru.me (alias equivalente: https://api.muntru.me). Todas las rutas de inferencia, publicación y administración exigen cabecera Authorization: Bearer <JWT> emitida para una cuenta de miembro del equipo.

curl -N https://ai.muntru.me/api/ai \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TEAM_JWT_TOKEN>" \
  -d '{
    "model": "pro",
    "skill": "engineer",
    "stream": true,
    "messages": [
      { "role": "user", "content": "/setup BMW M4 GT3 en Spa con 38C de pista: subviraje en Pouhon" }
    ]
  }'

Parámetros de POST /api/ai y códigos HTTP

El esquema formal en formato OpenAPI 3.1 está publicado en /ai-openapi.json.

Campo JSONTipoDescripción
messages REQUERIDOArray<Message>Historial de conversación con role (user | assistant) y content (texto o bloques multimodales con imagen base64).
model"lite" | "pro" | "ultra"Perfil de motor Muntrume 1.0. Por defecto pro.
skillstringSkill opcional (engineer, strategy, artifacts, telemetry, code, press).
streambooleanSi es true (recomendado), responde en text/event-stream token a token.

Códigos de respuesta HTTP

EstadoSignificadoAcción recomendada
200 OKInferencia completada o stream SSE abierto.Procesar chunks data: {...} hasta done: true.
400 Bad RequestPayload JSON inválido o lista messages vacía.Validar estructura del cuerpo enviado.
401 UnauthorizedToken ausente, expirado o cuenta no autorizada.Iniciar sesión en /login/ o mediante Passkey.
429 Too Many RequestsLímite de ráfaga superado para el piloto actual.Esperar unos segundos y reintentar con backoff.
502 / 503Todos los proveedores de la cascada temporalmente saturados.Cambiar temporalmente a perfil lite o reintentar.

Endpoints de Artifacts Studio

Método y RutaAuthFunción
POST /api/ai/artifactsEquipo (JWT)Publica un artefacto (html, svg, mermaid, slides, csv, doc, code) en D1 y devuelve su slug y URL pública.
GET /a/:slugPúblicoRenderiza la página pública del artefacto con marco editorial y Open Graph.
GET /a/:slug/rawPúblicoDevuelve el contenido crudo del artefacto con su tipo MIME nativo.
GET /u/:handlePúblicoMuestra el catálogo público de artefactos publicados por un autor.
DELETE /api/ai/artifacts/:slugAutor / AdminElimina permanentemente el artefacto de D1.

Endpoints de Passkeys WebAuthn y MFA

Método y RutaFunción
POST /api/auth/passkey/register/optionsGenera reto WebAuthn para registrar una nueva Passkey en la cuenta autenticada.
POST /api/auth/passkey/register/verifyVerifica la atestación y almacena la clave pública COSE en D1.
POST /api/auth/passkey/login/optionsInicia sesión sin contraseña generando reto para credenciales registradas.
POST /api/auth/passkey/login/verifyVerifica firma ECDSA P-256 y devuelve JWT de equipo.
POST /api/auth/mfa/totp/setup & /verifyGenera secreto Base32 + URI otpauth:// y activa TOTP RFC 6238 + 8 códigos de recuperación.
POST /api/auth/mfa/otp/send & /verifyEnvía y valida códigos OTP de un solo uso por ntfy.sh, Discord DM, Android SMS Gateway o WhatsApp Evolution/WAHA.

Garage Vault y Race Control Season

Método y RutaAuthFunción
GET /api/download?file=...Equipo (JWT)Descarga autenticada de setups .sto desde el Vault hacia el navegador o MMT Sync.
POST /api/admin/season/generateAdminImporta calendario provisional/oficial de iRacing en Race Control y genera la estructura de setups de la nueva temporada para Garage y MMT Sync.