THE OPENJEV API / ADVANCED REFERENCE
The API,
in detail.
The shapes you send. The values you receive.
A reference for integrating OpenJEV into your application.
Start with the API quickstart for your first call. Complete application examples live in Use cases.
One endpoint. JSON in and out.
https://api.openjev.sh/v1/systemoneSend Content-Type: application/json and Authorization: Bearer <your API key>. Create a key in your dashboard and keep it in your server environment.
| Field | Shape | Meaning |
|---|---|---|
state | String, object, or array | Required. The content to evaluate, including the context needed for the questions. |
questions | Non-empty object | Required. Each key identifies a question and its corresponding answer. |
model | String | Optional. Defaults to openjev. |
{
"model": "openjev",
"state": "Please cancel my subscription.",
"questions": {
"cancellation": {
"type": "noul",
"instructions": "Does the message request cancellation?"
}
}
}Examples on this page demonstrate request and response shapes. Response values are illustrative, not live model results.
Supply the context explicitly.
Jev evaluates text and structured JSON. Put the content and relevant facts in state; put the judgment to make in instructions. Fetch external records in your application before sending them. A URL is not a request to browse, and this endpoint does not accept image, audio, or file uploads.
A string
"Please cancel my subscription."An object
{
"message": "Please cancel my subscription.",
"account": { "plan": "monthly" },
"policy": "Monthly subscriptions can be cancelled at any time."
}An array
[
{ "speaker": "customer", "text": "Can I cancel?" },
{ "speaker": "support", "text": "Yes, at any time." }
]Reference a field with a dot-and-index path in backticks, such as account.plan or messages[0].text. These are natural-language cues, not a guaranteed dynamic evaluator or JSONPath operation. The referenced data must actually be present in the state.
{
"type": "noul",
"instructions": "Does `policy` allow the request in `message` for `account.plan`?"
}A question can have structure.
Use a clear, specific string for most questions. instructions can also be an object or an array when you need to keep the judgment, context, and constraints together.
{
"type": "noul",
"instructions": {
"question": "Does the message explicitly request cancellation?",
"scope": "Judge the customer's stated intent, not whether cancellation is allowed.",
"evidence": ["A direct request to cancel", "A request to stop renewal"]
}
}{
"type": "noul",
"instructions": [
"Does the message explicitly request cancellation?",
"A pricing question alone does not count as a cancellation request."
]
}Your field names are context, not API commands. Keys such as scope and evidence are names you choose. They do not introduce new execution settings or separate questions.
Question IDs label the returned answers for your application. They are not sent to the model. Write the complete judgment in instructions, even when the ID seems descriptive.
Define the possible answers.
Use choice for a category, score for an ordered scale, and noul for a yes/no judgment. The shape of criteria depends on the type.
| Type | Criteria container | Descriptions & limits |
|---|---|---|
| Choice | Object of named options | Up to 255 options. A description can be a string, object, array, or null. At least two options make a meaningful choice. |
| Score | Ordered array of levels | Up to 10 levels. Each level can be a string, object, or array. Use at least two distinct, described levels. |
| Noul | Optional object | Use true and/or false to describe the outcomes. Descriptions can be strings, objects, arrays, or null. |
Choice One named option
The option keys are the values your code receives. Include other or none when the list may not cover every input. Use null when an option name needs no further explanation.
{
"type": "choice",
"instructions": "What is the message asking about?",
"criteria": {
"cancellation": "Ending a subscription or stopping renewal",
"billing": "Payments, invoices, or charges",
"other": "None of the listed topics"
}
}For more detailed boundaries, give an option a structured description. The outer criteria stays an object of option names.
{
"type": "choice",
"instructions": "What is the message asking about?",
"criteria": {
"cancellation": {
"covers": "Ending a subscription",
"excludes": "Asking about the price",
"examples": ["Cancel my plan", "Stop renewal"]
},
"other": "Anything outside this definition"
}
}{
"type": "choice",
"choice": "cancellation",
"probabilities": { "cancellation": 1.0, "billing": 0.0, "other": 0.0 },
"confidence": 1.0
}Illustrative answer to the three-option question. A Choice returns one option; use separate Noul questions when several labels can apply independently.
Score A position on a scale
Levels are numbered from zero by their position in the array. A three-level scale returns a score from 0 to 2. A fractional value lies between levels; it is not a percentage or a category ID.
{
"type": "score",
"instructions": "How urgent is the request?",
"criteria": [
"No deadline or time pressure expressed",
"Would like a response soon, without a fixed deadline",
"Explicit deadline or request for immediate action"
]
}A level can contain a structured description. The outer container must still be an ordered array; an object inside that array describes one level.
{
"type": "score",
"instructions": "How urgent is the request?",
"criteria": [
{ "meaning": "No time pressure", "examples": ["Whenever convenient"] },
{ "meaning": "Immediate action requested", "examples": ["Please help now"] }
]
}{
"type": "score",
"score": 1.0,
"legend": {
"0": "No deadline or time pressure expressed",
"1": "Would like a response soon, without a fixed deadline",
"2": "Explicit deadline or request for immediate action"
},
"probabilities": { "0": 0.0, "1": 1.0, "2": 0.0 },
"confidence": 1.0
}Illustrative answer to the three-level question. The legend maps level numbers to their descriptions; those descriptions may themselves be structured.
Each level needs a self-contained description. Avoid labels such as “better than the previous level.” When comparing scales of different lengths, divide each score by number of levels − 1 before applying weights in your code.
Noul A yes/no probability
The noul value is between 0 and 1: near 1 means yes, near 0 means no, and near 0.5 means uncertainty. It does not measure degree or intensity. Noul has no separate confidence field.
{
"type": "noul",
"instructions": "Does the message explicitly request cancellation?",
"criteria": {
"true": "A direct request to end the subscription",
"false": "No cancellation request is expressed"
}
}{ "type": "noul", "noul": 0.92 }Omit criteria when the instructions already define yes and no clearly. Structured descriptions are supported here too.
Primitive shapes and limits follow the TypeSafe references for questions, Choice, Score, and Noul. Use OpenJEV’s endpoint and API key for the requests shown here.
Read the value and its uncertainty.
The response places each result under answers[questionId]. Check the HTTP status first. Choice and Score include probabilities and confidence; Noul returns its yes probability directly.
{
"model": "openjev",
"answers": {
"cancellation": { "type": "noul", "noul": 0.92 }
},
"usage": { "input_tokens": 120, "output_tokens": 8 }
}Illustrative response and token counts.
Confidence is not the selected option’s probability.
Confidence summarizes how concentrated the distribution is. It is not a guarantee of correctness, and a value of 0.9 is not a promise of 90% accuracy. Choose thresholds using representative labeled examples and the consequences of an incorrect result.
A Score is the probability-weighted mean of level numbers. Different distributions can produce the same score: all probability on level 1 and an even split between levels 0 and 2 both average to 1. Read the full distribution when that distinction matters.
For Noul, confident no is near 0, not near 0.5. Use separate yes, no, and uncertain ranges rather than treating every low value as low confidence.
Shared state. Independent answers.
All questions in one request are evaluated independently against the same state. The order of keys does not create a sequence. One question cannot reference another question’s answer within the same call.
{
"state": "Please cancel my subscription today.",
"questions": {
"cancellation": {
"type": "noul",
"instructions": "Does this message request cancellation?"
},
"urgent": {
"type": "noul",
"instructions": "Does this message request action today?"
}
}
}Send independent questions together, including conditional questions whose results your code may ignore. Make a second request when a previous answer is needed to fetch new state or define the next set of options. More questions still add tokens; measure performance with your own request sizes.
Models, keys, and usage.
The public model
openjev is the default public alias. It follows the configured latest Jev model, so it is not a pinned model-version identifier. The public model listing is available at GET https://api.openjev.sh/v1/models.
{
"object": "list",
"data": [{ "id": "openjev", "description": "OpenJEV public Jev." }]
}Usage is reported in tokens
When provided in the response, usage.input_tokens and usage.output_tokens describe model token usage. They are not currency amounts or a remaining request quota. Your dashboard shows recorded account usage and the request rate associated with your key.
The playground uses the same request shape
In the playground, State and Questions correspond to the API fields on this page. Its guest preview has a separate limited allowance. A public API integration authenticates with your OpenJEV key; do not integrate against the playground’s internal route.
Handle failures explicitly.
| Status | Meaning | Next step |
|---|---|---|
| 401 | Authentication failed | Check the Bearer header and the API key. Fix credentials before retrying. |
| 422 | Invalid request | Check JSON syntax, required fields, question definitions, and the model alias. |
| 429 | Rate limited | Honor Retry-After when present. OpenJEV’s key limiter expresses it in seconds. Reduce concurrency. |
| 503 | Temporarily unavailable | Retry with bounded backoff and keep a fallback if the service remains unavailable. |
Unlimited access does not mean unlimited simultaneous requests. Request rate limits apply to API keys; check your dashboard for the assigned rate. The playground’s guest allowance is separate.
{ "error": "Missing field: state" }Errors from the model provider can use other HTTP statuses or an error object instead of a string. Handle network failures, non-JSON responses, and non-2xx status codes before accessing answers. Use bounded retries for transient failures; avoid retrying an unchanged invalid request.