Jev API Reference & Practical Guide

Authentication, state, typed questions, response fields, curl examples, rate limits, and version pinning.

Endpoint and authentication

Send POST https://api.typesafe.ai/v1/systemone with Content-Type: application/json and Authorization: Bearer $TYPESAFE_API_KEY. Create a key in the TypeSafe console. Load it from your environment; do not include it in a browser bundle or commit it.

Request body

Field	Type	Purpose
`state`	string, object, or array	Facts and context to evaluate
`model`	string	An alias or pinned model
`questions`	object	Named, independently evaluated judgments

All questions use instructions (plural). Choice uses a criteria map, not an options array. Score uses an ordered criteria array, not an integer levels field. Noul criteria are optional descriptions of true and false.

Choice, Score, and Noul request

Save this as request.json. It is the same support-ticket example used throughout the manual.

{
  "model": "jev-1.13.0",
  "state": {
    "ticket": {
      "subject": "Duplicate subscription charge",
      "message": "I was charged twice this month. Please refund the duplicate before Friday."
    },
    "customer_plan": "pro"
  },
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this ticket?",
      "criteria": {
        "billing": "Payments, invoices, and refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "New purchases and upgrades",
        "other": "No listed department fits"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is the request?",
      "criteria": [
        "No time constraint",
        "Can wait this week",
        "Needs attention within a day",
        "Immediate outage or harm"
      ]
    },
    "refund_requested": {
      "type": "noul",
      "instructions": "Does the customer explicitly request a refund?"
    }
  }
}

Run a curl request

curl --fail-with-body https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

The complete request file can also be downloaded. Run it from a terminal with the environment variable set. A live request uses your TypeSafe account and is billed under your plan.

Response body

model reports the actual version that answered. answers uses the same question keys you sent. usage.input_tokens and usage.output_tokens describe accounting. The output token count can be nonzero even though direct output is free.

Answer	Main field	Additional fields
Choice	`choice`	`probabilities`, `confidence`, `type`
Score	`score`	`legend`, `probabilities`, `confidence`, `type`
Noul	`noul`	`type`

A Score’s raw level indices start at zero in the documented HTTP response. Use its returned legend to interpret values. Do not silently assume a one-to-five scale.

Python and JavaScript

The Python guide uses TypeSafeClient.system_one(). The JavaScript guide uses TypeSafeClient.systemOne(). Both include a complete program for this ticket. These methods have different names; copying the Python method name into JavaScript will fail.

Errors and rate limits

A 401 usually means invalid credentials. A 422 means the body failed validation. A 429 means a request or token limit was exceeded. TypeSafe also documents 529 for temporary overload. Retry transient failures with a bounded backoff; do not retry invalid credentials or a malformed request unchanged.

The current direct rate limits are 1200 requests/minute and 250000 tokens/second. They can change. Read the error guide for provider-specific diagnosis.

Pinning and production logging

Use jev-1.13.0 when your evaluation and thresholds depend on that version. Aliases may move. Log model, question-schema revision, latency, usage, outcome, and review result. Avoid logging full sensitive state or authorization headers.