Skip to content
EASYJEV

POST /v1/systemone

Complete reference for the judgment endpoint: model/state/questions fields, the three question types (noul, choice, score), processing semantics, response shape and pass-through upstream errors.

Request fields

FieldTypeRequiredDescription
modelstringYesModel name as returned by GET /v1/models, e.g. typesafe/jev-latest. Legacy bare names (jev-latest, jev-1.13.0) still work via alias normalization.
statestring / object / arrayYesThe content being judged. Free-form: a question, a ticket, a product record — anything the questions refer to.
questionsobjectYesMap of {question_id: question_def}. At least one entry; ids are echoed back in the response.
(others)anyNoUnknown fields pass through to the upstream unchanged (forward compatibility).
JSON · request body
{
  "model": "typesafe/jev-latest",
  "state": "User asks: can I get a refund for order #1024?",
  "questions": {
    "refund": {"type": "noul", "instructions": "Is this a refund request?"},
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this?",
      "criteria": ["low", "normal", "high"]
    }
  }
}

Question types

TypetypeRequired fieldsReturns
Yes/nonoul—Probability of “yes” in [0,1]; optional criteria.true/false descriptions.
Single choicechoicecriteriaMap of option name → description (≤255 options, description may be null); returns the pick plus per-option probabilities.
Ordinal scorescorecriteriaOrdered array of 2–10 levels; returns a value that interpolates between levels.

instructions is optional on every question type and accepts a string, object or array. Images can be attached via assets — see Images & Multimodal Assets.

Processing semantics (in order)

  1. 1. Request-size limits (single media 50 MB; total: multipart 60 MB / JSON 70 MB) → 413
  2. 2. Minimal structure check — missing model/state/questions → 422
  3. 3. Model whitelist (after alias normalization) — unknown model → 404, not forwarded
  4. 4. Per-key rate limits (default 600 RPM / 4,500,000 TPM) → 429
  5. 5. Balance pre-check — zero or negative balance → 402 (a call may settle into the negative once)
  6. 6. Upstream forwarding with failover: up to 3 channel+key attempts (401 auto-disables a key, 429 cools down, 5xx/network errors fail over)
  7. 7. Billing on 200 only: input tokens × input price + output tokens × output price, settled exactly against upstream usage; failed calls are free
  8. 8. Every call (success or failure) is logged with a request_id returned in response headers

Success response

The 200 body is the upstream response passed through unchanged (unknown fields included). usage is the billing meter: only input_tokens / output_tokens / cost (when the upstream returns it) are exposed.

JSON · 200 OK
{
  "model": "typesafe/jev-latest",
  "answers": {
    "refund": {
      "type": "noul",
      "noul": 0.97,
      "confidence": 0.93
    },
    "urgency": {
      "type": "score",
      "score": 1.4,
      "confidence": 0.88
    }
  },
  "usage": {"input_tokens": 1234, "output_tokens": 0}
}

Response headers

Every response (success or error) carries X-Request-Id and x-typesafe-request-id with the same value — use it for reconciliation and when contacting support; the official SDK also surfaces it as resp.request_id.

Upstream pass-through

Upstream validation failures (400 / 404 / 413 / 422) are passed through unchanged — the body is the upstream’s error JSON, not the gateway envelope — and are never billed. All other failures use the unified gateway error shape.