API reference
System One
POST /v1/systemone asks a decision model typed questions about a state and answers with probabilities, choices and scores.
https://gateway.kalsenti.ai/v1/systemoneOn 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 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?" } } }'| Field | What it is |
|---|---|
model | The model to ask, from GET /v1/models. |
state | The content the questions are about. A string, an object or an array. |
questions | Named questions, 1 to 64 in one request. The names come back on the answers. |
assets | Images the state refers to, as base64. Optional; only a model that reads images can use them. |
images | The 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.
| Type | Asks | Answer |
|---|---|---|
noul | Whether something is true, in plain words. | Probability from 0 to 1: { "type": "noul", "noul": 0.98 }. |
choice | Which of the options you list applies. | The option's name: { "type": "choice", "choice": "angry" }. |
score | Where the content sits on an ordered scale. | A number on that scale: { "type": "score", "score": 1.4 }. |
box | Where 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.
{
"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"
}
}
}{
"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.
{
"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
| What | What happens |
|---|---|
stream | Refused with a 400. An answer is a handful of numbers, so it arrives whole. |
Sampling fields such as temperature, max_tokens or tools | Refused 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 options | Refused with a 400. |
| A model with no decision route | Answered 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.