API guide
Jev API guide: endpoint, fields, examples and errors
How to call the Jev API: endpoint and key, request and response fields, all four question types, limits, aliases, errors, and curl, Python and JavaScript code.
The Jev API does its work at one endpoint: POST https://api.typesafe.ai/v1/systemone. You send a state (the content), named questions and a model name, and the Jev API returns one typed answer per question plus token usage. This reference follows TypeSafe's OpenAPI spec, version 0.2.0, as published on October 22, 2026. TheJevAI is independent of TypeSafe AI and has no API key, so every Jev API response below is written from the documented schema, not copied from a live call.
Jev API endpoint and authentication
The Jev API base URL is https://api.typesafe.ai. POST /v1/systemone answers questions, and GET /v1/models lists the model names your account can send. Both need a Jev API key from the TypeSafe console (console.typesafe.ai/keys), sent as Authorization: Bearer followed by the key. Our examples keep it in TYPESAFE_API_KEY, as TypeSafe's do.
Bodies are JSON (Content-Type: application/json); image requests may use multipart/form-data. GET /v1/models currently returns the aliases, and versioned IDs such as jev-1.14.0 work even though they are not listed.
Jev API request: curl https://api.typesafe.ai/v1/models -H "Authorization: Bearer $TYPESAFE_API_KEY" Jev API response (example shape from the OpenAPI spec): { "models": [ { "name": "jev-latest", "description": "General-purpose system one model.", "release_date": "2026-09-15" } ] }
Jev API request fields
| Jev API field | Required | What it holds |
|---|---|---|
| model | Yes | A model ID or alias, such as jev-1.14.0 or jev-latest |
| state | Yes | The content every question is about: a string, an object or an array |
| questions | Yes | Named questions, at least one, each with a type and usually instructions and criteria |
| assets | No | Images keyed by a reference string; needs the TypeSafe-Danger-Zone-Images: true header |
You choose the question names, and the Jev API uses them as keys in the answers object. The names never reach the model, so write the whole question in instructions. A question can point at part of the state by a path in backticks, such as ticket.messages[0].text.
The four Jev API question types
| Jev API type | Use it for | criteria | Answer fields |
|---|---|---|---|
| noul | Is this true? | Optional: what true and false mean | noul (probability of yes) |
| choice | Pick one option from a list | Required: 1 to 255 named options | choice, confidence, probabilities |
| score | Rate on an ordered scale | Required: 1 to 10 levels, two or more advised | score, confidence, legend, probabilities |
| box | Find one thing in an image | None | box edges from 0 to 1, confidence |
One Jev API request can mix all four types; each question is judged on its own against the same state. Confidence runs from 0 (probability spread evenly) to 1 (all on one answer), and a noul needs none because its probability already shows how sure the model is. Box needs an image, the images header and Jev 1.14.
Jev API example: noul
The numbers in this and the next three Jev API responses are illustrative: they follow the documented schema but did not come from a real call. A Jev API noul answer is the probability of yes.
Jev API request body: { "model": "jev-1.14.0", "state": "I was charged twice for order A-1042. Please refund one charge.", "questions": { "wants_refund": { "type": "noul", "instructions": "Does the customer ask for a refund?" } } } Jev API response (illustrative values): { "model": "jev-1.14.0", "answers": { "wants_refund": { "type": "noul", "noul": 0.97 } }, "usage": { "input_tokens": 52, "output_tokens": 4 } }
Jev API example: choice
In a Jev API choice answer, choice is the most likely option, probabilities covers every option and sums to about 1, and confidence summarizes how peaked that spread is.
Jev API request body: { "model": "jev-1.14.0", "state": "The CSV export shows an error page since yesterday. We need the report tomorrow.", "questions": { "team": { "type": "choice", "instructions": "Which team should handle this ticket?", "criteria": { "billing": "Payments and refunds", "technical": "Bugs and errors", "sales": "Plans and pricing" } } } } Jev API response (illustrative values): { "model": "jev-1.14.0", "answers": { "team": { "type": "choice", "choice": "technical", "confidence": 0.91, "probabilities": { "billing": 0.02, "technical": 0.94, "sales": 0.04 } } }, "usage": { "input_tokens": 70, "output_tokens": 9 } }
Jev API example: score
Jev API score levels are numbered from 0 in the order you list them. The score is the probability-weighted average of the level numbers, so 1.65 sits between This week and Today. Read probabilities too, because different spreads can give the same average.
Jev API request body: { "model": "jev-1.14.0", "state": "The CSV export shows an error page since yesterday. We need the report tomorrow.", "questions": { "urgency": { "type": "score", "instructions": "How urgent is this ticket?", "criteria": ["Can wait", "This week", "Today"] } } } Jev API response (illustrative values): { "model": "jev-1.14.0", "answers": { "urgency": { "type": "score", "score": 1.65, "confidence": 0.48, "legend": { "0": "Can wait", "1": "This week", "2": "Today" }, "probabilities": { "0": 0.05, "1": 0.25, "2": 0.7 } } }, "usage": { "input_tokens": 58, "output_tokens": 10 } }
Jev API example: box
A box question needs the TypeSafe-Danger-Zone-Images: true header and jev-1.14.0 or jev-preview. Edges are fractions of the image size from the top-left corner. A box answer always has four edges, even when the object is missing, so this Jev API request also asks a noul to check that the mug is there.
Jev API request body (sent with TypeSafe-Danger-Zone-Images: true): { "model": "jev-1.14.0", "state": { "photo": "3f6c1e2a-shelf" }, "assets": { "3f6c1e2a-shelf": { "type": "image", "format": "jpg", "data_base64": "<base64 JPEG>" } }, "questions": { "mug_visible": { "type": "noul", "instructions": "Is there a coffee mug in `photo`?" }, "mug": { "type": "box", "instructions": "the coffee mug in `photo`" } } } Jev API response (illustrative values): { "model": "jev-1.14.0", "answers": { "mug_visible": { "type": "noul", "noul": 0.95 }, "mug": { "type": "box", "box": { "top": 0.31, "bottom": 0.74, "left": 0.52, "right": 0.81 }, "confidence": 0.88 } }, "usage": { "input_tokens": 300, "output_tokens": 25 } }
Jev API call with curl
This Jev API call sends one state with two questions; set TYPESAFE_API_KEY in your shell first. Two questions in one request cost less than two separate calls, because the state is billed once. Keep the full question in instructions, since question names are never sent to the model.
curl https://api.typesafe.ai/v1/systemone -H "Authorization: Bearer $TYPESAFE_API_KEY" -H "Content-Type: application/json" -d '{ "model": "jev-1.14.0", "state": "I was charged twice for order A-1042. Please refund one charge.", "questions": { "wants_refund": { "type": "noul", "instructions": "Does the customer ask for a refund?" }, "team": { "type": "choice", "instructions": "Which team should handle this?", "criteria": { "billing": "Payments", "technical": "Bugs", "sales": "Plans" } } } }'
Jev API call with Python
Plain HTTP with requests is enough to call the Jev API. TypeSafe also ships an official SDK (pip install typesafe-sdk) with typed Noul, Choice and Score classes that reads TYPESAFE_API_KEY and retries rate limits; the plain version below does not retry.
# Jev API call with requests (pip install requests) import os import requests resp = requests.post( "https://api.typesafe.ai/v1/systemone", headers={"Authorization": f"Bearer {os.environ['TYPESAFE_API_KEY']}"}, json={ "model": "jev-1.14.0", "state": "I was charged twice for order A-1042. Please refund one charge.", "questions": {"wants_refund": {"type": "noul", "instructions": "Does the customer ask for a refund?"}}, }, timeout=10, ) resp.raise_for_status() data = resp.json() print(data["model"], data["answers"]["wants_refund"]["noul"], data["usage"])
Jev API call with JavaScript
The same Jev API call with the built-in fetch, for Node.js 18 or newer in an .mjs file. The official package is @typesafe-ai/sdk on npm; it infers answer types from your questions and retries 429 and 529 responses.
const res = await fetch("https://api.typesafe.ai/v1/systemone", { method: "POST", headers: { Authorization: `Bearer ${process.env.TYPESAFE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "jev-1.14.0", state: "I was charged twice for order A-1042. Please refund one charge.", questions: { wants_refund: { type: "noul", instructions: "Does the customer ask for a refund?" } }, }), }); if (!res.ok) throw new Error(`Jev API error ${res.status}: ${await res.text()}`); const data = await res.json(); console.log(data.model, data.answers.wants_refund.noul, data.usage);
Jev API models and aliases
| Jev API model name | Kind | Points to | Notes |
|---|---|---|---|
| jev-1.14.0 | Model ID | Jev 1.14 | Released October 14, 2026; required for box |
| jev-1.13.0 | Model ID | Jev 1.13 | The September 2026 launch version; stays available for a while |
| jev-latest | Alias | jev-1.14.0 (Models page, October 25, 2026) | Default in the official SDKs |
| jev-preview | Alias | jev-1.14.0 | Newest release, official or not |
The Models page, read on October 25, 2026, lists both jev-latest and jev-preview as pointing to jev-1.14.0, as the October 14 post said it would. Aliases can move again, and every Jev API response names the versioned model that answered. If you tuned thresholds on one version, send its ID instead of an alias. TypeSafe plans 60 days of notice before retiring jev-1.13.0 and 30 days for jev-1.14.0.
Jev API limits
- Context: by default a Jev API request may use 64k tokens in total (state plus all questions) and 32k for the state plus any one question.
- Long context: TypeSafe-Danger-Zone-Long-Context: true raises both limits to 262k tokens at the same price; TypeSafe says it is slower and less accurate.
- Questions: no fixed number, as long as the request fits.
- Body: the Jev API accepts up to 32 MiB of UTF-8 JSON without a byte order mark, 64 levels of nesting and finite numbers; gzip or zstd compression is allowed.
- Rate limits: Jev API limits are set per organization, in tokens and requests per second, and shown in the console.
- Speed: TypeSafe's launch post claims 70 to 500 ms end to end; its published speed tests ran from the US West Coast.
- Language: English is the main training language; other languages work with lower accuracy.
Jev API errors and fixes
| Jev API status | Meaning | What to do |
|---|---|---|
| 400 | A request rule is broken, or max_tokens_exceeded | Fix the body, or shrink the state |
| 401 | Missing or invalid key | Check the Authorization: Bearer header |
| 413 | Body over 32 MiB | Send less, or send images as multipart files |
| 415 | Unsupported or stacked Content-Encoding | Use gzip or zstd once |
| 422 | Validation failed, such as a missing field | Read detail[].loc to find the field |
| 429 | Rate limit reached | Back off exponentially and honor retry-after |
| 529 | TypeSafe is overloaded | Retry after a short delay with backoff |
Jev API 422 body (the example in the OpenAPI spec): { "detail": [ { "loc": ["body", "state"], "msg": "Field required", "type": "missing" } ] }
The official SDKs retry 429 and 529 with backoff; for plain Jev API calls, write that loop yourself.
The Jev API through third-party gateways
OpenRouter serves Jev with an OpenRouter key and no TypeSafe account, through its Decisions API (POST https://openrouter.ai/api/alpha/decisions) or a System One endpoint (POST https://openrouter.ai/api/v1/systemone) for TypeSafe's SDKs. Models there are typesafe/jev-1.14 and typesafe/jev-1.13, and ~typesafe/jev-latest tracks the newest release, while the Jev API's own jev-latest is defined as the most recent stable release.
Vercel AI Gateway accepts TypeSafe SDK clients at https://ai-gateway.vercel.sh/typesafe and has its own API at POST https://ai-gateway.vercel.sh/v1/evaluate with typesafe-ai/jev. Its examples call the yes/no type boolean, not noul, so a Jev API body needs edits there.
Build your first Jev API request
The request builder on our home page assembles a Jev API request in your browser. It runs only on your side and never calls Jev; you run the code it produces with your own key.
Sources
All pages accessed on October 22, 2026. The OpenAPI spec is the reference for Jev API field names.