Core Guides
Decisions
Get typed probabilities, choices, and scores from a decision model
POST /v1/systemone evaluates one state against named questions and returns one typed answer per question. The response is synchronous JSON: a probability, an option name, or a score that your code can compare and branch on. It does not return generated text.
Decisions or chat
| Use decisions when | Use chat when |
|---|---|
| Your code needs a number or a label to act on | A person or another model reads the answer |
| You route, classify, or gate a request: refund or not, which team, how urgent | You need explanations, summaries, or drafted text |
| You ask several fixed questions about the same input in one call | You need tools, streaming, images, or multi-turn messages |
The decision endpoint does not accept messages, tools, stream, or other chat controls, and it is not available in Batch. Keep your main chat model configured separately.
Choose a model
curl "https://api.tokenlab.sh/v1/models?recommended_for=decision" \
-H "Authorization: Bearer sk-your-api-key"You can also filter with category=decision. Read GET /v1/models/{model} for the selected model before you send requests, and send the model ID explicitly. The examples on this page use jev-1.13.
Jev has two versions:
| Model ID | Stage | Request alias |
|---|---|---|
jev-1.14 | Active | jev-latest, jev-preview |
jev-1.13 | Active | — |
jev-1.14 is TypeSafe's current stable Jev release. Since November 5, 2026, jev-latest reaches it, as it does at TypeSafe, and jev-preview also reaches it. jev-1.13 stays available by its exact ID. Both versions take the same request and read text only. An alias can point to another version later, so send the exact model ID after you tune thresholds on a version, and compare the answers of the two versions on your own labeled cases before you switch.
Request shape
| Field | Type | Notes |
|---|---|---|
model | string | Decision model ID |
state | string, JSON object, or JSON array | The input to evaluate, such as a ticket, a transcript, or a record |
questions | object | At least one question. Each key is your question name; each value has type, instructions, and criteria |
instructions and each criterion also accept a string, JSON object, or JSON array. The request rejects unknown fields.
type | criteria | Answer |
|---|---|---|
noul | Optional. An object with both true and false guidance | noul: a probability from 0 to 1 that the statement is true |
choice | Required. An object of 1–255 option names, each mapped to guidance or null | choice: one of your option names. Can include probabilities and confidence |
score | Required. An ordered array of 2–10 level descriptions | score: a number from 0 to the last array index; it can be fractional. Can include legend, probabilities, and confidence |
Evaluate a ticket
curl https://api.tokenlab.sh/v1/systemone \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "jev-1.13",
"state": "I was charged twice. Please refund the duplicate payment.",
"questions": {
"refund_requested": {"type": "noul", "instructions": "Is a refund requested?"},
"department": {
"type": "choice", "instructions": "Which team should handle this?",
"criteria": {"refunds": "Charges and refunds", "technical": "Software bugs"}
},
"urgency": {
"type": "score", "instructions": "Rate urgency",
"criteria": ["Routine enquiry", "Money affected", "Safety emergency"]
}
}
}'The response keeps your question names under answers. Values below are illustrative:
{
"model": "jev-1.13",
"answers": {
"refund_requested": {"type": "noul", "noul": 0.97},
"department": {"type": "choice", "choice": "refunds"},
"urgency": {"type": "score", "score": 1}
},
"usage": {"input_tokens": 96, "output_tokens": 12}
}Use the answers
- Every question gets an answer of the same
type, under the same name. - A
noulanswer is a probability, not a Boolean. Choose your own threshold for each action. - A
choiceanswer is always one of the option names you sent. - A
scoreanswer indexes yourcriteriaarray:1above means "Money affected". - Test decisions against your own labeled cases before they drive refunds, escalations, or other actions.
Use from MCP
The TokenLab MCP server exposes evaluate_decisions in the core and full profiles. Call list_models with {"category":"decision"} and get_model first, then pass the same model, state, and questions as tool arguments. Read structuredContent.answers and structuredContent.usage from the result. The tool returns a synchronous result and does not use async task polling.
Use from the SDKs
TokenLab JavaScript SDK 0.1.2+ provides evaluateDecisions(body); Python SDK 0.1.2+ provides evaluate_decisions(body). The body is the same JSON as the HTTP request. Both preserve typed answers and usage and do not automatically replay a failed request. See SDKs.
Cost and retries
- Decisions are charged by tokens, from the
usage.input_tokensandusage.output_tokensin the response, at the model's current token prices. - Prices can change. Read the model's pricing detail or the Pricing API instead of hard-coding a price.
- A model can report output tokens even when its output price is zero.
- Requests follow your delivery option. See Billing and pricing.
- A timeout leaves the outcome uncertain. Check the request in your logs or Console before you send a paid request again.
Common Errors
| Symptom | Likely cause | Fix |
|---|---|---|
400 on a field such as messages or stream | Chat fields are not part of this endpoint | Send only model, state, and questions |
400 on criteria | A choice has 0 or more than 255 options, a score has fewer than 2 or more than 10 levels, or a noul object lacks true or false | Fix the question definition |
| Actions fire on weak signals | A noul probability was treated as true or false | Compare against a threshold that you tested |
API Reference
| Topic | Reference |
|---|---|
| Evaluate Decisions | Evaluate Decisions |
| List Models | List Models |
| Pricing | Pricing API |
| Billing & Pricing | Billing & Pricing |