Skip to content
Made with Jev
Submit

How to use Jev

One POST request, two fields. You send the text and the questions you want answered about it; Jev sends back a typed answer, a probability for every option and a confidence score, in 70 to 500 milliseconds. Everything else on this page is what to do with that.

Updated · by

Pink poster with the TypeSafe AI mark: how to use Jev. Your first call in 5 minutes.

In short

  • Get an API key from TypeSafe, then send one request. No SDK required.
  • A call has a state (the text) and questions (choice, score or noul). All of them are answered in parallel.
  • Branch on how sure the answer is: confidence on a Choice or Score, the probability itself on a Noul. How to set the line: Jev confidence.
  • For a coding agent: install the skill with npx skills add typesafe-ai/skills, or run an MCP server.

Step 1: one request

This is a whole Jev call. The state is what you want judged. Each key under questions is one question: a choice picks one of your options, a noul returns the probability that a statement is true, and a score places the state on a scale you define.

Request · POST /v1/systemone
{
  "state": "Thanks for the refund. Still annoyed it took three emails.",
  "model": "jev-latest",
  "questions": {
    "sentiment": {
      "type": "choice",
      "instructions": "The overall sentiment of this message",
      "criteria": {
        "positive": "Satisfied or thankful overall",
        "mixed": "Both satisfied and unhappy",
        "negative": "Unhappy overall"
      }
    },
    "needs_follow_up": {
      "type": "noul",
      "instructions": "A human should reply to this message"
    }
  }
}
Response
{
  "model": "jev-1.13.0",
  "answers": {
    "sentiment": {
      "type": "choice",
      "choice": "mixed",
      "probabilities": { "mixed": 0.79, "negative": 0.2, "positive": 0.01 },
      "confidence": 0.69
    },
    "needs_follow_up": { "type": "noul", "noul": 0.83 }
  }
}

Illustrative values. The confidence of 0.69 follows TypeSafe's formula: (0.79 − 1/3) / (1 − 1/3) = 0.685, rounded to 0.69.

One thing catches everyone out: the question’s key, such as needs_follow_up, never reaches the model. Write the whole question in instructions, and write each criterion as the description of a bucket rather than as a label.

Step 2: branch on the confidence

The probabilities say which option Jev picked; confidence says how spread out they were. A Noul has no confidence field, because its probability already says it. Above your line, act; below it, hand the case on. Where to put the line, with TypeSafe's examples and builders' own: Jev confidence.

What the answer is for
const { sentiment, needs_follow_up } = await jev( // jev() returns response.answers
  state, questions);

// Act on the sure ones; send the rest somewhere that can think.
if (sentiment.confidence < 0.7) return escalate(message);

if (needs_follow_up.noul > 0.8) return queueForHuman(message, sentiment.choice);

return file(message, sentiment.choice);

Where the threshold goes is an empirical question about your data, not a default. TypeSafe’s confidence docs explain how the score is produced.

Step 3: ask more questions, not more calls

Jev answers every question in a call in parallel against the same state, so the marginal cost of another question is close to nothing. Rob Hallam asks 61 questions about one draft post in about a second for $0.0004. The instinct to send one question per request is the most expensive mistake you can make with this model.

When the option list is the problem rather than the question count, the skill-suggestion cookbook shows the standard workaround: score everything in one pass, then run a second call over the shortlist. TypeSafe’s own Wikiracing demo picks links the same way, because a choice holds at most 255 options.

Endpoint
One POST, JSON in and JSON out
Latency
70 to 500 ms, whatever the question count
Price
$0.042 per million input tokens; output free
Context
64k per request; 32k for state plus longest question. 262k for both with the opt-in TypeSafe-Danger-Zone-Long-Context header (preview)
Rate limits
100,000 tokens per second and 80 requests per second as of 8 Oct 2026. TypeSafe says the limits are adjusting and can change without notice; going over returns 429.
Input
Text: a string, a JSON object or a list of strings. PNG and JPEG images in preview with the TypeSafe-Danger-Zone-Images header
Models
jev-1.13.0 and jev-1.14.0. jev-preview is 1.14; jev-latest moves from 1.13 to 1.14 around 21 Oct 2026

Source: TypeSafe models and the quickstart. The same figures, with the evals, are on what is Jev.

curl example

Send one POST to https://api.typesafe.ai/v1/systemone with an Authorization header and a JSON body containing state, model, and questions.

curl
curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Your text here",
    "model": "jev-latest",
    "questions": {
      "category": {
        "type": "choice",
        "instructions": "Main topic",
        "criteria": {
          "technical": "Code or API",
          "support": "Help request"
        }
      }
    }
  }'

Keys: console.typesafe.ai/keys. Playground (no code): console.typesafe.ai/playground. Sources: TypeSafe quickstart, TypeSafe API.

Node snippet

Install with npm install @typesafe-ai/sdk (Node ≥20, MIT). The client reads TYPESAFE_API_KEY from the environment.

Node / TypeScript
import { TypeSafeClient, choice } from "@typesafe-ai/sdk";

const client = new TypeSafeClient();

const result = await client.systemOne({
  state: "Your text here",
  questions: {
    category: choice("Main topic", {
      technical: "Code or API",
      support: "Help request"
    })
  }
});

console.log(result.answers.category.choice); // "technical"
console.log(result.answers.category.confidence); // 0.87

Source: TypeSafe JS SDK.

Python snippet

Install with pip install typesafe-sdk (Python ≥3.10). Use Choice, Noul, and Score from the SDK, and AsyncTypeSafeClient for async.

Python
from typesafe_sdk import TypeSafeClient, Choice

client = TypeSafeClient()

result = client.system_one(
    state="Your text here",
    questions={
        "category": Choice(
            instructions="Main topic",
            criteria={
                "technical": "Code or API",
                "support": "Help request"
            }
        )
    }
)

print(result.answers["category"].choice)      # "technical"
print(result.answers["category"].confidence)  # 0.87

Sources: TypeSafe Python SDK, Python SDK usage.

Errors and retries

StatusMeaningWhat to do
401Bad API keyCheck your key at console.typesafe.ai/keys
422Invalid requestCheck the request shape against the docs
429Rate limitedRetry with exponential backoff (SDKs do this)
529OverloadedRetry with exponential backoff (SDKs do this)

Source: TypeSafe API. The SDKs retry 429 and 529 with exponential backoff automatically.

Model pinning and aliases

GET /v1/models lists the available aliases. Versioned IDs such as jev-1.13.0 work even when they are not listed.

To pin a version: set model: "jev-1.13.0" per request, or set defaultModel (JS) / model= (Python) on the client.

Sources: TypeSafe models, SystemOneRequest interface.

Pattern: Give it options; don't ask it to write

When a task looks like generation, have regex or an LLM extract candidates, then let Jev pick one with Choice. Math, counting and dates stay in code.

Example: to classify email subject lines, do not ask Jev to write the category. Extract a shortlist with an LLM, then let Jev choose from that list with a Choice question where the criteria describe each category.

Source: Jev 1.13 jaggedness.

Shadow-mode checklist

Our guidance, based on TypeSafe’s confidence docs:

  1. Log Jev’s answers next to the current path.
  2. Label a sample.
  3. Set a threshold per risk level. The docs’ examples are a 0.5 floor and 0.9 for destructive actions.
  4. Send anything below the threshold to a human or a larger model.
  5. Pin the version.
  6. Keep questions and thresholds in one place.

Source: TypeSafe confidence docs.

Step 4: write the state and the criteria so the answer is right

When a decision looks wrong, the model is rarely the cause. The state usually is. Four habits fix most of it, collected from builders who have run Jev in real loops, including N01ennn’s guide to the agent loop.

  • Send evidence, not conclusions. Put the original request, the progress and the constraints in separate fields. If you hand over “the research is complete”, Jev has to take your word for it.
  • Describe each option by what it means. A label such as “research” says nothing. “Collect evidence still needed for the goal” does. The criteria text is where the decision lives, and it is the first thing to rewrite when answers look wrong.
  • Do not rely on the field name. Jev does not see your question ID, so calling a field safe_to_publish adds no instruction. The requirement has to be in the question text and the option descriptions.
  • Put the questions that read the same state in one request. They run in parallel. The one limit is that a question cannot read another’s answer. If a decision depends on a fresh search result, search first and send a second request.

Counting, arithmetic and date maths are weak spots. Do them in code and send the result in as state.

Calling it from where you already are

You do not have to hold a TypeSafe key to use Jev. It is served through the gateways and framework integrations most stacks already have, which is also the quickest way to try it against a model you are currently paying for.

RouteWhy you would use it
Jev on OpenRouterOne key across models you already call
Jev on Cloudflare AI GatewayAt the edge, with Workers
Jev on Netlify AI GatewayThrough Netlify's gateway
Jev through LiteLLMBehind the LiteLLM proxy
Jev in Pydantic AITyped calls from Pydantic AI
langchain-typesafeThe LangChain integration package
Trace every judgment with PhoenixTracing each judgment in Phoenix
Vercel AI GatewayModel typesafe-ai/jev at https://ai-gateway.vercel.sh/typesafe, billed through AI Gateway. Key: AI_GATEWAY_API_KEY. Docs

Using Jev from a coding agent

Two ways, and they are not the same thing. The agent skill teaches Claude Code or Codex to write programs that call Jev — install it with npx skills add typesafe-ai/skills, and the skills page lists the others people have published. An MCP server instead lets the agent ask Jev for a judgment while it works, as a tool call; those are on the Jev MCP page.

Watch someone do it

58 walkthroughs, tutorials and tests, all playable here. Start with Greg Isenberg’s if you want the shortest path to a working call, or the full tutorials below it if you would rather watch a whole build.

Guideyoutube.com/@GregIsenberg

Jev is HERE. How to use it

Greg Isenberg and Ryan Vogel on the Startup Ideas Pod: what Jev is, the businesses it unlocks, and how to call it today through the Vercel AI Gateway.

Guideyoutube.com/@promptwarrior

Jev: full tutorial

Moritz starts from the API key, then builds three prototypes: a voice-controlled browser, memory retrieval, and a YouTube topic scorer, and says where Jev still needs an LLM or plain code around it.

Guideyoutube.com/@DavidOndrej

Build anything with Jev

David Ondrej explains how to use Jev, the architecture behind it, and how to build a business on it.

Guideyoutube.com/@avb_fj

Livestream: coding with Jev

Neural Breakdown with AVB takes Jev apart and looks at architectures for models that predict JSON. The video starts at 6:57.

Guideyoutube.com/@nateherk

I tested Jev on 12 real use cases

Nate Herk compares speed and cost against ordinary models, then builds an X feed classifier and a real-time paper-trading prototype live.

Guideyoutube.com/@KodeKloud

Jev Explained in 3 Mins

KodeKloud’s short: what a System One model decides, and why it answers in milliseconds.

Guideyoutube.com/@CalebWritesCode

Jev explained in 7min..

Caleb Writes Code: what Jev is and how to use it, in seven minutes.

Guideyoutube.com/@syntaxfm

wtf is jev?

CJ from Syntax explains how Jev works, then demos browser use, classification, code review, a model router and a chat bot with no LLM.

Guideyoutube.com/@vogeldev

Meet Jev: tested on 1,000 emails

Ryan Vogel runs Jev on 100 and then 1,000 of his emails: category, priority, spam and reply predictions.

Guideyoutube.com/@AICodeKing

Jev and Browser Use, fully tested

AICodeKing tests support routing, refund detection, prompt-injection resistance and browser automation.

Guideyoutube.com/@retriever-ai

Jev in the rtrvr.ai browser agent

Retriever AI tests Jev on real browser tasks: where it worked, where it struggled, and how they will use it next to larger models.

Guideyoutube.com/@NidhiSinghAttri

Jev and herdr: routing between models

Nidhi Singh’s setup: one terminal, three AI subscriptions, and Jev picks the model for Claude Code, Codex and Cursor.

Guideyoutube.com/@TechBrewRideHome

What is Jev? (Tech Brew Ride Home)

A podcast segment on TypeSafe AI, its $40 million raise, and why the name is a nod to Jevons paradox.

Guideyoutube.com/@GaryExplains

Jev: fast and cheap, but there is a caveat

Gary Explains on the catch: Jev understands natural language but it is not an LLM. It answers with structured values and a confidence level.

Guideyoutube.com/@Itssssss_Jack

Jev AI just dropped

Jack Roberts walks through the three kinds of micro decision: a yes or no, a choice from preloaded options, and a score from 1 to 100.

Guideyoutube.com/@maximilian-schwarzmueller

It really is. No joke.

Maximilian Schwarzmüller on a new kind of model that beats LLMs in the areas it was built for.

Guideyoutube.com/@albertolgaard

I tested the new Jev model

Albert Olgaard tests Jev and explains why the System One models matter.

Guideyoutube.com/@TheHunterBohm

I paired Jev with Astra

Hunter Bohm on how Jev works, pricing and parallel decisions, whether it is actually new, and his own Astra plus Jev benchmark.

Guideyoutube.com/@samwitteveenai

Open Jev Models Are Here!!

Sam Witteveen goes through the open decision models released in Jev's first week.

Guideyoutube.com/@engineerprompt

Steerable Reranking: How JEV Solves RAG

Prompt Engineering puts Jev in the reranking step of a RAG pipeline: why vector search and cosine similarity fail, how a steerable reranker works, and how it compares with LLM rerankers and cross-encoders. A Colab notebook comes with it.

Guideyoutube.com/@JulianGoldieSEO

Jev AI Full COURSE 1 HOUR

Julian Goldie’s hour-long course: the three question types, many decisions batched in one request, and ten use cases, from email sorting and lead scoring to internal linking across 586 pages and a browser agent finding flights.

Guideyoutube.com/@KevBuildsApps

Jev AI just changed video editing forever

Kev makes Jev the decision maker inside HyperEdit, his open-source AI video editor, and walks through the whole setup with Claude Code. The repository is free on GitHub.

Guideyoutube.com/@CoderOne

Open Source, Faster Jev is HERE

Coderone on Laya, the open System One model from Convai Innovations: what typed decisions are, why they replace a share of LLM calls, and Laya run locally to see if its figures hold up.

Guideyoutube.com/@daveebbelaar

Jev Explained for Python Developers

Dave Ebbelaar in Python: a support-ticket classification first, then Choice, Score and Noul, several questions in one call, and latency and price next to Claude Haiku, Opus 5 and Fable 5.1.

Guideyoutube.com/@Raul-Marin-Calleja

Jev para diseñadores: uso en Design Systems

Raúl Marín, in Spanish: what Jev decides against what an LLM writes, then closed judgments applied to a design system — variant choice, email classification next to GPT, fast UI rendering and screens generated from prompts. 21 minutes, with chapters.

Guideyoutube.com/@t3dotgg

Jev is incredible

Theo on what Jev does and why it matters.

Guideyoutube.com/@krishnaik06

Will Jev replace LLMs?

Krish Naik on what Jev is from TypeSafe AI, and whether it replaces an LLM.

Guideyoutube.com/@TheFintechBuilder

50 financial jobs, one model

The Fintech Builder runs Jev on fifty financial jobs and shows where it works and where it does not.

What to read next

The official quickstart first. Then the cookbook for the two-pass pattern, and the harness guide for what a real system looks like once Jev is inside it.

Preview of Cookbook: skill suggestion

Guidedocs.typesafe.ai

Cookbook: skill suggestion

TypeSafe’s recipe for picking at most one skill per agent turn out of 182: one request ranks them all, a second reads the top three.

Preview of Jev on Cloudflare

Guidedevelopers.cloudflare.com

Jev on Cloudflare

Examples for support routing, refund decisions and risk escalation.

When your first call works, the interesting question is what to point it at: the use cases group every build here by the job Jev does in it. For the code around the call, read the agent harness page, Jev with Claude Code and Jev agent orchestration. If a hosted call is the wrong shape for your data, training your own is the other route.

Common questions

How do I make my first Jev call?
Send one POST to TypeSafe's API with two fields: a state, which is the text to judge, and a questions object, where each question has a type of choice, score or noul and its instructions. The response comes back typed: a Choice with a probability for each option and a confidence, a Noul with the probability of yes, and a Score with probabilities per level and a confidence, in 70 to 500 milliseconds.
Do I need an SDK?
No. It is one HTTP request, so curl or fetch is enough. TypeSafe also ships Python and JavaScript SDKs that add retries with backoff when you go over a rate limit, and there are integrations for LangChain, Pydantic AI, LiteLLM, OpenRouter and the Cloudflare and Netlify gateways.
How many questions can one call hold?
Enough that people ask 61 in a single request. Jev answers every question in parallel against the same state, so a long rubric costs about the same as one question. The limits that do bite are 64k tokens per request, 32k for the state plus the longest question, and 255 options in a single choice.
What do I do with the confidence score?
Pick a threshold and act on the answers above it automatically, escalating the rest to a person or a larger model. On a Choice or Score, branch on the confidence; on a Noul, on the probability itself. There is no universal line; test it on your own data.
How do I use Jev with Claude Code or Cursor?
Either install the TypeSafe agent skill with npx skills add typesafe-ai/skills, so the agent writes programs that call Jev, or run an MCP server so the agent can ask Jev directly as a tool call.

Made with Jev is independent and not affiliated with TypeSafe AI. Every figure on this page is the one its author published, linked to where it can be checked.