Jev API-Dokumentation

Überblick

Jev evaluiert einen State — ein Support-Ticket, ein Chat-Log, einen Tool-Aufruf, beliebigen Text oder JSON — gegen typisierte Fragen und liefert strukturierte Antworten, auf die dein Code verzweigen kann. Es generiert keinen Text.

Ein Request kann bis zu 8 Fragen stellen; sie werden gemeinsam evaluiert und teilen die State-Inputkosten. Der Request Body hat dieselbe Form wie die TypeSafe-SystemOne-API — eine funktionierende Integration migrierst du durch Austausch von Basis-URL und Bearer-Key.

• POST https://jevmodel.org/v1/systemone — der einzige Entscheidungs-Endpoint.
• CORS ist offen (access-control-allow-origin: *), der Endpoint antwortet von jedem Origin. Halte deinen Key trotzdem auf dem Server.
• Der Playground sendet dieselbe Request-Form über deine Browser-Session — was du dort siehst, ist, was du sendest.

Authentifizierung

Jeder API-Aufruf braucht einen jevmodel.org API-Key. Erstelle einen unter Dashboard → API keys; Keys beginnen mit sk- und werden nur einmal bei der Erstellung gezeigt. Speichere ihn als Umgebungsvariable, z. B. JEVMODEL_API_KEY.

Authorization: Bearer $JEVMODEL_API_KEY

Keys gehören zum Token-Guthaben deines Kontos und können im Dashboard widerrufen werden. Gib einen Key nie in Client-Code aus und committe ihn nicht in ein Repository — bei einem Leck widerrufe ihn und stelle einen neuen aus. Der Playground authentifiziert über deine angemeldete Browser-Session und braucht keinen Key.

HTTP-Endpoint

Sende einen JSON-Body mit Bearer-Authentifizierung an den Evaluierungs-Endpoint:

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 ist optional (bis zu 100 Zeichen). Retries mit demselben Key nutzen den ursprünglichen Abrechnungsdatensatz — eine Wiederholung wird nicht doppelt für denselben Input berechnet.

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

Request Body

Ein JSON-Objekt mit einem State und einer Map von Fragen:

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

Jede Frage braucht ein type und instructions (bis zu 1.800 Zeichen), die dem Modell sagen, was es entscheiden soll. criteria liefert den Antwortraum — Pflicht für Choice und Score, optional für Noul.

Fragetypen

Wähle die Antwortform, mit der deine Anwendung arbeiten kann.

Serialisierte criteria sind auf 2.000 Zeichen pro Frage begrenzt. Validierungsfehler liefern 422, bevor Tokens reserviert werden — fehlerhafte Requests werden nie berechnet.

Response-JSON

Eine 200-Antwort ist die Modellausgabe selbst: das aufgelöste Modell, eine Antwort pro Fragename und Usage. Die Werte unten sind illustrativ — echte Ausgaben erhältst du im Request.

{
  "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 ist nach deinen Fragennamen gekeyed — du liest die Felder, die du gefragt hast.
• Bei choice verzweigst du auf dem gewählten Label und prüfst probabilities für die volle Verteilung.
• noul ist P(ja) — dein Code legt den Schwellenwert fest.
• usage.input_tokens ist, was dieser Aufruf tatsächlich berechnet hat; Output-Tokens sind kostenlos.

Abrechnung

Die API rechnet nur Input-Tokens ab — Output ist kostenlos. Jeder Aufruf reserviert zunächst eine Schätzung und rechnet dann mit den tatsächlichen usage.input_tokens ab, die das Modell meldet. Scheitert Jev upstream, wird die Reservierung automatisch vollständig erstattet.

• Einmal anmelden und 100.000 Input-Tokens gratis erhalten; bezahlte Packs ab $9,90, laufen nie ab.
• Zu wenig Guthaben liefert 402, bevor Jev aufgerufen wird.
• X-Tokens-Remaining auf jeder 200-Antwort ist dein Guthaben nach Verrechnung.
• Selbst schätzen: ceil(JSON.stringify({state, questions}).length / 4).

Modelle und Limits

jev-latest ist der Standard und das aktuell ausgelieferte Modell — das model-Feld ist optional. Die im Playground gezeigten Laya-Varianten sind geplant und über diesen Endpoint noch nicht verfügbar.

Diese Werte beschreiben den API-Validator; das Upstream-Modell kann eigene Kontextlimits haben.

Fehler und Retries

Fehler liefern einen JSON-Umschlag mit maschinenlesbarem type und menschlicher message:

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

429 und 502 mit exponentiellem Backoff wiederholen — das Rate-Fenster ist pro Minute, kurze Pausen reichen meist. Sende beim Retry einen Idempotency-Key, damit ein wiederholter Request auf denselben Abrechnungsdatensatz bucht statt doppelt zu berechnen.

MCP-Server für Agents

jevmodel.org betreibt außerdem einen Remote-MCP-Server über Streamable HTTP unter https://jevmodel.org/mcp. Er stellt vier Tools bereit — jev_decide (der volle State-plus-Questions-Vertrag), jev_noul, jev_choice und jev_score — damit Coding-Agents wie Claude Code, Cursor oder Cline Jev ohne HTTP-Code aufrufen können.

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

• Gleicher Authorization: Bearer sk-…-Key und dasselbe Token-Guthaben wie diese API — tools/call berechnet nur Input-Tokens.
• initialize, ping und tools/list sind unauthentifiziert; nur tools/call nutzt deinen Key.
• GET /mcp liefert eine JSON-Discovery-Karte für Agents und Menschen.

Setup-Befehle für Claude Code und Cursor sowie das passende Agent-Skill (Urteils-Playbook) findest du auf der Agent-Tools-Seite.

Agent-Tools-Anleitung →

Vom Playground zur API

Baue das Szenario zuerst im Playground — die Request-Vorschau zeigt den exakten JSON-Body, den deine Anwendung senden soll, und Copy API example liefert das passende cURL. Wenn die Antworten passen, erstelle einen Key im Dashboard und tausche die Browser-Session gegen Bearer-Authentifizierung.

Weiterlesen: Wie man Jev nutzt führt einen ersten Aufruf komplett durch, und Jev API-Beispiele enthält Produktionsmuster für jeden Fragetyp.