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. See Models for the available models and aliases.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.
The instructions property can be a string, an object, or an array. You can break up a long question that has extra context, or data it needs to reference, into a structured object. Put the question in one field and the data in the others, and refer to the data fields by name in backticks, the same way you point a question at a nested state value:
Noul
A yes/no question. Returns the probability the answer is yes."noul"
required
string | object | array
required
The yes/no question to evaluate. An object can hold the question in one field and data it refers to in others; see Use structure in the questions.
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. An object can hold the question in one field and data it refers to in others; see Structured instructions and criteria.
map<string, string | object | array | null>
required
A map of option to rubric description; use null when an option needs no extra detail. You can have a maximum of 255 options per Choice.
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. An object can hold the question in one field and data it refers to in others; see Use structure in the questions.
array<string | object | array>
required
An ordered array of level descriptions. A Score should have at least two levels; the API accepts up to 10.
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.