How to Use Jev: Getting Started with the Jev API

This guide assumes you know what Jev is. If not, start with What is Jev?.

1. Get access and an API key

Jev is in early access. Join the waitlist at typesafe.ai. In the first week after launch, early users reported being let in within a day or two.

Once you’re in:

1. Try a few questions in the Playground. It’s the fastest way to get a feel for question wording.
2. Create an API key on the keys page.
3. Make it available to your code as an environment variable. Both official SDKs read TYPESAFE_API_KEY automatically.

export TYPESAFE_API_KEY="your-key-here"

2. Install an SDK

Python (3.10 or newer):

pip install typesafe-sdk
# or: uv add typesafe-sdk

JavaScript / TypeScript (Node.js 20 or newer):

npm install @typesafe-ai/sdk

No SDK for your language? Call the HTTP API directly (below), or check the community SDKs.

3. Make your first call

The example asks three questions about one product review: which topic it’s about (Choice), how positive it is (Score), and whether the store should follow up (Noul).

Python

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient()  # reads TYPESAFE_API_KEY, uses jev-latest

review = "Arrived two days late and the box was crushed, but the headphones sound great."

response = client.system_one(
    state=review,
    questions={
        "topic": Choice(
            instructions="What is the review mainly about?",
            criteria={
                "product": "The product itself: quality, features, performance",
                "delivery": "Shipping speed or packaging",
                "support": "Customer service interactions",
            },
        ),
        "sentiment": Score(
            instructions="Overall sentiment of the review",
            criteria=["Negative", "Mixed", "Positive"],
        ),
        "needs_follow_up": Noul(
            instructions="The customer reports a problem the store should follow up on",
        ),
    },
)

topic = response.answers["topic"]
print(topic.choice, topic.probabilities, topic.confidence)
print(response.answers["sentiment"].score)
print(response.answers["needs_follow_up"].noul)

JavaScript / TypeScript

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

const client = new TypeSafeClient(); // reads TYPESAFE_API_KEY

const response = await client.systemOne({
  state: { review: "Arrived two days late and the box was crushed, but the headphones sound great." },
  questions: {
    topic: choice("What is the review mainly about?", {
      product: null,
      delivery: null,
      support: null,
    }),
  },
});

console.log(response.answers.topic.choice);

Answer types are inferred from your questions, so response.answers.topic is typed as a Choice answer. The SDK also exports score() and noul() helpers; see the JavaScript SDK reference for their signatures.

curl

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Arrived two days late and the box was crushed, but the headphones sound great.",
    "questions": {
      "needs_follow_up": {
        "type": "noul",
        "instructions": "The customer reports a problem the store should follow up on"
      }
    }
  }'

4. Read the answers

The response has one entry in answers for each question you asked, keyed by the name you gave it:

• Choice returns choice (the winning option), probabilities (one per option, summing to 1), and confidence.
• Score returns score, the probability-weighted position on your scale. With three levels it runs from 0 to 2, so 1.6 means “between Mixed and Positive, leaning Positive.” It also returns probabilities per level, a legend mapping level numbers to your descriptions, and confidence.
• Noul returns noul, the probability that the statement is true, from 0 to 1.

The response also reports usage.input_tokens, which is what you’re billed for. Output tokens aren’t billed. See pricing.

5. Use confidence to decide when to act

The reason to use Jev instead of parsing text from an LLM is that you get a usable measure of certainty. A simple starting pattern is three bands:

topic = response.answers["topic"]

if topic.confidence >= 0.8:
    route_automatically(topic.choice)
elif topic.confidence >= 0.5:
    route_with_review(topic.choice)
else:
    send_to_human(review)

The thresholds above are placeholders. TypeSafe recommends starting conservatively, testing on your own data, and gating riskier actions (refunds, deletions, money movement) at a higher threshold than harmless ones. Noul answers don’t carry a confidence field; threshold noul directly.

6. Pin a model version for production

jev-latest points at the newest stable release, currently jev-1.13.0. When a new version ships, the alias moves and your answers can shift without any code change. Once you’ve tuned thresholds, pin the exact version:

client = TypeSafeClient(model="jev-1.13.0")

Every response includes a model field with the version that actually answered, which is worth logging.

Tips for writing good questions

• One judgment per question. Split “is this urgent and about billing?” into two questions and combine them in code.
• Say exactly what you mean. Jev reads instructions literally. Put boundary cases into the option descriptions.
• Keep math and dates in code. Jev is not a calculator and doesn’t reliably compare dates.
• Send only the relevant state. Irrelevant detail in the state lowers accuracy.

Where to go next

• Official cookbooks cover guardrails, re-ranking, RAG passage filtering, and more.
• Want Jev inside Claude Code or Codex? Browse MCP servers and agent skills and coding-agent tools.
• Budgeting? Use the cost calculator.

Frequently asked questions

How long does the Jev waitlist take?

TypeSafe doesn't publish a timeline. Early users reported getting access within a day or two of signing up in the first week after launch.

Which SDKs are official?

TypeSafe publishes official SDKs for Python (typesafe-sdk, Python 3.10+) and JavaScript/TypeScript (@typesafe-ai/sdk, Node.js 20+). Community SDKs exist for Go, Java, Rust, Elixir, and .NET.

What is the difference between jev-latest and jev-1.13.0?

jev-latest is an alias that moves to each new stable release. jev-1.13.0 is a fixed version. Use the alias while experimenting and pin the version once you have tuned confidence thresholds.