Documentación de la API de Jev

Visión general

Jev evalúa un state — un ticket de soporte, un registro de chat, una llamada a herramienta, cualquier texto o JSON — contra un conjunto de preguntas tipadas y devuelve respuestas estructuradas sobre las que tu código puede ramificar. No genera texto.

Una petición puede formular hasta 8 preguntas; se evalúan juntas y comparten el coste de entrada del state. El cuerpo de la petición tiene la misma forma que acepta la API SystemOne de TypeSafe — para migrar una integración que funciona, cambia la URL base y la clave Bearer.

• POST https://jevmodel.org/v1/systemone — el único endpoint de decisiones.
• CORS está abierto (access-control-allow-origin: *), el endpoint responde desde cualquier origen. Mantén tu clave en un servidor de todos modos.
• El playground envía exactamente la misma petición a través de tu sesión de navegador — lo que previsualizas ahí es lo que envías.

Autenticación

Cada llamada a la API necesita una clave de jevmodel.org. Créala en Dashboard → API keys; las claves empiezan por sk- y se muestran una sola vez al crearlas. Guárdala como variable de entorno, por ejemplo JEVMODEL_API_KEY.

Authorization: Bearer $JEVMODEL_API_KEY

Las claves pertenecen al saldo de tokens de tu cuenta y pueden revocarse desde el dashboard. Nunca pongas una clave en código del lado del cliente ni la subas a un repositorio — si se filtra, revócala y genera otra. El playground se autentica con tu sesión de navegador y no necesita clave.

Endpoint HTTP

Envía un cuerpo JSON al endpoint de evaluación con autenticación Bearer:

POST /v1/systemone HTTP/1.1
Host: jevmodel.org
Authorization: Bearer $JEVMODEL_API_KEY
Content-Type: application/json
Idempotency-Key: ticket-4821-run-1   # optional

Idempotency-Key es opcional (hasta 100 caracteres). Los reintentos con la misma clave reutilizan el registro de facturación original, así que una petición reintentada no se cobra dos veces por la misma entrada.

curl -X POST https://jevmodel.org/v1/systemone \
  -H "Authorization: Bearer $JEVMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "The customer has been billed twice and wants a refund today.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Which queue should own this ticket?",
        "criteria": {
          "billing": "Payments, refunds, invoices",
          "technical": "Product errors and usage problems",
          "sales": "Pricing, upgrades, new business"
        }
      },
      "escalate": {
        "type": "noul",
        "instructions": "Does this need a human right now?"
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this for the customer?",
        "criteria": ["routine", "soon", "urgent", "critical"]
      }
    }
  }'

Cuerpo de la petición

Un objeto JSON con un state y un mapa de preguntas:

{
  "model": "jev-latest",
  "state": "The customer has been billed twice and wants a refund today.",
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which queue should own this ticket?",
      "criteria": {
        "billing": "Payments, refunds, invoices",
        "technical": "Product errors and usage problems",
        "sales": "Pricing, upgrades, new business"
      }
    },
    "escalate": {
      "type": "noul",
      "instructions": "Does this need a human right now?"
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this for the customer?",
      "criteria": ["routine", "soon", "urgent", "critical"]
    }
  }
}

Cada pregunta necesita un type e instructions (hasta 1.800 caracteres) indicando al modelo qué decidir. criteria aporta el espacio de respuesta — obligatorio para choice y score, opcional para noul.

Tipos de pregunta

Elige la forma de respuesta que tu aplicación pueda usar.

Los criteria serializados admiten hasta 2.000 caracteres por pregunta. Los fallos de validación devuelven 422 antes de reservar tokens — las peticiones incorrectas nunca se cobran.

JSON de respuesta

Una respuesta 200 es la salida del modelo en sí: el modelo resuelto, una respuesta por nombre de pregunta y el uso. Los valores de abajo son ilustrativos — ejecuta la petición para una salida real.

{
  "model": "jev-latest",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.93, "technical": 0.05, "sales": 0.02 },
      "confidence": 0.93
    },
    "escalate": {
      "type": "noul",
      "noul": 0.12
    },
    "urgency": {
      "type": "score",
      "score": 1.4,
      "confidence": 0.88
    }
  },
  "usage": { "input_tokens": 136, "output_tokens": 18 }
}

• answers va indexado por tus nombres de pregunta — lees los campos que pediste.
• En choice, ramifica por la etiqueta seleccionada e inspecciona probabilities cuando necesites la distribución completa.
• noul es P(sí) — tu código decide el umbral de acción.
• usage.input_tokens es lo que esta llamada cobró realmente; los tokens de salida son gratis.

Facturación

La API cobra solo tokens de entrada — la salida es gratis. Cada llamada reserva una estimación por adelantado y luego liquida con los usage.input_tokens reales que informa el modelo. Si Jev falla en el upstream, la reserva se reembolsa automáticamente por completo.

• Inicia sesión una vez y recibe 100.000 tokens de entrada gratis; los paquetes de pago empiezan en $9,90 y no caducan.
• Saldo insuficiente devuelve 402 antes de llamar a Jev.
• X-Tokens-Remaining en cada respuesta 200 es tu saldo tras la liquidación.
• Estímalo tú mismo: ceil(JSON.stringify({state, questions}).length / 4).

Modelos y límites

jev-latest es el modelo por defecto y el que se sirve actualmente — el campo model es opcional. Las variantes Laya del playground están anunciadas y aún no están expuestas en este endpoint.

Estas cifras describen el validador de la API; el modelo upstream puede tener sus propios límites de contexto.

Errores y reintentos

Los errores devuelven un sobre JSON con un type legible por máquina y un message para humanos:

{
  "error": {
    "type": "invalid_request_error",
    "message": "At most 8 questions per request."
  }
}

Reintenta 429 y 502 con backoff exponencial — la ventana de tasa es por minuto, así que pausas cortas suelen bastar. Envía un Idempotency-Key al reintentar para que una petición repetida liquide contra el mismo registro de facturación en vez de cobrar dos veces.

Servidor MCP para agentes

jevmodel.org también ejecuta un servidor MCP remoto sobre Streamable HTTP en https://jevmodel.org/mcp. Expone cuatro herramientas — jev_decide (el contrato completo de state más questions), jev_noul, jev_choice y jev_score — para que agentes de código como Claude Code, Cursor o Cline llamen a Jev sin escribir HTTP.

claude mcp add --transport http jev https://jevmodel.org/mcp \
  --header "Authorization: Bearer $JEVMODEL_API_KEY"

• Misma clave Authorization: Bearer sk-… y mismo saldo de tokens que esta API — tools/call cobra solo tokens de entrada.
• initialize, ping y tools/list no requieren autenticación; solo tools/call usa tu clave.
• GET /mcp devuelve una tarjeta JSON de descubrimiento para agentes y humanos.

Los comandos de configuración para Claude Code y Cursor, y la skill de agente a juego (manual de juicio), están en la página de herramientas de agente.

Guía de herramientas de agente →

Del playground a la API

Construye primero el escenario en el playground — la vista previa de la petición muestra el cuerpo JSON exacto que tu aplicación debe enviar, y Copy API example te da el cURL correspondiente. Cuando las respuestas convenzan, crea una clave en el dashboard y cambia la sesión del navegador por autenticación Bearer.

Más lectura: Cómo usar Jev recorre una primera llamada de principio a fin, y Ejemplos de la API de Jev tiene patrones de producción para cada tipo de pregunta.