API reference

System One

POST /v1/systemone asks a decision model typed questions about a state and answers with probabilities, choices and scores.

POSThttps://gateway.kalsenti.ai/v1/systemone
On this page

Request body

A decision model answers typed questions about something you send it, with numbers rather than prose: a probability, a choice from a list, a score, or a box in an image. It never writes an explanation, which is what makes its answer safe to branch on in code.

Send POST /v1/systemone with a model, a state and one or more questions. The state is what every question refers to: a string, an object or an array, so a message, a ticket and the relevant records can go together.

curl
curl https://gateway.kalsenti.ai/v1/systemone \
  -H "Authorization: Bearer $KALSENTI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "jev-latest", "state": "I was charged twice for this month’s invoice. Please refund the extra charge.", "questions": { "billing": { "type": "noul", "instructions": "Is this message about billing?" } } }'
FieldWhat it is
modelThe model to ask, from GET /v1/models.
stateThe content the questions are about. A string, an object or an array.
questionsNamed questions, 1 to 64 in one request. The names come back on the answers.
assetsImages the state refers to, as base64. Optional; only a model that reads images can use them.
imagesThe same images as a plain list of URLs or data URIs, for a model that takes them that way rather than by asset name.

Questions

Each question has a type and, usually, instructions. The type decides the shape of its answer, and the four types can be mixed in one request.

TypeAsksAnswer
noulWhether something is true, in plain words.Probability from 0 to 1: { "type": "noul", "noul": 0.98 }.
choiceWhich of the options you list applies.The option's name: { "type": "choice", "choice": "angry" }.
scoreWhere the content sits on an ordered scale.A number on that scale: { "type": "score", "score": 1.4 }.
boxWhere something is in an image.Four edges as fractions of the image's width and height.

A choice carries its options in criteria, as names mapped to a description of when each applies; a name without a description is read by its name alone. A score carries its levels as a list, in order, and the answer's number counts from 0 at the first level.

A choice question
{
  "tone": {
    "type": "choice",
    "instructions": "What is the tone of this message?",
    "criteria": {
      "angry": "An upset or hostile message",
      "calm": "A neutral or polite message",
      "excited": "An enthusiastic or eager message"
    }
  }
}
A score question
{
  "urgency": {
    "type": "score",
    "instructions": "How urgent is this message?",
    "criteria": ["Can wait", "Needs attention this week", "Needs attention today"]
  }
}

Ask independent questions together. They are answered in one run over the same state, which is cheaper and no slower than asking one at a time.

Answers

Answers come back under the names you gave the questions, with the model that answered and the token usage that was charged for. The model name in the answer can differ from the one you sent when a model has an alias.

Response
{
  "model": "jev-latest",
  "answers": {
    "billing": { "type": "noul", "noul": 0.98 },
    "tone": { "type": "choice", "choice": "angry" },
    "urgency": { "type": "score", "score": 1.4 }
  },
  "usage": { "input_tokens": 120, "output_tokens": 12 }
}

Some types also return a confidence with the answer, so code can decide when to act and when to send the case to a person. Only the fields the model's own documentation lists are present; nothing else is added.

Not supported

WhatWhat happens
streamRefused with a 400. An answer is a handful of numbers, so it arrives whole.
Sampling fields such as temperature, max_tokens or toolsRefused with a 400 naming the field, rather than ignored: a decision is not a completion.
More than 64 questions, or a choice with more than 255 optionsRefused with a 400.
A model with no decision routeAnswered 503. Only a model built for decisions can answer this endpoint.

Requests are charged like any other: from the token usage in the answer, at the model's prices on the Models page. An ordinary chat model cannot be called here, and a decision model cannot be called on chat completions.