Jev API: Endpoint, Request Format and Responses

This page covers TypeSafe’s own API. If you reach Jev through Vercel, OpenRouter or Cloudflare, the idea is the same but the endpoint, model name and some field names differ; see Jev channels compared.

Everything below was checked against live calls on September 19, 2026.

Endpoint and authentication

Item	Value
Endpoint	POST https://api.typesafe.ai/v1/systemone
Auth header	Authorization: Bearer <your key>
Body	JSON (Content-Type: application/json)
Model list	GET https://api.typesafe.ai/v1/models

Keys are created in the TypeSafe console once your account has access. See How to get a Jev API key. Keep the key in an environment variable; both official SDKs read TYPESAFE_API_KEY automatically.

Request body

Field	Required	What goes in it
model	Yes. Leaving it out returns HTTP 422	jev-1.13.0, jev-latest or jev-preview
state	Yes	The content to judge: a string, a JSON object or an array of text
questions	Yes	A map from your own IDs to question objects

The question IDs are yours. They come back as keys in the answer, and TypeSafe says they are not shown to the model, so write the full question in instructions.

Question objects

Each question has a type, an instructions field and, depending on the type, criteria:

type	criteria	Example
noul	Optional: { "true": "...", "false": "..." } describing what yes and no mean	“Is the customer asking for money back?”
choice	Required: a map of option name to description (a description can be null)	billing / technical / sales
score	Required: an ordered array of level descriptions	“Can wait a week”, “This week”, “Today”

instructions, option descriptions and level descriptions can also be JSON objects or arrays when a question needs structure. A Choice accepts up to 255 options.

Response body

A real response to a three-question request (our test, jev-1.13.0, 539 ms):

Response

{
  "model": "jev-1.13.0",
  "answers": {
    "wants_refund": { "type": "noul", "noul": 0.99 },
    "queue": {
      "type": "choice",
      "choice": "billing",
      "confidence": 1,
      "probabilities": { "sales": 0, "billing": 1, "technical": 0 }
    },
    "urgency": {
      "type": "score",
      "score": 2,
      "confidence": 1,
      "legend": { "0": "Can wait a week", "1": "Should be handled this week", "2": "Needs a reply today" },
      "probabilities": { "0": 0, "1": 0, "2": 1 }
    }
  },
  "usage": { "input_tokens": 451, "output_tokens": 72 }
}

Things worth knowing about the response:

• model always reports the exact version that answered (jev-1.13.0), even when you sent an alias. Log it if you tune thresholds.
• Noul answers have no confidence; the noul probability is the signal. Choice and Score answers carry both probabilities and a confidence derived from them. See confidence.
• usage.output_tokens is reported but not billed. Only input tokens cost money.

A complete request in three languages

curl

curl -s https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-1.13.0",
    "state": "I was charged twice for my annual plan this morning. Please refund one of the charges today.",
    "questions": {
      "wants_refund": { "type": "noul", "instructions": "Is the customer asking for money back?" }
    }
  }'

Python

# pip install typesafe-sdk   (Python 3.10+)
from typesafe_sdk import Noul, TypeSafeClient

client = TypeSafeClient(model="jev-1.13.0")  # reads TYPESAFE_API_KEY

response = client.system_one(
    state="I was charged twice for my annual plan this morning. Please refund one of the charges today.",
    questions={"wants_refund": Noul(instructions="Is the customer asking for money back?")},
)
print(response.answers["wants_refund"].noul)  # 0.99 in our test

JavaScript

// npm install @typesafe-ai/sdk   (Node.js 20+)
import { TypeSafeClient, noul } from '@typesafe-ai/sdk';

const client = new TypeSafeClient({ defaultModel: 'jev-1.13.0' }); // reads TYPESAFE_API_KEY

const response = await client.systemOne({
  state: 'I was charged twice for my annual plan this morning. Please refund one of the charges today.',
  questions: { wantsRefund: noul('Is the customer asking for money back?') },
});
console.log(response.answers.wantsRefund.noul); // 0.99 in our test

We ran the Python and JavaScript versions with typesafe-sdk 0.7.0 and @typesafe-ai/sdk 0.6.0. Full walkthroughs: Python and JavaScript.

Model names that work

Name you send	Result (Sep 19, 2026)
jev-1.13.0	Works. Recommended when you need repeatable results
jev-latest	Works, resolves to jev-1.13.0; moves when a new release ships
jev-preview	Works, currently also jev-1.13.0
jev-1.13	HTTP 400, “Unknown model: jev-1.13”, even though one example in TypeSafe’s own docs uses this spelling

GET /v1/models currently lists only the two aliases, not the versioned IDs. The versioned ID is accepted anyway.

Limits

• State size: TypeSafe documents 64k tokens per request and 32k for the state plus the longest question. In our tests a request with 32,204 input tokens went through; one with roughly 33,600 was rejected with HTTP 400 max_tokens_exceeded.
• Rate limits: 1,200 requests per minute and 250,000 tokens per second, adjusted dynamically by TypeSafe. We saw no rate-limit headers on responses. See Jev rate limits.
• Many questions per call: the number of questions is limited only by the token budget. Asking 20 yes/no questions in one call took 332 ms in our test, the same as asking one.

Error responses

Errors come back as JSON under a detail key. These are the ones we reproduced on the official endpoint:

HTTP	Body (abridged)	Cause
401	authentication_error: “Cannot authenticate with the server…”	Wrong or revoked key. Details
403	authentication_error: “Must supply an API key!…”	No Authorization header at all. Details
400	api_usage_error: “Invalid request.”	Unknown question type, for example boolean. Details
400	api_usage_error: “Unknown model: …”	Model name not recognized
400	max_tokens_exceeded	State too large. Details
422	List of fields with “Field required”	Missing model, questions or a Choice’s criteria. Details

TypeSafe also documents 429 for rate limits and 529 when the service is overloaded. The errors index covers all of them, including the ones you only see on Vercel and OpenRouter.