Decisions

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.

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 noul answer is a probability, not a Boolean. Choose your own threshold for each action.
A choice answer is always one of the option names you sent.
A score answer indexes your criteria array: 1 above 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_tokens and usage.output_tokens in 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

Decisions

Decisions or chatCopy Anchor Link

Choose a modelCopy Anchor Link

Request shapeCopy Anchor Link

Evaluate a ticketCopy Anchor Link

Use the answersCopy Anchor Link

Use from MCPCopy Anchor Link

Use from the SDKsCopy Anchor Link

Cost and retriesCopy Anchor Link

Common ErrorsCopy Anchor Link

API ReferenceCopy Anchor Link

On this page