Skip to contentKumoDocs
Sections
On this page
The gateway

Decisions

The POST /v1/systemone call — a state and questions in, answers as probabilities out, and what the call costs.

View as Markdown

Quick

A decision model does not write text. It reads a state — state — and answers your questions with probabilities: yes or no, which of several options, where on a scale. One operation takes the state and a map of questions and answers with a map of answers under the same keys. The request format is System One, the same as OpenRouter's: a client already written for it changes only the base URL.

curl https://api.kumorouter.com/v1/systemone \
  -H "Authorization: Bearer $KUMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "state": "The customer writes for the third time this week that the order has not arrived and asks for a refund.",
    "questions": {
      "refund": {
        "type": "noul",
        "instructions": "Is the customer asking for a refund?"
      },
      "topic": {
        "type": "choice",
        "instructions": "What is the request about?",
        "criteria": {
          "delivery": "delivery and timing",
          "payment": "payment and refunds",
          "other": "something else"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgently does this need an answer?",
        "criteria": ["can wait", "within the day", "right now"]
      }
    }
  }'

Request members

modelRequired. A catalog model carrying the decisions protocol, under the name the client uses for it.
stateRequired. What the model judges: a string, a JSON object or a JSON array.
questionsRequired. A non-empty object: the key is your name for the question, the value is the question. The key is how your code finds the answer.

state may be a string — an email, a message, a description — a JSON object with named fields when the state reads better in parts, or a JSON array: a list of messages, or a list of content parts such as [{"type":"text","text":"…"}], where some models also read images. The state reaches the model exactly as you sent it. Whether a given model reads images depends on the model; it is stated on its page and in the catalog.

Streaming is not part of this surface: the answer arrives whole.

Question types

Every question carries type and instructions — the judgment you ask for; the upstream refuses a question without instructions. The questions of one request are decided independently of each other.

noulYes or no: does the statement hold.
choiceWhich of several options.
scoreWhere on an ordered scale.

noul

criteria is optional: an object describing true and false, when yes and no are worth spelling out. The answer carries noul — the probability of yes, from 0 to 1.

choice

criteria is required: an object of label → description, with one label or more; a label's description may be null. The answer carries choice — the label chosen, probabilities — the probability of each label, and confidence — how settled the choice is.

score

criteria is required: a list of levels, lowest first. The answer carries score — the probability-weighted position, from 0 to the number of levels minus one; legend — each level's number and text; probabilities — the probability of each level; and confidence.

The response

idThe call's identifier.
modelThe model that answered.
answersOne answer per question, under the question's own key; `type` repeats the question's type.
usage`input_tokens` — the call's input tokens; `output_tokens` is always `0`.
{
  "id": "dec-<request id>",
  "model": "<model>",
  "answers": {
    "refund": { "type": "noul", "noul": 0.97 },
    "topic": {
      "type": "choice",
      "choice": "payment",
      "confidence": 0.81,
      "probabilities": { "delivery": 0.17, "payment": 0.82, "other": 0.01 }
    },
    "urgency": {
      "type": "score",
      "score": 1.62,
      "confidence": 0.58,
      "legend": { "0": "can wait", "1": "within the day", "2": "right now" },
      "probabilities": { "0": 0.04, "1": 0.3, "2": 0.66 }
    }
  },
  "usage": { "input_tokens": 412, "output_tokens": 0 }
}

What the call costs

Billing counts input tokens only: a decision model has an input price and no output price, so output_tokens in the answer is always zero and the ledger records zero for it. What a million input tokens of a given model cost is stated in the price list.

Which models answer

Only a model whose published catalog entry carries the decisions protocol answers here; its modality in the catalog is Decisions. A model of another protocol is refused on this surface, just as a decision model is refused on the chat surfaces.

The model catalog → The price list →

Next

Errorsthe refusal envelope and this operation's status codes.Rate limitsthe request and token ceilings.API referencethe operation member by member, straight from the API description.
Previous
Images
Next
Streaming