Jev API Reference: Endpoint, Request Body & Response Shapes

A compact reference for the Jev System One API. For the concepts behind each field, see the linked concept pages; this page is the shape-of-the-wire version.

Verification note. Endpoint, auth, body fields, primitive types, limits, and SDK names are cross-verified across two independent community documentation projects. Exact response envelope key names follow community documentation — confirm against the official API reference at jev.com before writing brittle parsers.

#Endpoint

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <TYPESAFE_API_KEY>
Content-Type: application/json

API keys are created at console.typesafe.ai → Settings → Keys.

#Request body

Three fields:

{
  "model": "jev-1.13.0",
  "state": { "...": "the record to judge" },
  "questions": { "<your_key>": { "type": "noul|choice|score", "...": "..." } }
}

Every question object requires instructions (what to judge) and accepts optional criteria (tie-breakers, edge-case policy).

#Noul — yes/no → probability

Request:

"is_spam": {
  "type": "noul",
  "instructions": "Answer yes if this review is spam or fake engagement.",
  "criteria": "Short negative reviews from verified purchases are not spam."
}

Response shape:

{ "answers": { "is_spam": { "type": "noul", "probability": 0.91 } } }

One probability in [0, 1]. No confidence field — Noul's probability carries the whole signal.

#Choice — one of N

Request:

"route": {
  "type": "choice",
  "instructions": "Pick the team that should own this ticket.",
  "options": ["billing", "technical", "account", "sales"]
}

Response shape:

{
  "answers": {
    "route": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.78, "technical": 0.15, "account": 0.05, "sales": 0.02 },
      "confidence": 0.86
    }
  }
}

Limit: ≤ 255 options per question. Over that, bucket hierarchically (Cascade Routing).

#Score — rating on a 2–10 level scale

Request:

"quality": {
  "type": "score",
  "instructions": "Rate this article draft's overall quality.",
  "criteria": "5 = publishable with light edits; 8+ = publish as-is.",
  "scale": 10
}

Response shape:

{
  "answers": {
    "quality": {
      "type": "score",
      "score": 7,
      "legend": { "1": "unusable", "5": "publishable with light edits", "10": "exceptional" },
      "probabilities": { "6": 0.2, "7": 0.45, "8": 0.25, "...": "..." },
      "confidence": 0.81
    }
  }
}

Scale size is your choice, 2 to 10 levels. The legend echoes back what each level means; probabilities give the distribution over levels.

#Multiple questions per request

The questions map takes many entries, and primitives can be mixed freely in one call — one HTTP request, one state transmitted, N verdicts back. This is the single most important cost optimization; see Speculative Fan-Out.

#Errors & rate limits

• Limits: 250k tokens/sec and 1200 requests/min, officially subject to dynamic adjustment during early access.
• On 429, respect the Retry-After header and back off. Both official SDKs do this automatically.
• Latency: 70–500 ms typical (launch-blog figures, no SLA).

#SDKs

pip install typesafe-sdk        # Python 3.10+
npm install @typesafe-ai/sdk    # Node.js 20+

Both wrap the endpoint above, read TYPESAFE_API_KEY from the environment, and handle 429 backoff. Exact method names are in each package's README.

#Where to go next

• Getting Started — the same material as a walkthrough
• The Three Primitives — choosing between noul/choice/score
• Glossary — every term on one page

#Sources

• jevai.wiki — API reference (community documentation).
• learnjev.com — Getting started (community documentation).
• jev101.com — 什么是 Jev（中文） (community documentation, Chinese).

Unofficial fan-made handbook. Not affiliated with TypeSafe AI or jev.com.