Jev API

/ 01

Quick Start

1. Get a key at console.typesafe.ai/keys.
2. POST to the endpoint with Authorization: Bearer <API_KEY>.
3. Read answers using your question id.

curl -X POST https://api.typesafe.ai/v1/systemone   -H "Authorization: Bearer $TYPESAFE_API_KEY"   -H "Content-Type: application/json"   -d '{"state":"An agent plans to send customer history to an unverified endpoint without recorded consent.","model":"jev-latest","questions":{"requires_review":{"type":"noul","instructions":"Does this action require explicit human approval?"}}}'

Request shape checked against the official quick start.

/ 02

The Endpoint

POST https://api.typesafe.ai/v1/systemone with a Bearer key and Content-Type: application/json. This is TypeSafe’s direct endpoint; this guide documents it for your own integration.

VerdictKit’s live playground instead calls POST https://openrouter.ai/api/alpha/decisions with typesafe/jev-1.13 through a server-side relay and our OpenRouter key. For your own OpenRouter integration, use your own key. Neither path gives you a VerdictKit API key.

/ 03

Request Body

/ 04

The Three Question Types

{
  "state": {
    "user_request": "Find the current Jev API price and cite the official documentation.",
    "available_tools": ["search_docs", "browser", "calculator"],
    "proposed_action": "Send customer history to an unverified external endpoint without recorded consent.",
    "ticket_impact": "A production outage blocks all workspace deployments."
  },
  "model": "jev-latest",
  "questions": {
    "tool": { "type": "choice", "instructions": "Which tool should the agent use first?", "criteria": { "search_docs": "Search internal knowledge", "browser": "Open current public documentation", "calculator": "Perform arithmetic" } },
    "action_risk": { "type": "score", "instructions": "How risky is it to execute the proposed action?", "criteria": ["Low", "Moderate", "High"] },
    "ticket_priority": { "type": "choice", "instructions": "What support response priority should be assigned?", "criteria": { "p0": "Critical broad outage", "p1": "Major impairment", "p2": "Routine request" } }
  }
}

/ 05

Agent Workflow Examples

Jev API calls can support bounded agent decisions such as tool selection (Choice), action risk scoring (Score) and support ticket priority (Choice). Define the available tools, ordered risk levels or priority labels in each question’s criteria so the answer stays within your application’s decision set. See the agent workflow examples for sample states and response shapes.

/ 06

Response Body

noul:  { "type": "noul", "noul": 0.95 }
choice: { "type": "choice", "choice": "browser", "probabilities": {...}, "confidence": 0.77 }
score:  { "type": "score", "score": 1.71, "legend": {...}, "probabilities": {...}, "confidence": 0.89 }

See Jev JSON output for all fields and parsing pitfalls.

/ 07

Get Your Jev API Key

1. Sign in to the TypeSafe console.
2. Open the keys page and generate a key.
3. Store it in a server-side TYPESAFE_API_KEY environment variable.

/ 08

Official SDKs

Python 3.10+: pip install typesafe-sdk. The client reads TYPESAFE_API_KEY and defaults to jev-latest.

from typesafe_sdk import Choice, Score, TypeSafeClient

client = TypeSafeClient()
response = client.system_one(
    state="A user needs the current Jev API input price and an official citation. Available tools: search_docs, browser, calculator. A separate agent action would send customer records to an unverified endpoint without consent, and a production outage blocks deployments.",
    questions={
        "tool": Choice(instructions="Which tool should the agent use first?", criteria={"search_docs": "Search internal knowledge", "browser": "Open current public documentation", "calculator": "Perform arithmetic"}),
        "action_risk": Score(instructions="How risky is it to execute the proposed action?", criteria=["Low", "Moderate", "High"]),
        "ticket_priority": Choice(instructions="What support response priority should be assigned?", criteria={"p0": "Critical broad outage", "p1": "Major impairment", "p2": "Routine request"}),
    },
)
print(response.answers["tool"].choice)

The official SDK retries 429 and 529 by default. See Python SDK documentation.

/ 09

Errors and Retries

/ 10

429 Rate Limits and Exponential Backoff

A 429 Too Many Requests response means the request exceeded a rate limit. Stop sending requests immediately and retry with exponential backoff; TypeSafe also recommends this for 529 Overloaded. Honor Retry-After when the response includes it. The official SDKs retry these responses by default. TypeSafe’s model page currently lists direct API limits, but notes that they can change dynamically.

async function postWithRetry(url, init, maxRetries = 5) {
  for (let attempt = 0; ; attempt++) {
    const response = await fetch(url, init);
    if (![429, 529].includes(response.status) || attempt >= maxRetries) {
      return response;
    }

    const retryAfter = response.headers.get("retry-after");
    const retryAfterSeconds = retryAfter === null ? NaN : Number(retryAfter);
    const retryAfterDate = retryAfter === null ? NaN : Date.parse(retryAfter);
    const delayMs = retryAfter === null
      ? Math.random() * Math.min(30_000, 500 * 2 ** attempt)
      : Number.isFinite(retryAfterSeconds)
        ? retryAfterSeconds * 1_000
        : Number.isFinite(retryAfterDate)
          ? Math.max(0, retryAfterDate - Date.now())
          : Math.random() * Math.min(30_000, 500 * 2 ** attempt);

    await response.body?.cancel();
    await new Promise(resolve => setTimeout(resolve, delayMs));
  }
}

This example uses capped exponential backoff with jitter when no valid Retry-After value is supplied. It does not set a request rate or guarantee a retry will succeed. See the official API error and retry guidance.

/ 11

What It Costs

At review time, TypeSafe lists $0.042 per million input tokens for Jev 1.13 and free output tokens. This is a current reference, not a guaranteed future price. Check the official models page before budgeting. For VerdictKit plan prices, see Pricing. We do not control TypeSafe’s rate or resell API credits.

/ 12

Is There a Free Jev API?

Short answer: no. TypeSafe does not publish a free tier for the Jev API. Calling it requires an API key and is billed per input token, with output free at the currently published rate. A small call can cost a fraction of a cent, but the API is still metered. The paths below separate free playground exploration from paid API access.

1. Use a playground — two guest runs or five account runs per day, no API key

Paste your state, ask a typed question, and inspect the structured answer. Our Jev playground provides clearly labeled example previews without an account, key or card. Guests can make two live runs per day without signup. Sign in with Google for the 5-live-runs-per-day Free account. Both include Choice, Score and Noul and full JSON output, resetting at 00:00 UTC. A playground is a browser workflow, not an API key.

TypeSafe’s console playground is another option for hands-on evaluation, but requires sign-in.

2. Start on a gateway for metered access without a TypeSafe account

OpenRouter lists Jev as typesafe/jev-1.13. You can top up an OpenRouter account and pay per call without a separate TypeSafe account. Check its current model price and any gateway fees against TypeSafe’s published rate; a markup is not guaranteed.

3. Go direct — the official API

Get a key at console.typesafe.ai/keys and call POST https://api.typesafe.ai/v1/systemone. Your application pays TypeSafe directly for input tokens; output tokens are free at the published rate.

What we don’t do

VerdictKit is not an API reseller. We do not provide customer API keys, sell an API gateway or mark up tokens. This page documents TypeSafe’s official API so your own integration can call TypeSafe and pay TypeSafe directly. Playground live requests, when configured, pass through our server using our key; this internal relay does not give customers API access.

Our paid plans cover playground workflow features: Run Pack includes 500 runs that never expire, Pro adds unlimited runs, saved judges, history and CSV export, and Batch adds file processing for teams. None includes a TypeSafe API key or API credits. See Pricing for launch status and plan details.

If you find an offer called a “free Jev API,” check whether it is a trial credit or a gateway product. TypeSafe does not publish a free API tier in the documentation reviewed here.

/ 13

Try Jev Without an API Key

Open the Jev playground, paste your state and add a typed Choice, Score or Noul question. Example previews and sample JSON need no account, key or card. A human-verification challenge protects each live request.

The guest trial allows two live runs per day without signup. A free Google account allows 5 live runs per day. Both include all three question types and full JSON output, with allowances resetting daily at 00:00 UTC. Need more? Run Pack offers 500 runs that never expire; Pro removes the daily cap and adds saved judges, run history and CSV export; Batch handles files for teams. See Pricing. These plans do not include an API key.

/ FAQ

Frequently asked questions