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
| Field | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Model 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. |
| state | string / object / array | Yes | The content being judged. Free-form: a question, a ticket, a product record — anything the questions refer to. |
| questions | object | Yes | Map of {question_id: question_def}. At least one entry; ids are echoed back in the response. |
| (others) | any | No | Unknown fields pass through to the upstream unchanged (forward compatibility). |
{
"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
| Type | type | Required fields | Returns |
|---|---|---|---|
| Yes/no | noul | — | Probability of “yes” in [0,1]; optional criteria.true/false descriptions. |
| Single choice | choice | criteria | Map of option name → description (≤255 options, description may be null); returns the pick plus per-option probabilities. |
| Ordinal score | score | criteria | Ordered 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. Request-size limits (single media 50 MB; total: multipart 60 MB / JSON 70 MB) → 413
- 2. Minimal structure check — missing model/state/questions → 422
- 3. Model whitelist (after alias normalization) — unknown model → 404, not forwarded
- 4. Per-key rate limits (default 600 RPM / 4,500,000 TPM) → 429
- 5. Balance pre-check — zero or negative balance → 402 (a call may settle into the negative once)
- 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. Billing on 200 only: input tokens × input price + output tokens × output price, settled exactly against upstream usage; failed calls are free
- 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.
{
"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.