How to Use the Jev API

This guide walks through the Jev API as documented in the official TypeSafe AI docs: authenticating, sending a state, asking questions with the three primitives, and reading structured answers back.

One request, many questions

A request is one state plus any number of typed questions. Every question is evaluated against the state in parallel and in isolation, so adding questions barely changes response time and each answer stands on its own.

There are exactly three question types, which TypeSafe calls primitives:

All three can be mixed in a single call.

1. Get an API key

Create a key in the TypeSafe console and keep it server-side. The client SDKs read the conventional environment variable:

export TYPESAFE_API_KEY="your-api-key"

Like any AI provider credential, it should never ship to the browser. Calls belong in your backend or a serverless function.

2. Your first decision

The endpoint is POST https://api.typesafe.ai/v1/systemone. The model field selects the model; jev-latest is the default alias and the one the docs use in examples.

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Customer says: I was charged twice for this month.",
    "model": "jev-latest",
    "questions": {
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this",
        "criteria": {
          "billing": "Payment or subscription issues",
          "technical": "Bugs or integration problems",
          "sales": "Pricing or account questions"
        }
      },
      "is_urgent": {
        "type": "noul",
        "instructions": "The message conveys urgency or time-sensitivity"
      }
    }
  }'

A Choice question maps each option to a short description through criteria. Those descriptions are part of the answer space, and a well-described option discriminates better than a bare label.

The response returns typed answers plus token usage:

{
	"model": "jev-1.13.0",
	"answers": {
		"department": {
			"type": "choice",
			"choice": "billing",
			"confidence": 0.89,
			"probabilities": {
				"billing": 0.91,
				"technical": 0.02,
				"sales": 0.07
			}
		},
		"is_urgent": {
			"type": "noul",
			"noul": 0.93
		}
	},
	"usage": {
		"input_tokens": 210,
		"output_tokens": 65
	}
}

3. Calling Jev from TypeScript

TypeSafe ships an official JavaScript SDK (@typesafe-ai/sdk). If you prefer raw HTTP, wrap the fetch in one small typed function rather than scattering calls across the codebase:

type SystemOneResponse = {
	model: string;
	answers: {
		department: {
			type: "choice";
			choice: string;
			confidence: number;
			probabilities: Record<string, number>;
		};
		is_urgent: {
			type: "noul";
			noul: number;
		};
	};
	usage: { input_tokens: number; output_tokens: number };
};

export async function routeTicket(message: string): Promise<SystemOneResponse> {
	const response = await fetch("https://api.typesafe.ai/v1/systemone", {
		method: "POST",
		headers: {
			Authorization: `Bearer ${process.env.TYPESAFE_API_KEY}`,
			"Content-Type": "application/json",
		},
		body: JSON.stringify({
			state: `Customer says: ${message}`,
			model: "jev-latest",
			questions: {
				department: {
					type: "choice",
					instructions: "Which team should handle this",
					criteria: {
						billing: "Payment or subscription issues",
						technical: "Bugs or integration problems",
						sales: "Pricing or account questions",
					},
				},
				is_urgent: {
					type: "noul",
					instructions: "The message conveys urgency or time-sensitivity",
				},
			},
		}),
	});

	if (!response.ok) {
		throw new Error(`TypeSafe API error: ${response.status}`);
	}

	return response.json();
}

The typed return value is what matters downstream. Your code branches on choice and confidence with no string munging.

4. Acting on confidence

Choice and Score answers carry a confidence value. TypeSafe's docs are precise about what it means: probabilities are calibrated against outcomes across groups of predictions, and it does not guarantee any individual answer is correct. That is exactly what makes it usable as a routing signal with a fallback policy.

const result = await routeTicket(message);
const { choice, confidence } = result.answers.department;

if (confidence >= 0.85) {
	return assignTo(choice);
}

if (confidence >= 0.6) {
	return askClarifyingQuestion();
}

return escalateToHuman();

Automate the confident majority and escalate the uncertain tail, and a decision model starts paying for itself.

5. Limits worth knowing

From the official models page, as of Jev 1.13:

• Pricing: $0.042 per million input tokens ($42 per billion). Output tokens are free.
• Rate limits: 250,000 tokens/second and 1,200 requests/minute, currently adjusting dynamically while demand is high. The official SDKs retry with backoff and honor retry-after.
• Context: 64k tokens per request total; 32k for the state plus the single longest question.
• Input: text only (strings, JSON objects, arrays of text). Pre-process other media into text.
• Language: English is the strongest. Other languages including CJK work, but test on your own content.

6. Things to keep in mind

Keep states relevant. The 64k budget is generous, but accuracy shifts as the state grows, so send the context the decision needs rather than the whole transcript.

Options are part of the answer space. Adding a clearly wrong option is a good way to test discrimination; overlapping descriptions compress the probabilities.

Log answers and confidence. You will want the history when you tune thresholds or compare Jev against alternatives.

Handle failures explicitly. Timeouts and 4xx responses should degrade to your fallback path, not crash the request that contains them.

Try it

Experiment with the three primitives in the official TypeSafe playground, or practice routing, tool-selection, and scoring scenarios in the Jev Agent playground.

What to read next

• Jev Tutorial: Build Your First Decision Workflow
• Jev Model Explained: System One Models
• Jev Pricing Explained