Jev Agent

Independent Platform · Designed for TypeSafe's Jev Model

Jev API: Typed Decisions for Your Code

The Jev API lets your code ask structured questions and get typed answers back — no prompt engineering, no free-form text to parse. You send a state (a support ticket, a document, a log line) with one or more named questions, and each answer comes back as a typed object: a choice with per-option probabilities, a score on the levels you define, or a Noul probability. Choice and score answers also carry a confidence value. The Jev Agent endpoint, /api/v1/systemone, follows the shape of TypeSafe's published examples for TypeSafe's own Jev AI API.

This page covers the request and response shapes, the three question types, how authentication works, and how a Jev Agent key differs from an official TypeSafe API key. It closes with a Pydantic example and a note on calling the API from your own CLI or SDK.

Quickstart

A request names a state and a map of named questions. Each question is a choice among labeled options, a score, or a noul probability. Here is a request adapted from the support-routing example in LiteLLM's TypeSafe pass-through documentation:

{
  "model": "jev-latest",
  "state": "Help! My payouts have been failing for 3 days.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

The response wraps every answer in an answers map keyed by question name, alongside the model that answered and a usage object:

{
  "model": "jev-latest",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "probabilities": {
        "billing": 0.08,
        "technical": 0.85,
        "sales": 0.07
      },
      "confidence": 0.82
    }
  },
  "usage": { "input_tokens": 312 }
}

Example adapted from LiteLLM's TypeSafe pass-through docs.

Request

{
  "model": "jev-latest",
  "state": "Help! My payouts have been failing for 3 days.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

Response

Illustrative sample — not a live Jev response

Press Run live to send this request to Jev and see the typed answers.

The panel above runs this support-routing request against Jev live, alongside a ticket-triage example, so you can see the real response shape before you write code of your own.

Choice, Score, Noul Endpoints

TypeSafe's own API accepts text input only and answers three question types through a single endpoint, POST /v1/systemone, using the jev-latest model, as TypeSafe's System One docs describe. The Jev Agent endpoint follows the shape of TypeSafe's published examples. A state can be a plain string, a JSON object, or an array of strings — whichever best represents the text you're classifying.

Choice

A choice question sets an instructions string describing the decision, plus a criteria object mapping each option name to a short description. The response returns the option with the highest probability under choice, a probability for every option under probabilities, and an overall confidence value. Use choice questions for routing, tagging, and any decision with a fixed set of outcomes, like the department example above.

Score

A score question sets criteria to an ordered list of level descriptions, from the low end of the scale to the high end (two to ten levels). The response returns score, a position on that level line from 0 to the top level number, plus probabilities for each level (keyed by level number), a legend mapping each level number back to its description, and a confidence value. Use it to rate severity, urgency, or quality on a graded scale — an incident's urgency from "can wait" to "drop everything", for example.

Noul

A Noul question returns a probability, under noul, that a described condition is true — 0 means no, 1 means yes. There is no separate confidence value for a Noul: the probability is the answer. An optional criteria object with true and false descriptions spells out what counts as each. Use it for yes-or-no checks where you want a graded probability rather than a hard boolean — whether a refund is warranted, or whether a message contains a policy violation.

API Key Authentication

Every request to the Jev Agent endpoint needs an Authorization header:

curl https://jev-agent.org/api/v1/systemone \
  -H "Authorization: Bearer <your Jev Agent key>" \
  -H "Content-Type: application/json" \
  -d '{"model": "jev-latest", "state": "...", "questions": {...}}'

Create that key from your account settings on a paid plan, then send it in the header above.

Official TypeSafe API Key vs Jev Agent Key

There are two honest paths to this API, and they are not the same thing. An official TypeSafe API key comes directly from TypeSafe AI once you clear its own waitlist. It authenticates against TypeSafe's production service and is entirely TypeSafe's to issue, price, and support.

A Jev Agent key is ours. It authenticates against the Jev Agent endpoint, /api/v1/systemone, which follows the shape of TypeSafe's published examples for TypeSafe Jev. Both paths are meant to return answers shaped like Jev (TypeSafe AI): a choice, a score, or a Noul probability, with a confidence value on choice and score answers. Which one you want depends on whether you're building directly on TypeSafe's own infrastructure or on Jev Agent's plans and the tooling on this site.

Get your Jev Agent API key

Pydantic Integration

Model your questions and responses with Pydantic so a malformed reply fails loudly instead of silently:

from typing import Literal

import requests
from pydantic import BaseModel


class DepartmentAnswer(BaseModel):
    type: Literal["choice"]
    choice: str
    probabilities: dict[str, float]
    confidence: float


class RoutingResponse(BaseModel):
    model: str
    answers: dict[str, DepartmentAnswer]
    usage: dict[str, int]


payload = {
    "model": "jev-latest",
    "state": "Help! My payouts have been failing for 3 days.",
    "questions": {
        "department": {
            "type": "choice",
            "instructions": "Which team should handle this?",
            "criteria": {
                "billing": "Payments, invoicing, refunds",
                "technical": "Bugs, outages, integrations",
                "sales": "Pricing, upgrades, new accounts",
            },
        }
    },
}

resp = requests.post(
    "https://jev-agent.org/api/v1/systemone",
    headers={
        "Authorization": "Bearer <your Jev Agent key>",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
result = RoutingResponse.model_validate(resp.json())
department = result.answers["department"]
print(department.choice, department.confidence)

This Pydantic integration catches schema drift immediately — a renamed field or a dropped probability throws before your code acts on bad data, which matters more once this call sits inside a larger agent loop.

Local CLI and SDK Access

Jev runs as a hosted API. TypeSafe does not distribute offline model weights, so there is no local model to download and run. You can still call the hosted endpoint from wherever your code already lives: a script on your laptop during development, a CLI tool wired into a build pipeline, or an SDK you write yourself as a thin wrapper around the requests call above. Nothing about the request format changes based on where the call originates — only the Authorization header and base URL matter.

Errors and Rate Limits

These error codes and rate limits are planned at launch, not live yet:

CodeMeaning
400Malformed request body
401Missing or invalid API key
402Payment required
429Rate limit exceeded
502Upstream error

Rate limit: 600 requests per minute (RPM) on every paid plan. See API Token Pricing & Rate Limits for the plans and their token pricing.

Next Steps

Wire this endpoint into an autonomous loop in Build an Agent with Jev API, or Read Jev Technical Whitepaper for the model concepts behind Choice, Score, and Noul.

Frequently asked questions

How do I get a TypeSafe API key for Jev?

Official TypeSafe API keys are issued by TypeSafe AI through its early-access waitlist at typesafe.ai. Jev Agent keys are separate: they work with the Jev Agent endpoint and are issued from your account settings on a paid plan.

What formats does the Jev API support?

Requests are JSON with a state — a string, a JSON object or an array of strings — and a map of named questions. Each answer comes back under the same name as a typed object: a choice with per-option probabilities, a score on the levels you define or a Noul probability, with a confidence value on choice and score answers. Jev currently accepts text input only.

Can I run Jev locally?

No. Jev runs as a hosted API and TypeSafe does not distribute offline model weights. You can still call it from local scripts, a command-line tool or an SDK in your own code — see the local CLI and SDK section on this page.