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 still work in model even when absent from the list.

Errors

Official SDKs retry with backoff by default.

Rate limits last verified

From the official models page (2026-09-20):

• 250,000 tokens per second
• 1,200 requests per minute

Context limits

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

See How Jev works for why both exist.

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.