Skip to content
Back to the guides

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.

TheJevAIPublished Updated 9 min read

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 request fields
Jev API fieldRequiredWhat it holds
modelYesA model ID or alias, such as jev-1.14.0 or jev-latest
stateYesThe content every question is about: a string, an object or an array
questionsYesNamed questions, at least one, each with a type and usually instructions and criteria
assetsNoImages 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

The four Jev API question types
Jev API typeUse it forcriteriaAnswer fields
noulIs this true?Optional: what true and false meannoul (probability of yes)
choicePick one option from a listRequired: 1 to 255 named optionschoice, confidence, probabilities
scoreRate on an ordered scaleRequired: 1 to 10 levels, two or more advisedscore, confidence, legend, probabilities
boxFind one thing in an imageNonebox 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 models and aliases
Jev API model nameKindPoints toNotes
jev-1.14.0Model IDJev 1.14Released October 14, 2026; required for box
jev-1.13.0Model IDJev 1.13The September 2026 launch version; stays available for a while
jev-latestAliasjev-1.14.0 (Models page, October 25, 2026)Default in the official SDKs
jev-previewAliasjev-1.14.0Newest 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 errors and fixes
Jev API statusMeaningWhat to do
400A request rule is broken, or max_tokens_exceededFix the body, or shrink the state
401Missing or invalid keyCheck the Authorization: Bearer header
413Body over 32 MiBSend less, or send images as multipart files
415Unsupported or stacked Content-EncodingUse gzip or zstd once
422Validation failed, such as a missing fieldRead detail[].loc to find the field
429Rate limit reachedBack off exponentially and honor retry-after
529TypeSafe is overloadedRetry 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.

Build a Jev AI request