How to use Jev:
your first call.

Four ways to make a first call

TypeSafe AI documents four routes in its quick start (opens in a new tab). Pick the one that matches how you work:

• The playground. Paste an input, add a question and see the result in the browser. No code and the fastest way to test an idea. Open the playground (opens in a new tab).
• The HTTP API. One POST request to https://api.typesafe.ai/v1/systemone with your key as a Bearer token.
• The Python SDK. pip install typesafe-sdk (Python 3.10 or later). The client reads TYPESAFE_API_KEY from the environment and calls jev-latest by default.
• The agent skill. If a coding agent is writing the integration, TypeSafe publishes a skill that teaches it the API (npx skills add typesafe-ai/skills --skill typesafe-ai).

The steps below use the API and the SDK, with one example: sorting an incoming email.

Step 1: Write your questions

A request has three parts: the state (the input to evaluate), the model, and a map of questions. Each question is one of three types:

• Choice picks one option from a set you define, as a map of option name to description.
• Score places the input on an ordered scale you describe in words.
• Noul returns the probability that a yes/no statement is true.

Two details from TypeSafe's Choice docs (opens in a new tab) save a lot of debugging. The question ID you choose (category below) is never shown to the model, so the full question must be in instructions. And both the option names and their descriptions are sent, so write descriptions that clearly separate one option from another.

{
  "model": "jev-latest",
  "state": "From: Dana Lee <dana@acme.io>\nSubject: Invoice #4471 charged twice\nBody: Our card was charged twice for March. Can you refund the duplicate today? Our finance close is tomorrow.",
  "questions": {
    "category": {
      "type": "choice",
      "instructions": "What kind of email is this?",
      "criteria": {
        "needs_reply": "A person expecting a response from us",
        "updates": "Notifications, receipts, product updates",
        "promotions": "Marketing and newsletters",
        "spam": "Unwanted or suspicious mail"
      }
    },
    "needs_human": {
      "type": "noul",
      "instructions": "Does this email involve money, legal risk or an upset customer?"
    }
  }
}

Step 2: Call the API

Send the request with your key. Get the key from TypeSafe's dashboard, as described in the quick start.

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Step 3: Read the response

Each answer is returned under the question ID you chose. The values below are illustrative; the shape follows TypeSafe's API.

{
  "model": "jev-1.13.0",
  "answers": {
    "category": {
      "type": "choice",
      "choice": "needs_reply",
      "confidence": 0.84,
      "probabilities": { "needs_reply": 0.91, "updates": 0.05, "promotions": 0.03, "spam": 0.01 }
    },
    "needs_human": { "type": "noul", "noul": 0.88 }
  },
  "usage": { "input_tokens": 212, "output_tokens": 31 }
}

• choice is the selected option, and probabilities gives one probability per option.
• confidence collapses the shape of those probabilities into a single number from 0 to 1: 1 when all the probability sits on one option, 0 when it is spread evenly. Score answers carry a score, a legend of your levels and a confidence too.
• noul is the probability that the statement is true. Noul answers don't carry a confidence value.
• usage reports input tokens, which is what you're billed for.

Step 4: Turn confidence into rules

This is where Jev earns its keep. TypeSafe's confidence guide (opens in a new tab) suggests three paths: act automatically when confidence is high, proceed with care or ask for confirmation in the middle, and route to a person or a stronger model when it is low. It uses 0.5 as a floor, and says thresholds should scale with the cost of being wrong, so a destructive action needs a higher bar than a read-only one. It also advises starting conservative and testing on your own data.

from typesafe_sdk import Choice, Noul, TypeSafeClient

client = TypeSafeClient()  # reads TYPESAFE_API_KEY from the environment

response = client.system_one(
    state=email_text,
    questions={
        "category": Choice(
            instructions="What kind of email is this?",
            criteria={
                "needs_reply": "A person expecting a response from us",
                "updates": "Notifications, receipts, product updates",
                "promotions": "Marketing and newsletters",
                "spam": "Unwanted or suspicious mail",
            },
        ),
        "needs_human": Noul(instructions="Does this email involve money, legal risk or an upset customer?"),
    },
)

category = response.answers["category"]
if category.confidence < 0.5:
    route_to_human(email_text)   # the model is genuinely unsure
elif category.choice == "spam":
    archive(email_text)
else:
    label(email_text, category.choice)

Step 5: Keep the cost down

• Batch your questions. Questions about the same input go in one request, so the input is read once.
• Send only what the decision needs. Input length is the biggest lever. An email's subject and first few hundred words usually decide the category.
• Price it first. The cost calculator estimates a monthly bill from volume, item length and questions per item.

Other ways to reach Jev

Besides TypeSafe's own API, Jev is available through the Vercel AI Gateway, OpenRouter and LiteLLM. The resources page links each setup guide.

What to build first

Pick a decision a person currently makes over and over: which team gets this ticket, does this lead deserve a call, is this post spam. The use cases show the questions and the cost for each. For how Jev differs from a language model, read Jev vs ChatGPT and Claude.

Common questions

How do I use Jev?

Send TypeSafe's API an input (called the state) and the questions you want answered. Each question is a Choice, a Score or a Noul, and lists the answers it accepts. Jev returns the answer with a probability for each option and, for Choice and Score, a confidence value. You can try this in the browser first, in TypeSafe's playground.

Do I need to code to use Jev?

Not to try it. The playground runs in the browser. To run Jev on live data you call the API or use the Python SDK, or use a tool someone has already built on it.

Which model name do I send?

Use "jev-latest". At the time of writing it points to Jev 1.13 (jev-1.13.0). The Python SDK uses jev-latest by default.

How do I get a Jev API key?

From TypeSafe's dashboard, as described in their quick start. You send it as a Bearer token in the Authorization header.

What does Jev cost to run?

TypeSafe AI bills $0.042 per million input tokens and does not bill output. For a typical email with three questions that's around 2 cents per 1,000 emails. Use the cost calculator for your own workload.