How to use the Jev API

Jev exposes a single endpoint. You send a state and a set of questions; it returns typed answers with probabilities. Here's everything you need to make your first call.

1. The endpoint

Every request is a POST to https://api.typesafe.ai/v1/systemone, authenticated with a Bearer token. Official SDKs read your key from the TYPESAFE_API_KEY environment variable.

curl

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Customer: I was charged twice and I am furious.",
    "questions": {
      "topic": {
        "type": "choice",
        "instructions": "What is the issue about?",
        "criteria": { "billing": "money problems", "bug": "broken product" }
      },
      "urgent": {
        "type": "noul",
        "instructions": "Escalate to a human now?"
      }
    }
  }'

2. The request body

Three fields:

model — jev-latest, or pin a version like jev-1.13.0 if you tune thresholds.
state — the context, as a string, JSON object, or array of text. Up to ~64k tokens combined with your questions.
questions — a map of question names to question objects. They're all evaluated in one round trip.

3. The three question types

choice — pick one option

Give a criteria map of up to 255 labelled options. Jev returns the winning key, a probability per option, and a confidence.

"topic": {
  "type": "choice",
  "instructions": "What is the primary issue?",
  "criteria": {
    "billing": "billing or payment problem",
    "bug": "the product is broken",
    "account": "login or access"
  }
}

score — position on a scale

Give an ordered criteria array of 2–10 level descriptions. Jev returns a (possibly fractional) score plus the full distribution.

"severity": {
  "type": "score",
  "instructions": "How urgent is this?",
  "criteria": [
    "routine",
    "handle today",
    "urgent",
    "critical, about to churn"
  ]
}

noul — calibrated yes/no

No criteria — just instructions. Jev returns noul, a probability from 0 to 1.

"escalate": {
  "type": "noul",
  "instructions": "Escalate to a human immediately?"
}

4. The response

You get back the resolved model, an answers map, and token usage:

{
  "model": "jev-1.13.0",
  "answers": {
    "topic":    { "type": "choice", "choice": "billing",
                  "confidence": 1.0,
                  "probabilities": { "billing": 1.0, "bug": 0.0, "account": 0.0 } },
    "severity": { "type": "score", "score": 3.0, "confidence": 1.0,
                  "legend": { "0": "routine", "3": "critical, about to churn" },
                  "probabilities": { "0": 0.0, "3": 1.0 } },
    "escalate": { "type": "noul", "noul": 0.8 }
  },
  "usage": { "input_tokens": 434, "output_tokens": 75 }
}

Because the types are fixed, you can branch on the results with plain code — if (answers.escalate.noul > 0.7) — with no parsing, no regex, and no risk of a malformed response.

5. Limits & good practices

Rate limits: 250,000 tokens/second and 1,200 requests/minute.
Context: up to 64k tokens for state + all questions; 32k for state + a single longest question.
Pin versions in production if your thresholds matter — jev-latest can shift behavior.
Batch questions into one call rather than many; they run in parallel and share the state cost.
Use confidence to auto-handle the easy cases and route only the uncertain ones to a human or a bigger model.

Want an easier way in?

Official Jev access is waitlisted. If you'd like a simpler, hosted way to call Jev — higher demo limits, ready-made endpoints, no waitlist — leave your email and tell us what you'd build. We're gauging demand before we build it.

Want to see it before you write any code? Every example on this page runs live in the playground. For official keys and full docs, see docs.typesafe.ai.

▶ Run it in the playground See pricing