Concepts

The request

Every call to POST /v1/systemone carries one state and one or more named questions. The model reads the state once, then answers each question from that reading. The response has one answer per question, under the same name, in the same order.

curl -s "https://api.vakyn.com/v1/systemone" \  -H "Authorization: Bearer $TYPESAFE_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "jev-latest",    "state": {      "channel": "email",      "customer": {        "plan": "team",        "seats": 12,        "months_active": 14      },      "message": "Since this morning nobody on our team can sign in. We have a client demo at 3pm."    },    "questions": {      "outage": {        "type": "noul",        "instructions": "Is the customer unable to use the product?"      },      "team": {        "type": "choice",        "instructions": "Which team should handle this?",        "criteria": {          "billing": "Invoices, charges and refunds",          "access": "Sign-in, passwords and permissions",          "product": "Bugs and how-to questions"        }      },      "urgency": {        "type": "score",        "instructions": "How soon does this need a reply?",        "criteria": [          "Can wait",          "Today",          "Within the hour"        ]      }    }  }'

{  "model": "vakyn-fake",  "answers": {    "outage": {      "type": "noul",      "noul": 0.91,      "stats": {}    },    "team": {      "type": "choice",      "choice": "access",      "confidence": 0.89,      "probabilities": {        "billing": 0.02,        "access": 0.93,        "product": 0.05      },      "stats": {}    },    "urgency": {      "type": "score",      "score": 1.86,      "legend": {        "0": "Can wait",        "1": "Today",        "2": "Within the hour"      },      "probabilities": {        "0": 0.01,        "1": 0.12,        "2": 0.87      },      "confidence": 0.79,      "stats": {}    }  },  "usage": {    "input_tokens": 112,    "output_tokens": 0  },  "assets_used": null}

State

The state is whatever you want a decision about: a support message, a contract clause, a form submission, a log line, a product listing. It can be a string, a JSON object or a JSON array, and it must not be null.

Objects and arrays are turned into indented text before the model reads them. Field names stay in as labels, so {"customer": {"plan": "team"}} is read roughly as:

customer:  plan: team

• Pass structure when you have it. A field called message next to a field called plan tells the model more than the same values glued into one sentence.
• Name fields in plain words; the names are part of what the model reads.
• Leave out what should not affect the answer (internal ids, timestamps you do not ask about). Every token of state counts toward the limits.

Questions

questions is an object: each key is a name you choose (outage, team, urgency), each value is a question with a type. The name is only a handle for your code; the model does not see it.

Instructions

instructions is the question itself, in your words. It is optional, may be a string, an object or an array, and is read together with the options. Write it as you would brief a careful colleague: one question, the decision you need, and any rule that matters ("a request for store credit counts as a refund").

Criteria

criteria describes the possible answers. Descriptions are optional for noul and choice, but they are the most effective way to steer the model: say what belongs in each option, and where the borderline cases go.

Answers

Answers are probabilities rounded to two decimals. A noul answer is a single number; choice and score answers carry the full distribution plus a confidence. Every answer also has an empty stats object, kept for compatibility. The SDKs give you typed access: result.nouls, result.choices and result.scores in Python, and answers.<name> with types inferred from your questions in JavaScript.

One reading, many questions

The state is processed once per request and every question branches off that shared reading. Asking several questions about the same state in one request is much cheaper than sending them one by one. See fan-out.