Documentazione API Jev

Panoramica

Jev valuta uno state — un ticket di supporto, un log di chat, una chiamata a uno strumento, qualsiasi testo o JSON — rispetto a un insieme di domande tipizzate e restituisce risposte strutturate su cui il tuo codice può diramare. Non genera testo.

Una richiesta può porre fino a 8 domande; vengono valutate insieme e condividono il costo di input dello state. Il corpo della richiesta ha la stessa forma accettata dall’API SystemOne di TypeSafe — per migrare un’integrazione funzionante, scambia l’URL base e la chiave Bearer.

• POST https://jevmodel.org/v1/systemone — l’unico endpoint di decisione.
• CORS è aperto (access-control-allow-origin: *), l’endpoint risponde da qualsiasi origine. Tieni comunque la chiave su un server.
• Il playground invia esattamente la stessa forma di richiesta attraverso la tua sessione di browser — ciò che vedi in anteprima è ciò che invii.

Autenticazione

Ogni chiamata API richiede una chiave jevmodel.org. Creane una in Dashboard → API keys; le chiavi iniziano con sk- e vengono mostrate una sola volta alla creazione. Conservala come variabile d’ambiente, ad esempio JEVMODEL_API_KEY.

Authorization: Bearer $JEVMODEL_API_KEY

Le chiavi appartengono al saldo di token del tuo account e possono essere revocate dalla dashboard. Non esporre mai una chiave nel codice lato client né committarla in un repository — se trapela, revocala e generane una nuova. Il playground si autentica con la tua sessione di browser connessa e non ha bisogno di chiave.

Endpoint HTTP

Invia un corpo JSON all’endpoint di valutazione con autenticazione 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 è opzionale (fino a 100 caratteri). I nuovi tentativi con la stessa chiave riutilizzano il record di fatturazione originale, quindi una richiesta ripetuta non viene addebitata due volte per lo stesso input.

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

Corpo della richiesta

Un oggetto JSON con uno state e una mappa di domande:

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

Ogni domanda richiede un type e instructions (fino a 1.800 caratteri) che dicono al modello cosa decidere. criteria fornisce lo spazio delle risposte — obbligatorio per choice e score, opzionale per noul.

Tipi di domanda

Scegli la forma di risposta che la tua applicazione può utilizzare.

I criteria serializzati sono limitati a 2.000 caratteri per domanda. I fallimenti di validazione restituiscono 422 prima che vengano riservati token — le richieste errate non vengono mai addebitate.

JSON di risposta

Una risposta 200 è l’output del modello stesso: il modello risolto, una risposta per nome di domanda e l’uso. I valori qui sotto sono illustrativi — esegui la richiesta per un output reale.

{
  "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 è indicizzato dai tuoi nomi di domanda — leggi i campi che hai chiesto.
• Per choice, dirama sull’etichetta selezionata e ispeziona probabilities quando serve la distribuzione completa.
• noul è P(sì) — il tuo codice decide la soglia di azione.
• usage.input_tokens è ciò che questa chiamata ha effettivamente fatturato; i token di output sono gratuiti.

Fatturazione

L’API fattura solo i token di input — l’output è gratuito. Ogni chiamata riserva prima una stima, poi liquida sui usage.input_tokens effettivi riportati dal modello. Se Jev fallisce a monte, la riserva viene rimborsata automaticamente per intero.

• Accedi una volta e ricevi 100.000 token di input gratis; i pacchetti a pagamento partono da $9,90 e non scadono mai.
• Saldo insufficiente restituisce 402 prima di chiamare Jev.
• X-Tokens-Remaining su ogni risposta 200 è il tuo saldo dopo la liquidazione.
• Stimalo da solo: ceil(JSON.stringify({state, questions}).length / 4).

Modelli e limiti

jev-latest è il default e il modello attualmente servito — il campo model è opzionale. Le varianti Laya mostrate nel playground sono in arrivo e non ancora esposte tramite questo endpoint.

Queste cifre descrivono il validatore dell’API; il modello a monte può avere i propri limiti di contesto.

Errori e nuovi tentativi

Gli errori restituiscono un envelope JSON con un type leggibile dalla macchina e un message per l’uomo:

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

Riprova 429 e 502 con backoff esponenziale — la finestra di frequenza è al minuto, brevi pause di solito bastano. Invia un Idempotency-Key quando riprovi così una richiesta ripetuta liquida sullo stesso record di fatturazione invece di addebitare due volte.

Server MCP per agenti

jevmodel.org gestisce anche un server MCP remoto su Streamable HTTP all’indirizzo https://jevmodel.org/mcp. Espone quattro strumenti — jev_decide (il contratto completo state-più-questions), jev_noul, jev_choice e jev_score — così agenti di codice come Claude Code, Cursor o Cline possono chiamare Jev senza scrivere HTTP.

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

• Stessa chiave Authorization: Bearer sk-… e stesso saldo di token di questa API — tools/call fattura solo token di input.
• initialize, ping e tools/list non richiedono autenticazione; solo tools/call usa la tua chiave.
• GET /mcp restituisce una card JSON di discovery per agenti e umani.

I comandi di setup per Claude Code e Cursor, e la skill agente corrispondente (manuale di giudizio), sono sulla pagina strumenti per agenti.

Guida agli strumenti per agenti →

Dal playground all’API

Costruisci prima lo scenario nel playground — l’anteprima della richiesta mostra l’esatto corpo JSON che la tua applicazione deve inviare, e Copy API example ti dà il cURL corrispondente. Quando le risposte vanno bene, crea una chiave nella dashboard e sostituisci la sessione del browser con l’autenticazione Bearer.

Per approfondire: Come usare Jev percorre una prima chiamata dall’inizio alla fine, e Esempi API Jev ha pattern di produzione per ogni tipo di domanda.