Jev API Guide: Build AI Decision Systems with Confidence

Introduction

Released by TypeSafe AI on September 15, 2026, Jev is the company’s first System One decision model. Developers send state text and typed questions via a POST endpoint, and the model returns structured answers with calibrated probabilities rather than natural language text generation. This guide is built upon official TypeSafe documentation, Python and JavaScript SDK repositories, and updated technical specifications dated September 21, 2026. It walks through the entire lifecycle of Jev usage: Playground trial, API key creation, curl and SDK invocation, confidence threshold routing setup, benchmark comparison against large generative models, rate limit management, context budget control, and language support constraints. The current model version is jev-1.13.0. Pricing stands at $0.042 per million input tokens, with zero charges for output tokens. Rate caps are limited to 250,000 tokens per second and 1,200 requests per minute. The maximum input length for a single state payload is capped at 32K tokens, while the total per-request context budget is restricted to 64K tokens.

What Jev Is and Its Suitable Use Cases

Jev serves as TypeSafe AI’s flagship System One model. Its official definition describes it as a service that “receives state information and typed questions, and delivers structured results ready for program consumption.” It does not generate free-form text. It only returns probabilistic results from pre-defined options, ranks, or boolean judgements. This characteristic makes Jev ideal for decision nodes embedded within source code, instead of replacing general large language models for content writing tasks.

According to TypeSafe official specification data published on September 2026, Jev’s core technical parameters are listed in the table below.

Common production scenarios include job ticket classification, intent detection, content scoring, authenticity validation, duplicate filtering, and guardrail inspection for outputs generated by large generative models. The official documentation explicitly notes that Jev accepts plain text input only. Image, audio and video data must first be converted into text or structured fields before submission.

Step 1: Playground Trial and API Key Application

Jev remains in the early access preview stage, and the onboarding workflow contains three core steps.

1. Access Playground: Navigate to https://docs.typesafe.ai/introduction/quickstart and open console.typesafe.ai/playground. Paste arbitrary text content as state data, then submit a Noul-type question such as “Does this message express urgency?”. The platform returns probability results instantly.
2. Create API Key: Navigate to the Keys page within the developer console to create a secret key. The official document states “Get your API key from the dashboard”.
3. Configure environment variables: SDKs automatically read the TYPESAFE_API_KEY environment variable. Hardcoding secrets directly inside application source code is discouraged.

export TYPESAFE_API_KEY="YOUR_SECRET_KEY"
pip install typesafe-sdk       # Python 3.10+
npm install @typesafe-ai/sdk   # Node.js 20+

As of September 21, 2026, PyPI and npm registry records show the latest Python package typesafe-sdk version is 0.7.0, while JavaScript package @typesafe-ai/sdk reaches version 0.6.0. The PyPI package named typesafe-ai acts merely as a wrapper and installs typesafe-sdk under the hood.

Step 2: First API Call with curl

All Jev model variants share one unified endpoint. The request payload consists of only three top-level JSON fields: state, model, and questions.

curl -X POST https://api.typesafe.ai/v1/systemone \
-H "Authorization: Bearer $TYPESAFE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"state": "Hi, I have been trying to connect my Stripe account for 3 days and the integration keeps failing. I am",
"model": "jev-latest",
"questions": {
"urgency": {
"type": "noul",
"instructions": "Does this message express urgency?"
}
}
}'

The returned JSON payload contains three top-level keys: model, answers, and usage. The model field returns the actual resolved model version, even if the request uses an alias. This design facilitates audit logging.

{
"model": "jev-1.13.0",
"answers": {
"urgency": {"type": "noul", "noul": 0.99}
},
"usage": {"input_tokens": 360, "output_tokens": 39}
}

Step 3: Understand The Three Native Question Types

Jev exposes three native question primitives. Multiple question types can be mixed freely within one single API request. All questions run independent evaluations against the identical state object. Official tests confirm adding extra questions barely increases end-to-end response latency.

Key implementation details for these three primitives:

1. Question identifiers are never transmitted to the model. The dictionary keys exist solely for mapping returned answers. The model only consumes instructions and criteria content, so option descriptions must carry distinct semantics to avoid ambiguity.
2. The Score value represents weighted average across defined ranks. For example, if a 3-level score has a 0.57 probability assigned to level 1 and 0.43 probability assigned to level 2, the final score becomes 1.43. Official guidance recommends describing scenarios rather than pure numeric levels, as raw numeric labels may introduce probability dispersion bias.
3. Noul responses omit the confidence field. The binary probability value fully describes the distribution; values close to 1 represent true, while values near 0 represent false.

Python SDK Example for Multi-Question Batch Request

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

ticket = "Hi, I have been trying to connect my Stripe account for 3 days and the integration keeps failing. I am"
with TypeSafeClient() as client:
    response = client.system_one(
        state=ticket,
        questions={
            "department": Choice(
                instructions="Which team should handle this support ticket?",
                criteria={"billing": "Billing department", "engineering": "Technical engineering team"}
            )
        }
    )

The state parameter accepts string, JSON object or array formats. Official best practice recommends structuring state as JSON objects. Business entities such as tickets, orders and refund rules can be packed within one state object with explicit naming. The model reads this unified state snapshot and evaluates all attached questions.

Step 4: Build Three-Way Routing with Confidence Metrics

Confidence is calculated from the probability distribution shape. The value falls within the range from 0 to 1. Confidence reaches 1.0 when all probability mass concentrates on a single option. The more evenly probabilities spread, the lower the confidence value. The official approximate formula for three-option scenarios is (max_probability *3 -1)/2. This metric describes output distribution characteristics, and the documentation explicitly clarifies that confidence does not serve as proof that an answer is factually correct.

The recommended production pattern treats confidence as a second decision dimension. Different threshold boundaries are defined based on business risk levels.

from typesafe_sdk import Choice, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state=user_message,
        questions={
            "action": Choice(
                instructions="What does the user want to do?",
                criteria={
                    "check_balance": "View account balance",
                    "reset_password": "Request password reset"
                }
            )
        }
    )

TypeSafe names this architecture Confidence-Gated Routing. Three additional native patterns are documented: Speculative Fan-Out, Composite Scoring, and Intent Routing. Speculative Fan-Out submits multiple speculative questions in one request, leaving downstream application logic to pick required results. Composite Scoring merges multiple atomic Score outputs programmatically. Intent Routing routes classified requests to deterministic code logic, specialized LLMs, or human reviewers. Threshold configuration should start conservatively and be iteratively tuned using real production datasets.

Step 5: Benchmark Against Large Models Using Open-Source Adapters

TypeSafe has open-sourced system-one-adapter-python. This library acts as an alternative implementation of TypeSafeClient. It reuses identical Choice, Score and Noul interfaces to invoke general large models, making cost, latency and accuracy side-by-side comparison straightforward. According to GitHub statistics dated September 21, 2026, this repository has 209 stars, and the PyPI version is 0.2.0.

pip install 'system-one-adapter[openai]'

from system_one_adapter import SystemOneAdapterClient, Noul
from system_one_adapter.providers.openai import OpenAIProvider

client = SystemOneAdapterClient(
    structured_outputs=True,
    llm_answer_mode="probabilities",
    normalize_probabilities=True,
)
response = client.system_one(...)

The OpenAIProvider built into the adapter accepts standard OpenAI compatible endpoints as comparison baselines. It preserves original request logs for latency measurement, retry tracking and token consumption statistics. When teams run mixed model services across multiple endpoints, centralized request management simplifies observability. An API gateway can standardize authentication, logging and routing for diverse model backends. 4sapi works as an API gateway that unifies traffic management across different model providers for production agent pipelines.

Step 6: Mandatory Constraints Before Production Deployment

Based on independent testing reports published by Emil Lindfors on September 18, 2026, Jev has six core limitations that developers must understand before online deployment.

1. Adjustable rate limits. Official warnings note GPU resource availability can change without advance notice. The SDK applies retry-after header backoff by default. Python implementations raise exceptions when rate limits are exceeded.
2. Dual constraint on context budget. The total context budget is capped at 64K tokens for all questions combined, while the longest single state segment cannot exceed 32K tokens. Documents exceeding these limits must be pre-split.
3. Language priority. The model can process Chinese and Japanese text, yet accuracy drops for non-English content. Lindfors’ Norwegian test shows roughly 2,006 characters per token. A 32K token context can only contain around 64,000 characters.
4. Instruction sensitivity. Tests reveal accuracy declines when prompt wording deviates heavily from training distributions. The official recommendation is to write direct instructions aligned closely with expected output values.
5. Non-modifiable weights. All model weights remain fixed. Tuning can only be achieved by adjusting state and criteria content. Fine-tuning is not supported.
6. No reasoning explanation. The response only delivers options and probability values. It is not suitable for scenarios requiring traceable logical justification.

Frequently Asked Questions

Can Jev be directly connected right now?

Jev stays in early preview access. Developers join the waitlist via console.typesafe.ai to obtain API keys. The Playground environment is available for trial evaluation. Third-party platforms including OpenCode Zen host jev-1.13 and free tier jev-1.13-free for preliminary testing.

What model version does jev-latest alias resolve to?

The model field returns the actual underlying version number, enabling stable result comparison. Developers should avoid locking confidence thresholds purely on alias names, as alias targets automatically shift upon new releases. Response headers carry the resolved real version string for log auditing.

Does Jev store user submitted data?

The model documentation states Jev will not use request payloads for model training. Enterprise clients can request zero-data retention policies. The service infrastructure is hosted on the US West Coast. Enterprises should independently assess compliance risks for cross-border data transmission.

How many questions can be sent within a single request?

The official documentation does not enforce hard limits on question quantity. The constraint comes from the total 64K context budget. Each Choice question supports a maximum of 255 options, and each Score question accepts up to 10 rank levels. Official practice recommends submitting all potential questions in one batch and filtering unused responses in application code. The tradeoff is that all submitted questions consume input token quota.

If Score equals 1.0, what conclusion can be drawn?

A score value of 1.0 cannot be interpreted as definitive correctness. It may mean all probability concentrates on level 1, or probability is split evenly between level 0 and level 2. Official specifications require score values to be read together with probability arrays and confidence metrics.

Conclusion

The core workflow for adopting Jev consists of applying for API keys on the developer console, sending state and question payloads to api.typesafe.ai/v1/systemone, and consuming results through Choice, Score and Noul primitives. The architecture splits complex business judgement tasks into atomic decision points, and confidence values are used to build branch routing logic within application code.

Jev is purpose-built for structured decision tasks rather than open-ended content generation. It shines for lightweight judgement nodes inside agent workflows, where low latency and predictable cost are critical requirements. The zero-output-token pricing model reduces operational expenditure when running large volumes of judgement requests. However, developers must strictly respect context budget limits, language performance gaps, and the absence of native reasoning explanation.

When integrating Jev with other LLMs in production stacks, teams often consolidate model endpoints to simplify authentication and monitoring. API gateway services streamline multi-model deployment and traffic governance.

International access: https://4sapi.com
Domestic access: https://4sapi.cn