Jev API in Five Minutes

Step 1 — Get a Jev AI API key

Sign in at console.typesafe.ai/keys and create an API key. Store it as an environment variable (TYPESAFE_API_KEY) on the server side — never in frontend code, where anyone can read it.

Step 2 — Send a Jev AI API request

One POST per decision, JSON in, JSON out:

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{
  "state": "Order #A-2291: predicted delivery 18:40. Driver marked 'delivered' at 18:52 at a GPS point 0.4 km from the customer address. Customer chat: 'nothing has arrived.'",
  "model": "jev-latest",
  "questions": {
    "possibly_failed": {
      "type": "noul",
      "instructions": "Does this order look like a failed or wrong-address delivery?"
    }
  }
}
EOF

The body has three fields:

Step 3 — The three Jev AI API question types

Choice — pick from your options (hotel-review routing)

{
  "state": "Hotel review: 'Loved the room and the breakfast spread. But check-in took forty minutes and the front desk seemed overwhelmed.'",
  "model": "jev-latest",
  "questions": {
    "route_review": {
      "type": "choice",
      "instructions": "Which department should act on this review first?",
      "criteria": {
        "front_desk": "check-in, checkout, desk staff, waiting times",
        "housekeeping": "room cleanliness and supplies",
        "food_and_beverage": "breakfast, restaurant, room service",
        "management": "escalations, compensation, repeat complaints"
      }
    }
  }
}

Response — a winner, a probability per option, and a confidence:

{
  "model": "jev-1.13.0",
  "answers": {
    "route_review": {
      "choice": "front_desk",
      "probabilities": {
        "front_desk": 0.78,
        "food_and_beverage": 0.09,
        "management": 0.08,
        "housekeeping": 0.05
      },
      "confidence": 0.81
    }
  },
  "usage": {
    "input_tokens": 96,
    "output_tokens": 0
  }
}

Score — grade against your rubric (guest-feedback positivity)

{
  "state": "Guest feedback: 'Room was spotless and the location is perfect, but the AC rattled all night and nobody answered the front desk phone.'",
  "model": "jev-latest",
  "questions": {
    "positivity": {
      "type": "score",
      "instructions": "Rate how positive this guest feedback is overall.",
      "criteria": {
        "0": "negative",
        "1": "mixed",
        "2": "positive"
      }
    }
  }
}

Response — a score on your scale, a distribution over the levels, and the legend echoed back:

{
  "model": "jev-1.13.0",
  "answers": {
    "positivity": {
      "score": 1.2,
      "probabilities": {
        "0": 0.18,
        "1": 0.62,
        "2": 0.2
      },
      "confidence": 0.74,
      "legend": {
        "0": "negative",
        "1": "mixed",
        "2": "positive"
      }
    }
  },
  "usage": {
    "input_tokens": 88,
    "output_tokens": 0
  }
}

Noul — a yes/no probability (delivery-anomaly check)

{
  "state": "Order #A-2291: predicted delivery 18:40. Driver marked 'delivered' at 18:52 at a GPS point 0.4 km from the customer address. Customer chat: 'nothing has arrived.'",
  "model": "jev-latest",
  "questions": {
    "possibly_failed": {
      "type": "noul",
      "instructions": "Does this order look like a failed or wrong-address delivery?"
    }
  }
}

Response — just noul, a 0–1 probability. Note there is no separate confidence field on Noul answers; threshold the value itself in your code.

{
  "model": "jev-1.13.0",
  "answers": {
    "possibly_failed": {
      "noul": 0.93
    }
  },
  "usage": {
    "input_tokens": 74,
    "output_tokens": 0
  }
}

All three at once

Questions in one request are evaluated against the same state in parallel, independently — extra questions add almost no latency:

{
  "state": "Hotel review: 'Loved the room and the breakfast spread. But check-in took forty minutes and the front desk seemed overwhelmed.'",
  "model": "jev-latest",
  "questions": {
    "route_review": {
      "type": "choice",
      "instructions": "Which department should act on this review first?",
      "criteria": {
        "front_desk": "check-in, checkout, desk staff, waiting times",
        "housekeeping": "room cleanliness and supplies",
        "food_and_beverage": "breakfast, restaurant, room service",
        "management": "escalations, compensation, repeat complaints"
      }
    },
    "mentions_wait": {
      "type": "noul",
      "instructions": "Does this review complain about waiting?"
    },
    "positivity": {
      "type": "score",
      "instructions": "Rate how positive this review is overall.",
      "criteria": {
        "0": "negative",
        "1": "mixed",
        "2": "positive"
      }
    }
  }
}

{
  "model": "jev-1.13.0",
  "answers": {
    "route_review": {
      "choice": "front_desk",
      "probabilities": {
        "front_desk": 0.78,
        "food_and_beverage": 0.09,
        "management": 0.08,
        "housekeeping": 0.05
      },
      "confidence": 0.81
    },
    "mentions_wait": {
      "noul": 0.91
    },
    "positivity": {
      "score": 1.1,
      "probabilities": {
        "0": 0.2,
        "1": 0.66,
        "2": 0.14
      },
      "confidence": 0.72,
      "legend": {
        "0": "negative",
        "1": "mixed",
        "2": "positive"
      }
    }
  },
  "usage": {
    "input_tokens": 172,
    "output_tokens": 0
  }
}

Reading a Jev AI API response

Three top-level fields: model, answers (keyed by your question ids), and usage. The model field reports the actual version that answered (e.g. jev-1.13.0) — worth logging, because the jev-latest alias moves as new versions ship. If you calibrated a confidence threshold against one version, pin the version string instead of relying on the alias.

Python quickstart for the Jev AI API

The official SDK (typesafe-sdk, Python ≥ 3.10) reads TYPESAFE_API_KEY from the environment automatically. A JavaScript SDK is also available as @typesafe-ai/sdk:

# pip install typesafe-sdk   (or: uv add typesafe-sdk) — Python 3.10+
from typesafe import TypeSafe

client = TypeSafe()  # picks up TYPESAFE_API_KEY from the environment

decision = client.systemone.run(
    state="Order #A-2291: marked delivered 0.4 km from the address; customer says nothing arrived.",
    model="jev-latest",
    questions={
        "possibly_failed": {
            "type": "noul",
            "instructions": "Does this order look like a failed delivery?",
        }
    },
)

answer = decision.answers["possibly_failed"]
print(f"failure probability: {answer.noul:.2f}")

Jev AI API rate limits and 429 handling

Limits: 100K tokens/sec and 80 requests/sec. Cross one and the API returns HTTP 429 with a retry-after header. The official SDKs back off and respect retry-after by default. If you call the HTTP API directly, do the same: honor retry-after, use exponential backoff with jitter, and never tight-loop a retry.

What the Jev AI API is not good at

Worth knowing before you ship: Jev’s accuracy drops on arithmetic, counting, date comparison, indirectly-phrased questions, and states full of distracting details. Three rules of thumb: keep exact calculations in your code, ask questions directly, and treat low confidence as a signal to hand off to a human — not as a conclusion to act on.

Building with an AI coding assistant? There is an official skill for wiring up this API: npx skills add typesafe-ai/skills --skill typesafe-ai