Jev API

What does the Jev API do?

The Jev API evaluates text against questions you define and returns typed decisions, without generating prose. I send the application state once, name the decisions I need, and read the results under those same names. This is TypeSafe’s System One interface: the output is a decision my code can use, rather than a paragraph I have to parse.

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <YOUR_TYPESAFE_API_KEY>
Content-Type: application/json

A Choice selects one of your labels. A Score rates the state against an ordered rubric. A Noul estimates whether a statement is true. None of these generates a support reply, an explanation, or a new document. See TypeSafe’s System One overview for the underlying model contract.

Which response fields should my code read?

The response envelope contains model, answers, and usage. The model reports the version that actually answered; the answers object preserves the question names you chose. Each answer’s type identifies how to interpret its value.

The definitions are in the official Choice, Score, and Noul references. A score of 2 on a three-level rubric means something different from 2 dollars, 2 hours, or a count of two incidents.

How do I call Jev with curl?

This Jev API example uses a synthetic support ticket about a broken checkout. It asks for a department, a priority rating, and an explicit urgency signal. I ran this request against the direct endpoint on October 4, 2026 and received HTTP 200.

How to call the Jev API

Load your key into the current shell first. On macOS or Linux with Bash, this keeps it out of the command text. Keep the key in a server environment or secret store when you build an application.

read -rsp "TypeSafe API key: " TYPESAFE_API_KEY; echo
export TYPESAFE_API_KEY

curl --fail-with-body --silent --show-error \
  https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "jev-latest",
  "state": "Our checkout integration has failed since this morning. Customers cannot pay. Please fix it today.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this support ticket?",
      "criteria": {
        "billing": "Charges, invoices, or refunds",
        "technical": "Broken software, outages, or integration failures",
        "sales": "Buying, upgrading, or product questions",
        "other": "None of these teams is a clear match"
      }
    },
    "priority": {
      "type": "score",
      "instructions": "How quickly does this ticket need attention?",
      "criteria": [
        "Routine: no immediate disruption",
        "Soon: impaired work, but a workaround is available",
        "Now: customers cannot complete a critical task"
      ]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "Does the customer explicitly request action today?"
    }
  }
}
JSON

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "confidence": 1,
      "probabilities": {
        "billing": 0,
        "sales": 0,
        "other": 0,
        "technical": 1
      }
    },
    "priority": {
      "type": "score",
      "score": 2,
      "confidence": 1,
      "legend": {
        "0": "Routine: no immediate disruption",
        "1": "Soon: impaired work, but a workaround is available",
        "2": "Now: customers cannot complete a critical task"
      },
      "probabilities": {
        "0": 0,
        "1": 0,
        "2": 1
      }
    },
    "is_urgent": {
      "type": "noul",
      "noul": 0.98
    }
  },
  "usage": {
    "input_tokens": 451,
    "output_tokens": 78
  }
}

The observed result is technical, priority 2, and urgency 0.98. The response reports 451 input tokens and 78 output tokens. This is one recorded response, not a promise that repeated requests or other tickets produce the same probabilities. For the code that turns it into a queue assignment, follow the ticket triage walkthrough.

Which request parameters are required?

The HTTP request needs all three top-level fields. The SDK can supply its own model default; that does not make model optional in a raw HTTP request. The following table follows the live OpenAPI schema.

The prose API reference marks instructions as required, while the checked OpenAPI schema permits omission. I include them explicitly. The reference documents at most 255 Choice options and 2–10 Score levels; these examples stay comfortably within those bounds.

For “Jev JSON mode,” the useful distinction is simple: JSON is already the request and response format. There is no response_format parameter here. A question key such as department names the returned answer; put the actual task in instructions, not in that key.

When should I trust a decision enough to act?

I keep the label and the certainty separate. A Choice always picks an option from the supplied set, even when the ticket is a poor fit. Adding an other label gives the workflow a place to send out-of-scope cases, but my code still checks confidence before routing.

For Choice and Score, confidence describes the probability distribution. It is not interchangeable with the selected option’s probability, and 1.0 is not proof of correctness. Noul exposes the yes probability directly: values near the middle are useful candidates for review.

const department = response.answers.department;
// 0.8 is an example policy threshold, not an API default.
const queue = department.confidence < 0.8
  || department.choice === "other"
  ? "manual-review"
  : department.choice;

Before using a threshold, label a sample of real tickets, measure mistakes among the automatically routed cases, and pick the review workload you can sustain. Read TypeSafe’s confidence guide for the distinction between probability and certainty.

What does Jev cost per request?

On October 4, 2026, TypeSafe’s model reference listed Jev 1.13 at $0.042 per million input tokens, with output tokens free. The live OpenRouter model page showed the same token rate. Check the provider you actually bill through before budgeting.

estimated USD = usage.input_tokens × 0.042 / 1,000,000
500 input tokens × 0.042 / 1,000,000 = $0.000021
1,000 requests × $0.000021 = $0.021
Recorded request: 451 input tokens → $0.000018942

This estimates token charges, not an invoice or an account quota. It does not assume free credits, a subscription allowance, or a minimum top-up. The ticket text alone does not explain the billed count: use usage.input_tokens after sending the full state and questions.

What are the limits, and how should I handle errors?

The checked direct TypeSafe limits are 80 requests per second and 100K tokens per second. These are per-second limits, not monthly allowances. TypeSafe says they can change during demand spikes; I would set a worker queue below the account’s effective limit instead of assuming this snapshot is a guaranteed throughput target.

The direct model reference documents 64K tokens across state and all questions, plus a 32K limit for state and the longest individual question. OpenRouter displays a 32K context window. Keep the provider’s own budget in view and trim irrelevant text before adding more questions.

These statuses and retry guidance come from the official error reference. TypeSafe’s default client retry policy handles transient limits. For direct HTTP calls, apply bounded retries yourself; do not create an immediate retry loop. Account credit balances and custom quotas belong in the provider console.

Which Jev model version am I using?

Our request used jev-latest and the response reported jev-1.13.0. The documented stable and preview aliases currently point to that version. An alias can move without a code change; log the response’s model with every saved evaluation.

curl --fail-with-body --silent --show-error \
  https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

Our checked account listed jev-latest and jev-preview. The model reference also documents versioned IDs, even when the listing contains only aliases. Pin a supported version for a tested production workflow and re-run your labeled cases before adopting a newer one.

Which key, SDK, or provider should I use?

The direct key comes from TypeSafe’s console. This site’s API interest signup is not a credential service. For an installed SDK and an executable first call, use our JavaScript setup steps.

What can I build with these call shapes?

These are design sketches, not additional recorded API responses. Each uses the same { model, state, questions } envelope; replace the sample text and define the business rules in code.

Support ticket routing

Send the ticket as state with a questions.department Choice, then route the label to an allowed queue or review it when uncertain—the tested request above implements this shape.

Jev document classification

Send extracted document text as state with a questions.kind Choice, then map your approved categories to storage tags.

Jev invoice processing

Send extracted invoice text as state with a questions.needsReview Noul, then check amounts, tax, duplicate IDs, and supplier records with deterministic code.

Relevance ranking

Send a query and passage in state with a questions.relevance Score, then rank by the rubric while retaining the distribution.

Application action selection

Send the current situation and allowed actions in state with a questions.action Choice, then validate the result against the allowed set before execution.

For a working application to explore, try the Chat Intent Analyzer. It demonstrates decision signals in a visible workflow. Use the tutorial below to build your own server-side flow from the complete ticket example.

Frequently asked questions

Keep building