Jev API

The Jev API is the TypeSafe System One evaluation API. This page is an independent map of the official contract, plus notes on how to operate it. It is not a mirror of TypeSafe's reference.

Authentication

Authorization: Bearer $TYPESAFE_API_KEY
Content-Type: application/json

Create the key in TypeSafe's console. Rotate it if it leaks. SDKs read TYPESAFE_API_KEY by default.

Evaluation endpoint

POST https://api.typesafe.ai/v1/systemone

Request fields

Question IDs are for your code. Official docs say they are not sent to the underlying model.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?"
    },
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    }
  }
}

instructions may be a string, object, or array. Structured instructions let you keep referenced data next to the question.

Choice criteria

Map of option → description or null. Official maximum: 255 options.

Score criteria

Ordered array of level descriptions. Official bounds: 2 to 10 levels.

Noul criteria

Optional { "true": "...", "false": "..." }.

Response

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": { "type": "noul", "noul": 0.95 },
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
      "confidence": 0.81
    },
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
      "confidence": 0.92
    }
  },
  "usage": { "input_tokens": 318, "output_tokens": 34 }
}

Always persist model and usage.input_tokens. You will need them when an alias moves or a bill looks surprising.

List models

curl https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

Official docs: the list currently returns aliases. Versioned IDs such as jev-1.13.0 and jev-1.14.0 still work in model even when absent from the list.

When last verified on 2026-10-16:

Errors

Official SDKs retry with backoff by default.

Rate limits last verified

When last verified on 2026-10-16, the public models page directs you to the TypeSafe developer console for your organization's current token-per-second and request-per-second limits. A request over either limit returns 429.

Context limits

Default limits (both jev-1.13.0 and jev-1.14.0):

• 64k tokens: state + all questions
• 32k tokens: state + longest single question

See How Jev works for why both exist.

Long context (optional)

Long context is off by default. To raise both limits to 262k tokens, send this header on requests that need it:

TypeSafe-Danger-Zone-Long-Context: true

Example:

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "TypeSafe-Danger-Zone-Long-Context: true" \
  -d '{"model":"jev-latest","state":"…","questions":{…}}'

When to call the HTTP API

Use raw HTTP from languages without an official SDK, from CI probes, or when you want to see the exact JSON.

Prefer the Python or TypeScript SDK in application code so retries and types are not your problem.

When not to

Do not expose your TypeSafe key in a browser. Put Jev behind your own backend.

Common mistakes

• Sending questions as an array instead of an object keyed by IDs.
• Forgetting type on a question.
• Retrying 422 (that will never start working).
• Treating 529 like a bug in your payload.

Language-specific copies: cURL, Python, TypeScript. Costs: pricing.

Experimental images and Box

Jev 1.13 and 1.14 accept images with TypeSafe-Danger-Zone-Images: true. Box localization requires Jev 1.14 and the same header. These features are experimental, not production-ready. The text examples above remain useful without enabling images. See Images, Box, and model and SDK migration.