state against a map of typed questions and get back structured answers, one per question. For a guided introduction, start with the primitives.
Evaluation endpoint
Request body
The top-level shape of every request. Each entry in thequestions map is a typed question you name.
string | object | array
required
The content to evaluate. A plain string for text, or structured data (object/array) for things like chat logs, records, or the current state of your application. See State for formats and best practices.
string
required
The model that handles the request. Use
"jev-latest", TypeSafe’s flagship model.map<string, Question>
required
A map of typed Question objects. You choose each key; answers come back under the same keys.
Example request
Question types
AQuestion is one of three types, set by its type field. All three share type and instructions; each adds its own criteria.
Noul
A yes/no question. Returns the probability the answer is yes."noul"
required
string | object | array
required
The yes/no question to evaluate.
object
Optional descriptions of what a yes and a no mean.
Example request
Choice
Picks one option from a set you define. Returns the chosen option and the full probability distribution."choice"
required
string | object | array
required
What the model should decide.
map<string, string | null>
required
A map of option to rubric description; use null when an option needs no extra detail.
Example request
Score
Rates the state along a rubric you define. Returns a probability-weighted value across your levels."score"
required
string | object | array
required
What the model should rate.
array
required
An ordered array of level descriptions. You must include at least two levels.
Example request
Response body
One answer per question, returned under the same ids you provided.string
required
The model that performed the evaluation.
object
required
Token usage for the request.
Example response
Answer types
Every answer carries atype matching its question. Choice and Score answers also carry a confidence between 0 to 1, derived from the answer’s probability distribution. See Confidence.
Noul answer
"noul"
required
number
required
The yes/no answer on a scale from 0 (no) to 1 (yes).
Example response
Choice answer
"choice"
required
string
required
The highest-probability option.
map<string, number>
required
Every option mapped to its probability (floats that sum to 1).
number
required
How certain the model is, derived from probabilities.
Example response
Score answer
"score"
required
number
required
The probability-weighted answer across the levels; can land between levels.
map<string, string>
required
Each level number mapped back to its description.
map<string, number>
required
Each level (string key) mapped to its probability (floats that sum to 1).
number
required
How certain the model is, derived from probabilities.
Example response
Errors
Errors use standard HTTP status codes with a JSON body describing what went wrong.Handling rate limits
When you receive a429 Too Many Requests or 529 Overloaded response, retry the request with exponential backoff instead of retrying immediately. Our client SDKs handle this automatically, so no extra handling is needed if you use one of our SDKs with its default retry policy.