How to Use Jev: A Tested Step-by-Step Guide With Working Code (2026)

A practical guide to TypeSafe Jev where every request was run against the live API. Setup, the three question types, eight recipes with curl, Python and JavaScript, decision-policy tables, cost math, error handling, a production checklist and when not to use it.

Book a Free Strategy Call

Skip the read: talk to the ManasFlow team in 30 min.

Free strategy call. We map your AI engineering team, you keep the notes.

Jev is TypeSafe's System One model. You send it some text and a set of typed questions, and it returns probabilities and a confidence value instead of a paragraph, so your code can branch on the result. The fastest path is four steps. Create a key in the TypeSafe console, POST one request to https://api.typesafe.ai/v1/systemone, read answers.<name>, and gate your action on confidence.

We checked every technical claim below against the TypeSafe docs on September 20, 2026, and ran every request in this guide against the live API. The responses you see are the ones we got. Where the docs did not say something, we left it out. Our benchmark numbers come from our own test of 791 labeled decisions, run on September 19, 2026.

Setup in 5 minutes

• Create an API key in the TypeSafe console (console.typesafe.ai/keys) and export it as TYPESAFE_API_KEY. TypeSafe's quick start also offers an SDK, an agent skill for coding agents, and a browser Playground if you want to try a question before writing code.
• Use the model id jev-latest. On October 23, 2026, TypeSafe's models page pointed jev-latest to jev-1.13.0 and jev-preview to jev-1.14.0 (released October 14, 2026). Pin a versioned id if you tune confidence thresholds, because aliases move.
• Send JSON to POST https://api.typesafe.ai/v1/systemone with an Authorization: Bearer header.

You do not need an SDK. Every example in this guide works with plain HTTP, and each recipe shows curl, Python and JavaScript. The Python and JavaScript blocks call one small helper, so paste it once.

TypeSafe also ships official SDKs. Python is pip install typesafe-sdk and JavaScript is npm install @typesafe-ai/sdk. Both read TYPESAFE_API_KEY and retry transient errors for you. We use raw HTTP here so every example shows exactly what goes over the wire.

Related Reads

Your first call

The request has three fields. state is the content to judge. model picks the model. questions is a map of names you choose, each with a type. This one asks three different questions about one support ticket.

Real response:

Read it like this. Each key under answers matches a question name. The choice answer has choice, a probabilities map over your options and a confidence. The score answer has score, a legend and probabilities per level. The noul answer has one number between 0 and 1. usage reports input and output tokens, and the docs say output tokens are free.

Python and JavaScript for the same call:

The aliases point at a specific version, and a response reports which one it used. When an alias moves to a new model, a threshold you tuned last month may not describe today's answers. This request sends the version id instead of the alias.

Real response:

Log the model field from every response. It tells you which version produced each decision.

Free weekly brief

Steal our production automations

The exact n8n flows, Claude Code setups, and prompts we ship for clients, broken down step by step. No spam, unsubscribe anytime.

The three question types

Every question has a type and instructions. What changes is the shape of the answer and what your code does with it.

Choice

A choice question returns one of your options and the full distribution behind it. The answer is always one of the options you supplied.

Real response:

Score

A score question returns a position on your rubric. The score is probability-weighted, so it can fall between two levels. TypeSafe's own weakness notes warn that score levels are weak at numeric calibration, so treat the value as an ordering, not as a measurement.

Real response:

Noul

A noul answers a yes/no claim with a probability. It has no confidence field. To gate on it, use the distance from 0.5 or fixed cutoffs, and set them from your own labeled data.

Real response:

Designing state and questions

State is the content you want judged. It can be a string, a JSON object or an array, and it must be text. The docs say images, audio and video are not supported. Use an object when the content has parts, because named fields keep their relationships clear. Keep facts in the state and judgments in the questions.

Three habits matter most, and each maps to a documented weakness of Jev 1.13.

Here is the same message asked two ways. The first question stacks a double negative and gives no criteria.

Real response:

The second asks one plain claim and defines both outcomes.

Real response:

Compare the two probabilities. For the same mixed message, the negated question returned 0.54 and the plain question with named outcomes returned 0.41, and the plain version cost 30 more input tokens (332 against 302). Neither number is the right answer to a message that says "I would rather not cancel, but I cannot afford this". The message is genuinely mixed, so the useful behavior is a probability that reflects that, and a question you can explain to a teammate. When a question has several parts, the docs suggest putting them in JSON with labeled keys, and referring to state fields with backticks, as in "Does passage answer query?". Recipe 5 does exactly that.

Batching questions in one request

Put every question you need in one questions map. TypeSafe's parallel-questions cookbook found that batching 13 questions into one call gave the same answers as asking them one at a time according to TypeSafe (some nouls varied between repeated runs), cost 12.2 times less because the document tokens are billed once, and finished in 0.27 seconds against 2.71 seconds sequentially. The fan-out pattern page adds that questions run in parallel, so extra questions usually have little effect on response time.

Real response:

Look at usage.input_tokens in that response. The article is counted once, not six times.

Recipe 1: support ticket routing

The problem is a shared inbox where a person reads every ticket just to decide who should handle it. One request can return the team, the priority and whether a human should read it first.

Real response:

Decision policy for the team choice, using the example tiers in the TypeSafe confidence docs.

Log the ticket id, the model version, the chosen team, the full probabilities, the priority score and which queue the ticket landed in. When a team bounces a ticket, log the corrected team. That correction data is what lets you move the thresholds.

Recipe 2: confidence-gated action

The problem is an assistant that can do things, and some things are safer than others. Checking an order is harmless. Canceling a subscription is not. The TypeSafe docs recommend higher thresholds for higher consequences, and this recipe sends two messages through the same question.

A clear request first.

Real response:

Now an ambiguous one with the same question.

Real response:

The 0.6 and 0.85 levels come from TypeSafe's banking example. The 0.9 level is ours, and here is why. In our benchmark on 160 confusable card intents, Jev answered 70.0 percent of items at confidence 0.90 or higher and was right 95.5 percent of the time on those. Still, 5 of the 112 items at 0.9 or higher were wrong, and all five were the same confusion, direct debits read as card payments. High confidence lowers the error rate. It does not remove it, so destructive actions need a confirmation step or an undo path as well.

Log every decision with its confidence, the action taken and the user's reaction to a confirmation prompt. If people confirm nearly every prompt in a band, that band can move to automatic.

Recipe 3: cascade to a larger model

The problem is cost and speed on the easy majority, with accuracy needed on the hard minority. Jev answers first. If its confidence is below a cutoff, a larger model answers instead. TypeSafe's cascade cookbook uses the same idea for extraction, with a Jev verifier deciding when to escalate a cheap model's output.

The message below is from a pair Jev often confuses in our data. The customer describes a direct debit, and the wrong answer is a card payment.

Real response:

call_bigger_model and callBiggerModel are yours to write. Send the fallback the same options and force it to answer with one of them. Our measured cascade, with GPT-5.6 Terra as the fallback and a 0.80 cutoff, looked like this.

Mean latency on the 8-way task dropped from 1.58 seconds for the fallback alone to 0.70 seconds for the cascade. Raising the cutoff to 0.90 sent 30.0 percent to the fallback and cost 38.1 percent of fallback-only, with the same 90.0 percent accuracy. Pick the cutoff by plotting your own data, not ours.

Log which side answered, Jev's confidence, both answers when the fallback ran, and the share routed to the fallback per day. A rising share means your traffic has drifted.

Recipe 4: input guardrail

The problem is user text that tries to hijack your assistant. A noul can screen each message before it reaches the main model. TypeSafe's guardrails cookbook uses the same approach with several noul questions and a severity score in one request. We use one noul and show two inputs.

Real response:

Now an ordinary message.

Real response:

The thresholds come from our injection test, 400 items from the deepset prompt-injections set, of which 170 were injections. These numbers are in-sample, so treat them as a starting point.

At 0.5, Jev caught 118 of 170 injections and flagged no benign text. Lowering the cutoff catches more and costs more false alarms. A guard that misses 31 percent of attacks at a 0.5 cutoff is a filter, not a wall, so keep least-privilege permissions behind it. The docs also warn that content written to steer the model can move its answer.

Log the message hash, the probability and the verdict. Send every message in the review band to a person, and add the confirmed attacks to a regression set.

Recipe 5: reranking retrieved passages

The problem is a search step that returns ten passages where only two answer the question. Ask one noul per query and passage pair, then sort by the probability. TypeSafe's reranking cookbook did this on 40 legal queries with 30 candidates each. It moved the correct passage into the top 10 for 62 percent of queries, up from 38 percent, and the 1,200 calls cost $0.0645.

Here is a relevant passage.

Real response:

And a passage on the same topic that does not answer the question.

Real response:

The cutoffs are a starting guess. Tune them on your own queries. Log the query, each passage id with its probability and whether the final answer cited it. Each call sends the query and one passage, so cost scales with passages retrieved.

Recipe 6: scoring and prioritizing leads

The problem is an inbox of demo requests and a sales team that answers them in arrival order. Break the judgment into small scores, then combine them in code with weights you control. That is TypeSafe's composite scoring pattern, and it lets you change the weights without rewriting prompts.

Real response:

Each score is divided by its highest level so it lands between 0 and 1. The weights above are an example, not a recommendation. Set them from your closed-won history.

Log each sub-score next to the composite and, months later, the deal outcome. That gives you the data to fit real weights.

Recipe 7: picking a value from candidates without generating text

The problem is turning free text into one of a fixed set of values, like a SKU, without letting a model invent one. A choice question can only return one of your options. Put the SKU in the option key and its description in the value.

Real response:

These cutoffs are our starting guesses, not TypeSafe's. Set yours from your own labeled examples.

Sort probabilities to get the runner-up for the middle row. Because the schema limits the answer to your options, the output can never be an unlisted SKU. It can still be the wrong listed one, which is why the confidence gate exists. Log the chosen SKU, the runner-up and whether the customer changed it.

Recipe 8: speculative fan-out

The problem is a decision tree where the second question depends on the first answer. Instead of two round trips, ask every question you might need in one call and read only the ones that matter. The cost of an unused question is a few input tokens, and the docs say parallel questions usually barely affect latency.

Real response:

Log every answer, including the ones you did not use. Unused answers are free training data for later rules.

Cost math

The docs price Jev at $0.042 per million input tokens, and output tokens are free. So a request costs its input tokens times 0.042 divided by a million. The state, every question and every criteria string count as input.

A worked estimate for the ticket-routing setup. The docs' three-question example reported 392 input tokens. Check your own usage.input_tokens, because it depends on your text and questions.

Our benchmark measured $0.0151 per 1,000 decisions on the 8-way intent task, where prompts averaged about 360 input tokens. That is $0.76 for the same 50,000. The 77-way task, with 952 tokens per prompt, cost $0.0400 per 1,000.

For comparison, the same 8-way messages cost $0.609 per 1,000 on GPT-5.6 Terra, $0.356 on Claude Haiku 4.5, $0.087 on Gemini 3.5 Flash-Lite and $0.070 on GPT-5.4 nano, as billed through OpenRouter. With a Terra fallback at a 0.80 cutoff, 50,000 tickets cost about $7.80 instead of $30.45. Jev's median latency across our 791 calls was 0.33 seconds, with a 95th percentile of 0.44 seconds. The LLMs ranged from 0.67 to 1.17 seconds at the median. We ran all of it through one client on one laptop with four parallel requests, so read the latency as relative, not as an SLA.

Using Jev in a product

Not sure where Jev fits in your product?

Show us the decision steps in your workflow and we will tell you which ones are worth moving off a large model. Free 30-minute call.

Limits

The docs do not state a maximum number of questions per request, a minimum number of choice options or a state size cap other than the context limits. We do not guess at them.

Error handling

The API reference lists four error statuses, 401, 422, 429 and 529. We reproduced 401 and 422, and we also got a 400 for an unknown question type, which the reference does not list. The response bodies are the real ones. We did not trigger 429 or 529 on purpose.

A request with an invalid key.

An empty questions map.

Real response:

An unknown question type.

Real response:

A score with one level. This one did not fail: the API accepted it and answered with a score of 0 and a confidence of 1.0, so a one-level scale tells you nothing. Validate your own scales before you send them.

Real response:

The official SDKs handle retries for you. The Python defaults are two retries on 408, 429 and any 5xx, a 0.5 second initial delay that doubles to a 5 second cap with jitter, respect for Retry-After, and a 30 second total budget. In the JavaScript SDK, errors expose status, body, headers, retryAfterMs and a requestId read from the x-typesafe-request-id header. Log the request id, because it is what support will ask for.

If you use raw HTTP, add the same behavior.

Troubleshooting

Production checklist

• Pin the model version in production and re-run your labeled set before changing it.
• Keep a labeled set of at least a few hundred real examples and set thresholds from it, per action and not globally.
• Send only the state fields the decision needs.
• Batch every question for one piece of state into one request.
• Put a human or an undo path behind any action with real cost.
• Log the model, request id, state hash, every probability, the decision taken and the later outcome.
• Alert on the share of decisions in the middle confidence band, since a rise means your inputs changed.
• Retry 408, 429 and 5xx with backoff, and never retry 400, 401 or 422.
• Keep a regression set of past failures and run it on each version change.
• Do not rely on Jev alone against adversarial input. Keep permissions narrow behind it.

When not to use Jev

Skip it when the output has to be text. It returns probabilities and labels, and the docs say generating text with it will not work well and will be slow. Skip it for counting, date arithmetic and exact numbers, all listed as weak in the model notes. Skip it for questions that need several reasoning hops or double negatives.

Do not use it as your only defense against a hostile user. In our test it caught 69 percent of injections at 0.5 with no false alarms, which is useful and not sufficient.

Think twice when a frontier model's extra accuracy matters more than cost. GPT-5.6 Terra beat Jev by about 5 points on 77-way intent routing, and a paired test says the gap is real (p = 0.029). Against the small models we tested, it was level on accuracy and far cheaper and faster. The confidence score is what makes a cascade work.

Finally, skip it for images, audio and video. Input is text only.

Keep going

• What it costs to run: Jev pricing and cost per decision.
• Measured results behind the numbers here: our independent Jev vs GPT and Claude benchmark.
• Video walkthroughs: the best Jev videos and tutorials, embedded and ranked.
• Jev use cases and the index of 1,300+ Jev builds.

FAQ

What is Jev?

Jev is TypeSafe's flagship System One model. It takes state and typed questions and returns probabilities and a confidence value in a fixed schema, instead of generated text.

How much does Jev cost?

The docs list $0.042 per million input tokens, with output tokens free. Our measured cost was $0.0151 per 1,000 decisions on 8-way intent routing.

Do I need the SDK?

No. The API is one POST endpoint, and every example here uses plain HTTP. The Python SDK is typesafe-sdk and the JavaScript SDK is @typesafe-ai/sdk, and both add retries.

Which model id should I send?

Send jev-latest while you experiment. For production, send a version id such as jev-1.13.0 so results do not shift under you, and log the model field from each response.

What is the difference between probabilities and confidence?

Probabilities are the full distribution over your options or levels. Confidence is a single number derived from that distribution. For three options the docs give the formula (3 times the largest probability, minus 1) divided by 2, so an even split scores 0 and a clear winner scores 1.

Does a noul have a confidence?

No. A noul returns one probability between 0 and 1. Gate on cutoffs you set from labeled data.

What confidence threshold should I use?

The docs suggest acting automatically above 0.9, confirming in the middle and not acting below 0.5, with higher thresholds for higher stakes. Ours: at 0.90 or more, Jev was right 95.5 percent of the time on 8-way intent, but not every time.

How many options can a choice have?

Up to 255. A score takes 2 to 10 levels.

Can I ask many questions at once?

Yes, and you should. TypeSafe's cookbook measured identical answers, 12.2 times lower cost and a 10 times speedup for 13 questions in one call. The docs do not state a hard cap on question count.

How fast is it?

In our test, median latency was 0.33 seconds and 95th percentile was 0.44 seconds across 791 calls through OpenRouter. The slowest single call took 1.42 seconds.

Is Jev more accurate than GPT or Claude?

Not in our test. It was level with the small models and behind GPT-5.6 Terra on intent routing. It was much cheaper and faster, and its confidence score supported a cascade that matched Terra's accuracy at about 26 to 28 percent of the cost.

Can Jev read images or PDFs?

Not directly. Input is text only. Extract the text first, then pass it as state.

What are the rate limits?

The Models page lists 250,000 tokens per second and 1,200 requests per minute. Exceeding either returns 429.

Can it write text or code?

No. The docs say it is not trained to generate text. Pair it with a normal LLM when you need prose, and use Jev to decide what to do with it.

Where to go next

ManasFlow has not used Jev on client projects. Our index of Jev builds and tests shows what others have built, including tests where it fell short. For ideas on what to build first, read what you can build with Jev.

Continue Reading

AI Facilities Management Tools: What to Automate, Where Judgment Leads (2026)

What AI facilities management tools automate well, how this differs from property management, and where facilities professional judgment still leads.

AI Vendor Management: What to Automate, Where Judgment Leads (2026)

Where AI genuinely helps in vendor management (contract tracking, risk monitoring, SLA tracking), and where negotiation and relationship judgment still lead.

AI Load Testing Tools: What to Automate, Where Engineering Judgment Leads (2026)

What AI load testing tools do well, how this differs from functional CI/CD testing, and where engineering judgment on results still leads.

Book a Free Strategy Call

Building this in production?