Decisions/Jev
Evaluate State with typed Questions and receive structured decision results.
Access and authentication
Open Decisions/Jev Playground, sign in, add State and Questions, then select Run. Examples fill the editors without running a request.
POST /api/decisions/run is a session-authenticated Playground endpoint. It requires a verified Qufas login cookie and a same-origin browser request. It is not a public API-key endpoint: a Qufas bearer API key alone does not authenticate this route. External SDK, cURL and cross-origin calls are not supported by this interface.
The server reads JEV_API_KEY and calls TypeSafe. This secret must never be included in browser code or a request body. Missing server configuration returns 503. No public /v1/decisions endpoint is implemented.
Request and primitives
Use model: "jev-latest". State and Questions must be JSON objects. Send parsed objects, not strings containing JSON. Jev returns one response; streaming and chat parameters are not supported.
1{2 "model": "jev-latest",3 "state": {4 "message": "My card was charged twice and I need this fixed today."5 },6 "questions": {7 "department": {8 "type": "choice",9 "instructions": "Which department should handle this request?",10 "criteria": {11 "billing": "Payments, invoices or refunds",12 "technical": "Technical or API problems",13 "sales": "Pricing or purchasing questions"14 }15 },16 "urgent": {17 "type": "noul",18 "instructions": "Does this request require urgent attention?"19 },20 "frustration": {21 "type": "score",22 "instructions": "How frustrated does the customer appear?",23 "criteria": [24 "Calm",25 "Somewhat frustrated",26 "Very frustrated"27 ]28 }29 }30}- Noul: a proposition evaluated as a probability of being true.
- Choice: a named criteria object with at least two nonempty string descriptions.
- Score: an ordered criteria array with at least two nonempty string descriptions. Levels start at zero.
Questions must contain at least one entry. Each entry requires a supported type and nonempty string instructions. Both the browser and server validate these rules. The request body is limited to 256 KB. Provider-specific constraints can also reject an otherwise valid request.
Call the Playground API
This example runs inside a signed-in Qufas page on the same origin. Your browser supplies the Origin header and session cookie.
1// Run from a signed-in Qufas page on the same origin.2// Your session cookie is sent automatically. No provider key belongs here.3const request = {4 "model": "jev-latest",5 "state": {6 "message": "My card was charged twice and I need this fixed today."7 },8 "questions": {9 "department": {10 "type": "choice",11 "instructions": "Which department should handle this request?",12 "criteria": {13 "billing": "Payments, invoices or refunds",14 "technical": "Technical or API problems",15 "sales": "Pricing or purchasing questions"16 }17 },18 "urgent": {19 "type": "noul",20 "instructions": "Does this request require urgent attention?"21 },22 "frustration": {23 "type": "score",24 "instructions": "How frustrated does the customer appear?",25 "criteria": [26 "Calm",27 "Somewhat frustrated",28 "Very frustrated"29 ]30 }31 }32};33 34const response = await fetch("/api/decisions/run", {35 method: "POST",36 credentials: "same-origin",37 headers: { "Content-Type": "application/json" },38 body: JSON.stringify(request),39 signal: AbortSignal.timeout(65000),40});41const body = await response.json();42 43if (!response.ok) {44 // For 429, wait this many seconds before offering a manual retry.45 const retryAfter = response.headers.get("Retry-After");46 console.error(body.error.type, body.error.message, {47 requestId: body.error.request_id,48 upstreamRequestId: body.error.upstream_request_id,49 retryAfter,50 });51} else {52 console.log(body.answers, body.usage, body.qufas);53}Response
The following values are illustrative, not measured usage or a price quote. Raw view preserves the upstream JSON and adds Qufas metadata.
1{2 "model": "jev-1.13.0",3 "answers": {4 "department": {5 "type": "choice",6 "choice": "billing",7 "probabilities": {8 "billing": 0.9,9 "technical": 0.06,10 "sales": 0.0411 },12 "confidence": 0.813 },14 "urgent": {15 "type": "noul",16 "noul": 0.9217 },18 "frustration": {19 "type": "score",20 "score": 1.62,21 "probabilities": {22 "0": 0.05,23 "1": 0.28,24 "2": 0.6725 },26 "legend": {27 "0": "Calm",28 "1": "Somewhat frustrated",29 "2": "Very frustrated"30 },31 "confidence": 0.7832 }33 },34 "usage": {35 "input_tokens": 312,36 "output_tokens": 4837 },38 "qufas": {39 "request_id": "decision_example",40 "latency_ms": 183,41 "provider": "typesafe",42 "upstream_status": 200,43 "upstream_request_id": "upstream_example"44 }45}answers uses the same keys as Questions. Choice returns the selected option and its distribution; Score returns the expected level, distribution and legend. Both may report confidence. Noul's noul value is true probability, not confidence.
Model and token counts come from the provider. qufas.latency_ms measures the server-side call including retries; qufas.request_id identifies the Qufas request. Validated upstream request IDs are included when available.
Errors and retries
Only HTTP 529 triggers overload retries: wait about 500 ms, retry once, then about 1500 ms and retry a second time. Each delay includes up to 100 ms of jitter. There are at most three attempts total. Success stops retries immediately. All attempts and delays share one 60-second deadline; client cancellation stops subsequent attempts.
401 and 422 are not retried. 429 does not enter the overload retry loop. Valid Retry-After seconds or HTTP dates are normalized to seconds in the response header and error.retry_after_seconds. The Playground disables Run for that period. When absent, no cooldown is inferred.
| Status | Type | Action |
|---|---|---|
| 400 | invalid_json / validation_error | Fix JSON, model, instructions or criteria before retrying. |
| 401 | authentication_error | Sign in to Qufas. |
| 403 | invalid_origin | Call from a Qufas page on the same origin. |
| 413 | request_too_large | Reduce the JSON body to at most 256 KB. |
| 422 | provider_error | The provider rejected the request. Review its input; no automatic retry. |
| 429 | rate_limit | Honor Retry-After when present. No automatic overload retry. |
| 502 | provider_authentication_error / provider_error / connection_error / invalid_response | Provider authentication, connection, response or server failure. Upstream 401/403 is mapped to 502. |
| 503 | not_configured / authentication_unavailable | Server configuration or session verification is unavailable. |
| 504 | timeout | The request was interrupted or exceeded the shared deadline. |
| 529 | provider_overloaded | Jev is experiencing high traffic. Two bounded retries were exhausted. |
1{2 "error": {3 "type": "provider_overloaded",4 "status": 529,5 "message": "Jev is currently experiencing high traffic. Please try again shortly.",6 "request_id": "decision_example",7 "provider": "typesafe",8 "upstream_status": 529,9 "upstream_request_id": "upstream_example"10 }11}Error metadata retains only the provider name, upstream status and validated upstream request ID. Raw provider error bodies, API keys, internal stack traces and sensitive headers are not returned.
Usage and billing
The current standalone Playground does not debit Qufas balances or perform Qufas billing reservations or settlement. Failed attempts never contribute usage or charge. If every attempt fails, the Qufas user is not charged. If an attempt succeeds, only that successful response's usage is returned.
Charge is displayed only when an explicit numeric USD charge is returned; it is never inferred from token counts. Provider account charges belong to the server-owned TypeSafe key and are subject to the provider's billing policy. Per-user quotas and Qufas billing are not implemented for this Playground.
Was this page helpful?