Hosted API reference

The Jev Decision API, hosted. Send a state and typed questions, get back calibrated answers — billed per input token against a prepaid balance, no TypeSafe waitlist. The request and response match the official Jev API, so anything you build here works the same way against TypeSafe directly.

Base URL

POST https://jevtypesafeai.com/api/v1/decide

Authentication

Send your key as a Bearer token. Create one on the pricing page (sign in, prepay a small balance) — keys look like jv_live_…. Keep the key in an environment variable; never commit it or expose it in client-side code.

Authorization: Bearer jv_live_your_key_here
Content-Type: application/json

Request body

model — jev-latest, or a pinned version like jev-1.13.0. Optional; defaults to jev-latest.
state — the input to evaluate: a string, object, or array. Required.
questions — a map of your question names to typed questions. Required. Each is a choice, score, or noul. They are evaluated in parallel in one round trip.

The three question types

Every question is exactly one of these. You can mix any number of them in a single call.

choice — pick one option

Give a criteria map of up to 255 labelled options ({ key: "what this option means" }; a value may be null for a label with no description). Jev returns the winning choice key, a probability for every option, and a confidence.

"route": {
  "type": "choice",
  "instructions": "Where should this ticket go?",
  "criteria": {
    "billing": "payments, refunds, invoices",
    "bug": "the product is broken",
    "account": "login or access"
  }
}
// → { "type":"choice", "choice":"billing", "confidence":0.99,
//     "probabilities": { "billing":0.99, "bug":0.0, "account":0.01 } }

score — rate on an ordered scale

Give an ordered criteria array of 2–10 level descriptions, low to high. Describe each level concretely (a situation, not just "medium"). Jev returns a (possibly fractional) score, the full probabilities per level, a legend, and a confidence.

"urgency": {
  "type": "score",
  "instructions": "How urgent is this message?",
  "criteria": [
    "routine, no rush",
    "should be handled today",
    "urgent, customer is frustrated",
    "critical, about to churn"
  ]
}
// → { "type":"score", "score":2.97, "confidence":1.0,
//     "probabilities": { "0":0.0, "3":1.0 } }

noul — a calibrated yes/no

No criteria needed — just instructions. Jev returns noul, a calibrated probability from 0 to 1 that the answer is "yes". You may optionally pass criteria: { "true": "...", "false": "..." } to spell out what a yes and a no mean. Ideal for gates and guardrails.

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

Tip: state may be a string, a JSON object, or an array of text — send the context the decision needs and nothing more. Up to ~64k tokens for the state plus all questions combined.

Example request

curl

curl https://jevtypesafeai.com/api/v1/decide \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route":    { "type": "choice", "instructions": "Where should this go?",
                    "criteria": { "billing": "money", "bug": "broken", "account": "login" } },
      "urgency":  { "type": "score",  "instructions": "How urgent is this?",
                    "criteria": ["routine", "today", "urgent", "critical"] },
      "escalate": { "type": "noul",   "instructions": "Escalate to a human now?" }
    }
  }'

Python

import os, requests

r = requests.post(
    "https://jevtypesafeai.com/api/v1/decide",
    headers={"Authorization": f"Bearer {os.environ['JEV_API_KEY']}"},
    json={
        "state": "Customer: I was charged twice...",
        "questions": {
            "escalate": {"type": "noul", "instructions": "Escalate to a human now?"}
        },
    },
    timeout=30,
)
data = r.json()
print(data["answers"]["escalate"]["noul"])  # 0.0 - 1.0

JavaScript / TypeScript

const res = await fetch("https://jevtypesafeai.com/api/v1/decide", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.JEV_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    state: "Customer: I was charged twice...",
    questions: {
      escalate: { type: "noul", instructions: "Escalate to a human now?" },
    },
  }),
});
const data = await res.json();
if (data.answers.escalate.noul > 0.7) handoffToHuman();

Response

You get back the resolved model, an answers map keyed to your questions, and a usage block with the token count, this call's cost, and your remaining balance:

{
  "model": "jev-1.13.0",
  "answers": {
    "route":    { "type": "choice", "choice": "billing", "confidence": 0.99,
                  "probabilities": { "billing": 0.99, "bug": 0.0, "account": 0.01 } },
    "urgency":  { "type": "score", "score": 3.0, "probabilities": { "0": 0.0, "3": 1.0 } },
    "escalate": { "type": "noul", "noul": 0.94 }
  },
  "usage": {
    "input_tokens": 62,
    "output_tokens": 0,
    "cost_usd": 0.000026,
    "credits_remaining_usd": 4.999974
  }
}

Because every answer's type is fixed by your request, you branch on the results in plain code — no parsing, no regex, and no risk of a malformed response.

Billing

You prepay a balance; each call deducts the cost of its input_tokens.
$0.42 per million input tokens. Output tokens are free.
Every response reports cost_usd for the call and credits_remaining_usd for your balance.
Credits never expire. Top up any time on the pricing page.
Want raw at-cost pricing ($0.042/M) and full quotas? Go direct via console.typesafe.ai — this hosted API is a managed convenience layer over it.

Errors

400 — the request body failed validation (bad state or questions). The error field says what.
401 — missing, invalid, or revoked API key.
402 — insufficient credits. Top up to continue (code: "insufficient_credits").
403 — the account is inactive.
502 — an upstream error from the Jev model; retry with backoff.

Limits & good practice

Batch several questions into one call — they run in parallel and share the state cost.
Trim the state to only what the decision needs; you pay per input token.
Pin a model version in production so calibrated thresholds don't shift under you.
Use confidence / probabilities to auto-handle easy cases and escalate the uncertain ones.
Keep your jv_live_ key server-side, in an environment variable.

jevtypesafeai.com is an independent site — not TypeSafe AI. This hosted endpoint proxies the official Jev API and bills per token. For the full model reference and SDKs, see docs.typesafe.ai.

Get an API key →▶ Try Jev free Agent skill