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 numeric score, or a Noul probability, each with a confidence value attached. The Jev Agent endpoint, /api/v1/systemone, follows the shape of TypeSafe's published examples; compatibility with TypeSafe's own Jev AI API will be confirmed before the endpoint opens with early access.

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.

{
  "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 panel above shows this support-routing request as an illustrative sample alongside a ticket-triage example, so you can see the shape of both before you have a key 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; compatibility will be confirmed before it opens. 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 returns a single numeric value under score, plus a confidence value. Use it to rate severity, urgency, or quality along a continuous scale instead of picking from a labeled list — an incident's urgency from 0 to 10, for example.

Noul

A Noul question returns a probability, under noul, that a described condition is true, with a confidence value attached. 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": {...}}'

You'll create that key from your account settings once Jev Agent early access opens for your batch. There is no key to generate yet, so treat the header above as the shape to expect rather than something to call today.

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 will authenticate against the Jev Agent endpoint, /api/v1/systemone, and will roll out in batches as Jev Agent early access opens; that endpoint follows the shape of TypeSafe's published examples for TypeSafe Jev, and compatibility will be confirmed before it opens. Both paths are meant to return answers shaped like Jev (TypeSafe AI): a choice, a score, or a Noul probability, each with a confidence value. Which one you want depends on whether you're building directly on TypeSafe's own infrastructure or joining Jev Agent's early-access rollout and the tooling on this site.

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.

Errors and Rate Limits

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

Planned rate limits at launch: 60 requests per minute (RPM) on the free tier, 600 RPM on paid plans. See API Token Pricing & Rate Limits for how those tiers map to token pricing once billing opens.

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.