Jev API request schema
Every first-party Jev request is the same three top-level fields. This page is the request half of the API shape. Confirm types on docs.typesafe.ai/api. Independent unofficial notes; we do not issue keys.
Top-level fields
| Field | Required | Allowed shapes | Failure if wrong |
|---|---|---|---|
state |
yes | string; JSON object; array of text | 422; also accuracy loss if you dump unrelated fields (jev-1.13 jaggedness) |
model |
yes | alias or versioned id | 422 if omitted; “unknown model” if the door rejects the string |
questions |
yes | object, ≥1 entry | 422 |
English is the primary training language (models page). Pre-process images/audio/video to text before state.
Question object
Shared:
| Field | Required | Notes |
|---|---|---|
type |
yes | noul, choice, or score (lowercase in HTTP examples) |
instructions |
yes | string or object or array. Point at nested state with backtick paths: `ticket.body` |
criteria |
Choice/Score yes; Noul optional | Must align with instructions (jaggedness: contradictory true/false labels hurt) |
Choice criteria: { "billing": "Payments…", "other": "None of the above" } — max 255 keys, values may be null if no extra gloss.
Score criteria: ["Calm", "Frustrated", "Very angry"] — 2–10 descriptive levels, not raw numbers you later interpolate (official warning).
Noul criteria: { "true": "…", "false": "…" }.
The map key ("department") is your code id. TypeSafe: it is not used in inference.
Structured instructions (official pattern)
{
"state": { "resume": "…" },
"model": "jev-1.13.0",
"questions": {
"same_person": {
"type": "noul",
"instructions": {
"potential_duplicate": {
"name": "John Smith",
"location": "Oakland, California"
},
"question": "Is the resume for the same person as `potential_duplicate`?"
}
}
}
}Pin jev-1.13.0 in production once thresholds exist. jev-latest is the docs default and can move. Unpatched jev-1.13 is a different string than the versioned id — see decision endpoint.
Minimal valid bodies
Noul only (quick start):
{
"state": "Help! My payouts have been failing for 3 days.",
"model": "jev-latest",
"questions": {
"is_urgent": {
"type": "noul",
"instructions": "Does this convey urgency?"
}
}
}Gateway/OpenRouter/Workers AI may wrap or rename fields (boolean, input). Those are not this schema. Compare channels.
FAQ
Can instructions reference criteria keys?
Write the question so a person could answer in seconds. Put contrast in criteria. Do not hide a second judgment in one string.
Array state? Yes — official state docs allow an array of text (for example chat turns). Still filter distractors.
Hub: API. Siblings: decision endpoint, response shape.
Sources
Public TypeSafe or adjacent documentation only. No private claims.