The Jev API accepts a state and a map of typed questions, then returns answers under the same question names. This guide uses a small urgency check so you can inspect one decision before adding it to an application. The request follows the official API shape; it has not been live-tested with a site-owned API key.

1. Get access and keep the key private

Open the official Playground to try a question in the browser, or sign in to the official console and obtain an API key. Confirm that your account has model access and check its billing terms. Store TYPESAFE_API_KEY in your shell environment or a server-side secret manager. Never paste a real key into a public webpage, repository, or browser bundle.

Official access links: Playground · API keys

2. Send a small request

The following cURL example uses an environment variable for authentication and pins jev-1.13.0 for a reproducible model identifier. The example state and instructions stay in English across this site’s translations. Model accuracy in other languages needs separate evaluation. The command makes a real, potentially billable request when you run it with your own key.

curl --fail-with-body --max-time 30 \
  https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "model": "jev-1.13.0",
  "state": "Our payment integration has failed for three days. Please help ASAP.",
  "questions": {
    "urgency": {
      "type": "noul",
      "instructions": "Does this message express urgency?"
    }
  }
}
JSON

3. Read the answer

Find answers.urgency.noul in the response. Noul is the probability that the answer to the yes/no question is yes, not a text label. The model field tells you which version answered. usage.input_tokens is useful for cost measurement. The response fragment below is illustrative, not a captured API response; your value can differ.

Illustrative response fragment:

{
  "model": "jev-1.13.0",
  "answers": {
    "urgency": {
      "type": "noul",
      "noul": 0.94
    }
  }
}

4. Choose what your program should do

Validate the response type and numeric range before using it. An illustrative rule might flag probabilities of 0.8 or greater for an urgent queue, with other cases following a normal or review path. The threshold is not an official safe default: choose it from labelled examples and the cost of false positives and false negatives. Never let model output bypass access control.

5. Add Choice or Score when needed

For team routing, use Choice with explicit criteria for billing, technical, sales, and a fallback. For an ordered assessment, use Score with descriptions for each level. Choice and Score provide confidence and a probability distribution. Noul returns a yes-probability; do not assume it has the same confidence field.

6. Handle errors and changes

For authentication failures, verify the header, key, and access. For a bad request, inspect the JSON and official schema. For 429 responses, respect retry-after when present and use bounded backoff; the official SDKs already provide retry behavior. Set timeouts for network calls, keep side effects idempotent, and treat missing or invalid answers as review cases. Re-evaluate thresholds before changing the pinned model.

Continue reading

Overview · Use cases · Pricing · Limitations

Sources & further reading