Skip to main content

​
The request

A request has exactly three fields. Any other field is rejected with a 400.

​
Question names

Question names are the keys of questions and of answers in the response. A name is 1 to 64 characters of letters, digits, _ and -. Use stable, descriptive names (refund_request, severity): your code reads answers by them.

​
Instructions and criteria

Every question has a type and an optional instructions field. instructions is the question itself, in plain language. It can be a string, an object, an array or null. criteria describes the possible answers, and its shape depends on the type: Descriptions can be strings, objects, arrays or null. Score level labels can be strings, objects or arrays.

​
The three question types

​
noul: yes or no

The answer is the probability that the answer to the question is yes. Use criteria to say what counts as yes (true) and no (false) when the instructions alone leave room for doubt.
Request
Response
noul is between 0 and 1. Here the model puts the chance of shipping damage at 0.88.

​
choice: one of your options

criteria maps each option name to a description. Option names are 1 to 128 characters and must be unique. The answer names the most likely option in choice, the model’s confidence in it, and the probability of every option in probabilities, keyed by option name. The probabilities add up to 1, up to rounding.
Request
Response

​
score: a level on your scale

criteria is an ordered list of level labels, lowest first. A level’s index is its 0-based position in the list. Use at least two levels; up to 10 are allowed. The answer has:
  • score: the probability-weighted average of the level indexes, a number from 0 to the highest index.
  • confidence: the model’s confidence in the result, between 0 and 1.
  • legend: your level labels, keyed by index as a string ("0", "1", …).
  • probabilities: the probability of each level, keyed the same way.
Request
Response
Use score to rank items against each other, and probabilities when you need the chance of a specific level, such as “Product unusable”.

​
Several questions at once

Questions of all three types can share one request. The model reads the state once for all of them, and the state is billed once. The API reference shows a request with one question of each type.

​
Thresholds and confidence

The answers are probabilities, so the decision rule is yours. Pick a threshold from the cost of each kind of mistake:
  • If acting wrongly is expensive (refunding automatically, closing an account), act only on a high probability, such as noul >= 0.9, and send the rest to a person.
  • If missing a case is expensive (flagging a possible safety issue), act on a lower one, such as noul >= 0.3.
For choice, compare probabilities instead of looking at choice alone: two close options (0.48 and 0.46) mean the input is ambiguous. confidence is a quick summary of how sure the model is; when it is low, fall back to a default or a human review. Calibrate thresholds on a sample of your own data before relying on them in production.