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.
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.
The model that handles the request. Use
"jev-latest", CosVec’s flagship model. See Models for the available models and aliases.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.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.
Example request
Choice
Picks one option from a set you define. Returns the chosen option and the full probability distribution.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.
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.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.
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.One Answer per question, keyed by the same ids you used in questions.
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
Example response
Choice answer
Example response
Score answer
Each level (string key) mapped to its probability (floats that sum to 1).
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.