/ 01

What Jev Returns

Jev evaluates a state against typed questions and returns structured decisions instead of prose. TypeSafe’s direct API returns model, answers and usage. Our live playground uses OpenRouter’s Decisions API, which preserves the typed answers but may add fields such as id, provider and usage.cost. The example below shows the direct TypeSafe shape.

/ 02

Full Response Example

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice", "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
      "confidence": 0.81
    },
    "is_urgent": { "type": "noul", "noul": 0.95 }
  },
  "usage": { "input_tokens": 318, "output_tokens": 34 }
}

The fields follow the official API reference. These sample values are illustrative, not a live run.

/ 03

Field Reference

FieldTypeMeaning
modelstringThe actual version that evaluated the request.
answersmapOne answer under each question id you supplied.
usageobjectInput and output token counts.

/ 04

Answer Shapes by Question Type

Noul

{ "type": "noul", "noul": 0.95 }

The number is the probability of yes. Noul has no confidence field and no probabilities map.

Choice

{ "type": "choice", "choice": "billing", "probabilities": { "billing": 0.88, "technical": 0.12 }, "confidence": 0.81 }

Choice is the highest-probability option. The distribution covers the defined options and sums to 1; confidence is derived from it.

Score

{ "type": "score", "score": 1.05, "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" }, "probabilities": { "0": 0, "1": 0.95, "2": 0.05 }, "confidence": 0.92 }

Score is probability-weighted and can fall between levels. Legend maps the string level keys back to descriptions.

/ 05

Request Shape in 10 Lines

{"state":"Help! My payout failed.","model":"jev-latest","questions":{"is_urgent":{"type":"noul","instructions":"Does this convey urgency?"}}}

The response returns under answers.is_urgent. See noul questions for criteria and thresholds.

/ 06

Errors You’ll Actually Hit

StatusMeaning / action
401Missing or invalid API key. Check Authorization.
422Invalid request body. Inspect the offending field and fix it before retrying.
429Rate limit exceeded. Retry with exponential backoff.
529TypeSafe temporarily overloaded. Retry with exponential backoff.

The official SDKs handle 429 and 529 retries by default.

/ 07

Common Parsing Pitfalls

  1. answers uses your question ids, not fixed names.
  2. Choice probability keys match your options; do not rely on key order.
  3. Noul is a probability, not a boolean; avoid if (noul).
  4. Do not read confidence from Noul.
  5. Score may be fractional, such as 1.05.
  6. Fix a 422 request before retrying.

/ 08

Try It in the Playground

Inspect these answer shapes in the Jev playground. For direct integration, read the Jev API guide. See Jev as a classifier for a triage example using all three answer types.

/ FAQ

Frequently asked questions

Is Jev’s output always JSON?

The HTTP API returns structured JSON with model, answers and usage.

Does a noul answer include a confidence score?

No. A Noul answer contains type and a noul probability only.

How do I know which answer belongs to which question?

Each answer uses the question id supplied in the request.

Why is the returned model name different from what I sent?

An alias such as jev-latest resolves to a versioned model such as jev-1.13.0.

What’s the difference between probabilities and confidence?

Probabilities form a distribution; Choice and Score confidence summarizes certainty derived from that distribution.

Do failed requests count toward usage?

The public API reference does not specify billing for failed requests. Check your console or ask TypeSafe.