Jev API Reference

The TypeSafe Jev API evaluates unstructured application state against typed questions (choice, score, noul) in a single synchronous parallel forward pass, returning calibrated probabilities and structured decisions without generating conversational text.

Quick Reference: Minimal Request & Response

To call Jev directly via HTTP, send a POST request with your API key, target model, input state, and one or more typed questions:

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": "Customer requested immediate cancellation after invoice failed twice.",
    "questions": {
      "churn_risk": {
        "type": "noul",
        "instructions": "Is the customer threatening to churn or cancel?"
      },
      "dept": {
        "type": "choice",
        "instructions": "Route this ticket to the primary owner.",
        "criteria": {
          "billing": "Invoice, charge, or refund problems",
          "retention": "Cancellation threats and churn risk",
          "support": "General technical questions or bugs"
        }
      }
    }
  }'

The API returns HTTP 200 with evaluated answers mapped under answers:

{
  "model": "jev-latest",
  "answers": {
    "churn_risk": {
      "type": "noul",
      "noul": 0.942
    },
    "dept": {
      "type": "choice",
      "choice": "retention",
      "probabilities": {
        "billing": 0.048,
        "retention": 0.942,
        "support": 0.010
      },
      "confidence": 0.942
    }
  },
  "usage": {
    "input_tokens": 82,
    "output_tokens": 18
  }
}

Endpoint & Authentication

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <TYPESAFE_API_KEY>
Content-Type: application/json

• Authentication: Every request requires an API key issued via console.typesafe.ai, passed in the Authorization header using standard Bearer <TOKEN> formatting.
• Model identifiers:
  • jev-latest: Points to the latest stable official release (currently jev-1.13.0).
  • jev-1.13.0: Pinned immutable release.
  • jev-preview: Points to the most recent release whether official or not, moving ahead of jev-latest when a preview build is available (currently both aliases point to jev-1.13.0).
• Pricing: $0.042 per 1M input tokens ($42 per billion tokens). Output tokens are free ($0.00 unmetered).

You can also reach the same model by calling Jev through OpenRouter (typesafe/jev-1.13 on OpenRouter's Decisions API) or by using Jev through the Vercel AI SDK (experimental_evaluate, directly or via AI Gateway).

Root Request Schema

The top-level JSON request body requires three fields:

Primitive Question Schemas

Jev accepts three typed primitives. In the raw HTTP API, instructions is required for all three question types. Jev rejects freeform conversational prompts or requests for unstructured prose.

1. choice (Multiclass Selection)

Selects a single option from a discrete set of 2 to 255 predefined values.

• type: "choice" (required)
• instructions: string, object, or array (required) — Clarifies the evaluation objective.
• criteria: object (required) — Map of option labels to string descriptions (or null for unguided choices). Minimum 2 options, maximum 255. Note: the raw API defines choices directly as keys in criteria; there is no separate options array.

Response shape under answers[key]:

• type: "choice"
• choice: string — The option key assigned the highest probability.
• confidence: float (0.0 to 1.0) — Concentration of probability mass on the winning option.
• probabilities: object — Map of each option key to its floating-point probability (sums to 1.0).

2. score (Ordinal Rubric)

Evaluates state against an ordered scale from 2 to 10 distinct levels.

• type: "score" (required)
• instructions: string, object, or array (required) — Defines the grading criterion.
• criteria: array of strings (required) — 2 to 10 descriptions ordered strictly from lowest index (0) to highest. Note: the field name is criteria, not levels.

Response shape under answers[key]:

• type: "score"
• score: float — Expected continuous value across level indices ($\sum i \times p_i$).
• confidence: float (0.0 to 1.0) — Concentration of probability mass around the score.
• legend: object — Map of string index keys ("0", "1", ...) to their criteria descriptions.
• probabilities: object — Map of string index keys ("0", "1", ...) to their individual probabilities.

3. noul (Boolean Probability)

Evaluates whether a declarative statement is true regarding the state.

• type: "noul" (required)
• instructions: string, object, or array (required) — Binary evaluation statement or condition to evaluate.
• criteria: object (optional) — Keyed by "true" and/or "false" to anchor outcome definitions.

Response shape under answers[key]:

• type: "noul"
• noul: float (0.0 to 1.0) — Direct calibrated probability that the condition is true.
• Note: Noul answers return no separate confidence field or boolean result property. Your application code applies its own threshold (e.g. noul >= 0.85).

Multi-Primitive Request & Response Example

Below is a complete request evaluating all three primitives concurrently over shared state:

{
  "model": "jev-latest",
  "state": {
    "account_tier": "enterprise",
    "incident_description": "Production database latency spiked to 4200ms following migration script 084. Connection pool saturated."
  },
  "questions": {
    "routing_target": {
      "type": "choice",
      "instructions": "Determine the primary engineering owner for this incident.",
      "criteria": {
        "database_reliability": "Connection pool, query degradation, schema migrations, lock contention.",
        "platform_infra": "Kubernetes pod restarts, CPU throttle, hardware failures.",
        "core_backend": "Application code exceptions, third-party API timeouts.",
        "networking": "DNS resolution errors, VPC peering packet drops."
      }
    },
    "severity_level": {
      "type": "score",
      "instructions": "Grade incident severity from minor disruption to total service outage.",
      "criteria": [
        "Negligible impact or internal-only alert",
        "Minor latency elevation within SLA buffers",
        "Degraded performance affecting user transactions",
        "Critical production outage causing continuous data loss"
      ]
    },
    "requires_page": {
      "type": "noul",
      "instructions": "Should an on-call engineer be paged immediately?",
      "criteria": {
        "true": "Active user transactions are failing or latency violates enterprise SLA.",
        "false": "The issue is contained, self-healing, or non-production."
      }
    }
  }
}

The response contains the model identifier, typed answers under their respective question keys, and token usage:

{
  "model": "jev-1.13.0",
  "answers": {
    "routing_target": {
      "type": "choice",
      "choice": "database_reliability",
      "probabilities": {
        "database_reliability": 0.942,
        "platform_infra": 0.038,
        "core_backend": 0.016,
        "networking": 0.004
      },
      "confidence": 0.942
    },
    "severity_level": {
      "type": "score",
      "score": 2.14,
      "legend": {
        "0": "Negligible impact or internal-only alert",
        "1": "Minor latency elevation within SLA buffers",
        "2": "Degraded performance affecting user transactions",
        "3": "Critical production outage causing continuous data loss"
      },
      "probabilities": {
        "0": 0.005,
        "1": 0.048,
        "2": 0.752,
        "3": 0.195
      },
      "confidence": 0.887
    },
    "requires_page": {
      "type": "noul",
      "noul": 0.963
    }
  },
  "usage": {
    "input_tokens": 184,
    "output_tokens": 34
  }
}

HTTP Error Codes & Diagnostics

TypeSafe documents four specific HTTP status codes for /v1/systemone:

Resolving HTTP 422 Errors

HTTP 422 indicates upfront validation failure before reaching model weights:

1. Option Boundary Violations:
   • Choice: Passing fewer than 2 or more than 255 options returns 422. If classifying large ontologies (e.g. hundreds of items), split into a two-tier hierarchy (broad category first, then sub-category).
   • Score: Passing fewer than 2 or more than 10 criteria descriptions returns 422. Group granular scales into 3 to 5 discrete behavioral tiers.
2. Context Budget Violations:
   • TypeSafe documents an operational ceiling of 64,000 total request tokens, with state plus the longest single question definition capped at 32,000 tokens. Exceeding these thresholds triggers immediate 422 rejection.
   • Pre-filter payloads in application code:

     cleaned_state = {
         "summary": ticket["summary"],
         "error_snippet": ticket["raw_log"][:2000],
         "tier": ticket["user"]["tier"]
     }
     

Rate Limits, Concurrency, and Workload Optimization

[!NOTE] Operational Envelopes During Early Access TypeSafe operates Jev under dynamic early-access concurrency envelopes. In initial developer documentation, baseline ceilings of 1,200 requests per minute (RPM) and 250,000 tokens per second (TPS) per organization have been cited, with request context ceilings capped at 64,000 tokens (32,000 for state plus longest question). Because early-access capacity and organization quotas adjust dynamically based on infrastructure demand, treat published figures as illustrative operational envelopes rather than immutable SLAs. Check your organization console for your active account limits.

Workload Crossover Dynamics

Whether an application approaches request-rate throttling or token-throughput throttling first depends on payload size:

• Workloads with compact payloads (under 10,000 tokens): Applications typically reach request-rate thresholds before token-throughput limits. For example, running 20 requests per second with 500-token payloads consumes only 10,000 tokens per second.
• Workloads with large context payloads (over 15,000 tokens): Token throughput becomes the primary constraint. Running 12 requests per second with 25,000-token payloads consumes 300,000 tokens per second, triggering throttling even at low request volumes.

Optimization Pattern: Question Batching

The most effective way to maximize throughput and minimize latency is batching multiple questions into a single request over a shared state:

• Individual Calls (Anti-Pattern): Evaluating 4 questions separately consumes 4 HTTP requests against rate limits, incurs 4 separate network round-trips, and resends state tokens 4 times.
• Batched Call (Recommended): Evaluating 4 questions concurrently in one system_one call consumes 1 HTTP request, incurs 1 network round-trip, and processes state tokens once.

from typesafe_sdk import TypeSafeClient, Choice, Score, Noul

client = TypeSafeClient()

# Evaluates 4 questions concurrently in 1 request over shared state
response = client.system_one(
    model="jev-latest",
    state=incident_context,
    questions={
        "dept": Choice(
            instructions="Route ticket",
            criteria={"billing": "Billing", "tech": "Technical", "sales": "Sales"}
        ),
        "urgency": Score(
            instructions="Grade issue severity",
            criteria=["low", "medium", "high", "critical"]
        ),
        "churn_risk": Noul(
            instructions="Is customer threatening cancellation or chargeback?"
        ),
        "needs_manager": Noul(
            instructions="Does customer demand supervisor escalation?"
        )
    }
)

Retry Behavior

TypeSafe's official client SDKs retry transient failures by default, including rate-limit and server errors, and honor retry timing returned by the service. If you use an official SDK with its default retry policy, you normally do not need to implement your own retry loop.

For direct HTTP integrations, retry 429 Too Many Requests and 529 Overloaded responses with exponential backoff rather than retrying immediately.

Official Client SDKs

TypeSafe provides client libraries that wrap POST /v1/systemone with native types:

Python SDK (typesafe-sdk)

pip install typesafe-sdk

import os
from typesafe_sdk import TypeSafeClient, Choice, Score, Noul

client = TypeSafeClient(api_key=os.environ["TYPESAFE_API_KEY"])

response = client.system_one(
    model="jev-latest",
    state={"query": "return item within 30 days unopened"},
    questions={
        "action": Choice(
            instructions="Determine return eligibility",
            criteria={
                "approve": "Meets return policy guidelines",
                "reject": "Violates return policy window",
                "manual_review": "Borderline or ambiguous request"
            }
        ),
        "urgency": Score(
            instructions="Customer urgency level",
            criteria=["low", "medium", "high", "critical"]
        ),
        "is_fraud_risk": Noul(
            instructions="Does this request indicate return fraud?"
        )
    }
)

# Typed answers are accessed via typed convenience mappings on the response
print(response.choices["action"].choice)
print(response.choices["action"].confidence)
print(response.scores["urgency"].score)
print(response.nouls["is_fraud_risk"].noul)

TypeScript SDK (@typesafe-ai/sdk)

npm install @typesafe-ai/sdk

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

const client = new TypeSafeClient({
  apiKey: process.env.TYPESAFE_API_KEY!,
});

const response = await client.systemOne({
  model: "jev-latest",
  state: { ticket: "Customer reports card charged twice on checkout" },
  questions: {
    category: choice("Classify support category", {
      billing: "Payment or subscription issue",
      technical: "System or platform bug",
      account: "Credentials or security",
    }),
    urgency: score("Assess support urgency", [
      "low",
      "normal",
      "urgent",
      "critical",
    ]),
    needsEscalation: noul("Does this require immediate supervisor intervention?"),
  },
});

console.log(response.answers.category.choice);
console.log(response.answers.category.confidence);
console.log(response.answers.urgency.score);
console.log(response.answers.needsEscalation.noul);

Related Context

First-call tutorial with setup instructions and practical question engineering

implementation↗

Breakdown of the $0.042/M input rate, free output tokens, and workload modeling

product↗

Compare primitive semantics, return types, and probability distributions

comparison↗

Return to the primary TypeSafe Jev entity guide for architectural details and benchmark data

entity↗

Sources & Documentation

1. TypeSafe AI Official Documentation: API Reference and System One Schema — Official HTTP API reference covering endpoints, required fields, question schemas, response payloads, and HTTP status codes.
2. TypeSafe AI Official Documentation: Models and Concurrency — Official documentation on model identifiers (jev-latest, jev-preview, jev-1.13.0) and operational limits.
3. TypeSafe SDK Documentation: Python and JavaScript Client Libraries — Official SDK installation, client configuration, and typed answer access patterns.