Documentation de l’API Jev

Vue d’ensemble

Jev évalue un state — un ticket de support, un journal de chat, un appel d’outil, n’importe quel texte ou JSON — contre un ensemble de questions typées et renvoie des réponses structurées sur lesquelles votre code peut brancher. Il ne génère pas de texte.

Une requête peut poser jusqu’à 8 questions ; elles sont évaluées ensemble et partagent le coût d’entrée du state. Le corps de requête a la même forme que celle acceptée par l’API SystemOne de TypeSafe — pour migrer une intégration existante, changez l’URL de base et la clé Bearer.

• POST https://jevmodel.org/v1/systemone — l’unique endpoint de décision.
• CORS est ouvert (access-control-allow-origin: *), l’endpoint répond depuis n’importe quelle origine. Gardez quand même votre clé côté serveur.
• Le playground envoie exactement la même requête via votre session navigateur — ce que vous y prévisualisez est ce que vous envoyez.

Authentification

Chaque appel API nécessite une clé jevmodel.org. Créez-en une dans Dashboard → API keys ; les clés commencent par sk- et ne s’affichent qu’une fois à la création. Stockez-la en variable d’environnement, par exemple JEVMODEL_API_KEY.

Authorization: Bearer $JEVMODEL_API_KEY

Les clés appartiennent au solde de tokens de votre compte et peuvent être révoquées depuis le dashboard. N’exposez jamais une clé dans du code côté client et ne la commitez pas dans un dépôt — en cas de fuite, révoquez-la et générez-en une nouvelle. Le playground s’authentifie avec votre session navigateur connectée et n’a pas besoin de clé.

Endpoint HTTP

Envoyez un corps JSON à l’endpoint d’évaluation avec l’authentification 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 est optionnel (jusqu’à 100 caractères). Les nouvelles tentatives avec la même clé réutilisent l’enregistrement de facturation d’origine — une requête réessayée ne peut pas être facturée deux fois pour la même entrée.

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"]
      }
    }
  }'

Corps de requête

Un objet JSON avec un state et une map de questions :

{
  "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"]
    }
  }
}

Chaque question nécessite un type et des instructions (jusqu’à 1 800 caractères) indiquant au modèle quoi décider. criteria fournit l’espace de réponse — obligatoire pour choice et score, optionnel pour noul.

Types de questions

Choisissez la forme de réponse que votre application peut exploiter.

Les criteria sérialisés sont limités à 2 000 caractères par question. Les échecs de validation renvoient 422 avant toute réservation de tokens — les requêtes invalides ne sont jamais facturées.

JSON de réponse

Une réponse 200 est la sortie du modèle elle-même : le modèle résolu, une réponse par nom de question et l’usage. Les valeurs ci-dessous sont illustratives — exécutez la requête pour une sortie réelle.

{
  "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 est indexé par vos noms de question — vous lisez les champs que vous avez demandés.
• Pour choice, branchez sur le libellé sélectionné et inspectez probabilities quand vous avez besoin de la distribution complète.
• noul est P(oui) — votre code fixe le seuil d’action.
• usage.input_tokens est ce que cet appel a réellement facturé ; les tokens de sortie sont gratuits.

Facturation

L’API ne facture que les tokens d’entrée — la sortie est gratuite. Chaque appel réserve d’abord une estimation, puis se règle sur les usage.input_tokens réels rapportés par le modèle. Si Jev échoue en amont, la réservation est intégralement remboursée automatiquement.

• Connectez-vous une fois et recevez 100 000 tokens d’entrée gratuits ; les packs payants démarrent à 9,90 $ et n’expirent jamais.
• Un solde insuffisant renvoie 402 avant l’appel à Jev.
• X-Tokens-Remaining sur chaque réponse 200 est votre solde après règlement.
• Estimez vous-même : ceil(JSON.stringify({state, questions}).length / 4).

Modèles et limites

jev-latest est le modèle par défaut et celui actuellement servi — le champ model est optionnel. Les variantes Laya affichées dans le playground sont à venir et pas encore exposées via cet endpoint.

Ces chiffres décrivent le validateur de l’API ; le modèle en amont peut avoir ses propres limites de contexte.

Erreurs et nouvelles tentatives

Les erreurs renvoient une enveloppe JSON avec un type lisible par machine et un message humain :

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

Réessayez 429 et 502 avec un backoff exponentiel — la fenêtre de débit est par minute, de courtes pauses suffisent en général. Envoyez un Idempotency-Key lors des nouvelles tentatives pour qu’une requête répétée se règle sur le même enregistrement de facturation au lieu d’être facturée deux fois.

Serveur MCP pour agents

jevmodel.org fait aussi tourner un serveur MCP distant en Streamable HTTP sur https://jevmodel.org/mcp. Il expose quatre outils — jev_decide (le contrat complet state-plus-questions), jev_noul, jev_choice et jev_score — pour que des agents de code comme Claude Code, Cursor ou Cline appellent Jev sans écrire de HTTP.

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

• Même clé Authorization: Bearer sk-… et même solde de tokens que cette API — tools/call ne facture que les tokens d’entrée.
• initialize, ping et tools/list sont non authentifiés ; seul tools/call utilise votre clé.
• GET /mcp renvoie une carte JSON de découverte pour agents et humains.

Les commandes d’installation pour Claude Code et Cursor, ainsi que la skill d’agent assortie (manuel de jugement), sont sur la page outils agent.

Guide des outils agent →

Du playground à l’API

Construisez d’abord le scénario dans le playground — l’aperçu de requête montre le corps JSON exact que votre application doit envoyer, et Copy API example vous donne le cURL correspondant. Quand les réponses conviennent, créez une clé dans le dashboard et remplacez la session navigateur par l’authentification Bearer.

Pour aller plus loin : Comment utiliser Jev parcourt un premier appel de bout en bout, et Exemples de l’API Jev contient des patterns de production pour chaque type de question.