Jev API tutorial: make your first request

1. Get a key and keep it server-side

Create the API key in the TypeSafe console and store it in TYPESAFE_API_KEY. Never put the key in browser JavaScript, a public repository, a screenshot, or the state that the model evaluates.

export TYPESAFE_API_KEY="your-api-key"

2. Send the smallest complete request

A request needs a model, the evidence to inspect in state, and named questions. Begin with one bounded Choice so that both the input contract and the returned answer are easy to verify.

curl -X POST https://api.typesafe.ai/v1/systemone   -H "Authorization: Bearer $TYPESAFE_API_KEY"   -H "Content-Type: application/json"   -d @- <<'EOF'
{
  "model": "jev-latest",
  "state": {
    "message": "Checkout returns HTTP 500 after payment."
  },
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which team should handle this request?",
      "criteria": {
        "billing": "Charges, invoices, or subscriptions",
        "technical": "Bugs, APIs, or integrations",
        "human": "Ambiguous or sensitive cases"
      }
    }
  }
}
EOF

3. Read the typed response

The answer is stored under the question ID you supplied. Choice returns the selected option, a probability for every option, and confidence. Score returns a position on your ordered rubric. Noul returns P(true) and has no separate confidence field.

{
  "model": "jev-1.13.0",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "technical",
      "confidence": 0.78,
      "probabilities": {
        "technical": 0.85,
        "billing": 0.10,
        "human": 0.05
      }
    }
  }
}

4. Turn the answer into a safe decision path

Validate the answer shape and option keys before branching. Keep side effects in ordinary code, use stricter gates for high-impact actions, and distinguish transport failure from a valid but uncertain model result.

const allowed = new Set(['billing', 'technical', 'human']);
const route = response.answers?.route;

if (!route || !allowed.has(route.choice)) throw new Error('Invalid response');
if (route.confidence < REVIEW_THRESHOLD) return enqueueHumanReview(route);
return suggestRoute(route.choice); // keep irreversible actions behind confirmation

5. Add more questions without hiding policy

Questions against the same state can be sent together and are evaluated independently. Split compound judgments into focused questions, then combine their answers with visible, versioned business rules in code.