Open System OneReference
The schemas of the 2026-11-07 release. Download it asopenapi/2026-11-07.json, or see theworking draft.
SystemOneRequest
Content and named questions to evaluate together.
| Property | Type | Required | Description |
|---|---|---|---|
model | string | yes | Name or alias of the model to use. |
state | SystemOneContent | yes | The content all questions in this request refer to: a string, or structured data as an object or array. |
questions | map of SystemOneQuestion | yes | Questions about the state, each under a name you choose. The response uses the same names for the answers. |
assets | map of SystemOneAsset | Media assets keyed by an opaque placeholder, such as a per-image UUID. Each placeholder, wherever it appears as or inside a string in state, question instructions, or criteria, is replaced with the asset. The placeholder's position is a hint: an implementer may present assets before the state instead. Image assets require a model that accepts images. | |
reference_date | string | The date that relative dates in the state are resolved against, as YYYY-MM-DD. A server that cannot honor it rejects the request with unsupported_parameter. |
SystemOneResponse
Answers keyed by question name, with the model used and token usage.
| Property | Type | Required | Description |
|---|---|---|---|
model | string | yes | Name of the model that answered. May differ from the alias in the request. |
answers | map of SystemOneAnswer | yes | Answers keyed by the question names in the request. Each answer's type matches its question's type. |
usage | SystemOneUsage | yes | |
truncated | boolean | Whether the server shortened the state to fit the model's context. Present whenever the server knows. A server may instead reject oversized input with an error of its own. | |
state_text | string | The text the model read, when it differs from the state as sent, for example when structured state is serialized to text, or only the portion the model read when truncated is true. Answer spans index into state_text when it is present. |
SystemOneUsage
Token usage for the request.
| Property | Type | Required | Description |
|---|---|---|---|
input_tokens | integer | yes | Number of input tokens used to evaluate the request. |
output_tokens | integer | yes | Number of output tokens used to answer the questions. |
SystemOneContent
Text or structured data: a string, an object, or an array.
Type: string | object | array of any
SystemOneAsset
An image that replaces its placeholder: its bytes in data_base64 with their format, or, in a multipart request, the name of the image part that holds them.
| Property | Type | Required | Description |
|---|---|---|---|
type | "image" | Identifies an image asset. | |
format | "png" | "jpg" | "jpeg" | "webp" | The image format, required with data_base64. | |
data_base64 | string | Base64-encoded image data. | |
part | string | In a multipart request, the name of the image part this asset uses. With part, data_base64 is ignored. |
SystemOneQuestion
A question about the state: a core question, or an extension question whose type is named owner:type. The type selects the question shape and the answer shape.
SystemOneCoreQuestion
A question of a core type. Decision types are noul, choice, score, and box; extraction types are text, number, date, time, datetime, duration, list, estimate, and forecast.
Type: NoulQuestion | ChoiceQuestion | ScoreQuestion | BoxQuestion | TextQuestion | NumberQuestion | DateQuestion | TimeQuestion | DateTimeQuestion | DurationQuestion | ListQuestion | EstimateQuestion | ForecastQuestion
SystemOneAnswer
An answer whose type matches its question's type: a core answer, or an extension answer.
Type: SystemOneCoreAnswer | ExtensionAnswer
SystemOneCoreAnswer
An answer of a core type.
Type: NoulAnswer | ChoiceAnswer | ScoreAnswer | BoxAnswer | TextAnswer | NumberAnswer | DateAnswer | TimeAnswer | DateTimeAnswer | DurationAnswer | ListAnswer | EstimateAnswer | ForecastAnswer
NoulQuestion
A yes/no question or statement, answered with the probability of yes or true.
| Property | Type | Required | Description |
|---|---|---|---|
type | "noul" | yes | |
instructions | SystemOneContent | null | The yes/no question or statement to evaluate. | |
criteria | NoulCriteria | null | What counts as a yes or a no answer. |
NoulCriteria
Criteria defining what counts as a yes or a no answer.
| Property | Type | Required | Description |
|---|---|---|---|
true | SystemOneContent | null | What counts as a yes answer. | |
false | SystemOneContent | null | What counts as a no answer. |
NoulAnswer
The probability of a yes answer or a true statement.
| Property | Type | Required | Description |
|---|---|---|---|
type | "noul" | yes | |
noul | SystemOneProbability | yes | Probability of a yes answer or a true statement, from 0 to 1. |
ChoiceQuestion
A question that selects one option from the choices in criteria.
| Property | Type | Required | Description |
|---|---|---|---|
type | "choice" | yes | |
instructions | SystemOneContent | null | What to decide when choosing an option. | |
criteria | map of SystemOneContent | null | yes | Choice names mapped to descriptions of when each applies. A choice without a description is interpreted by its name alone. |
ChoiceAnswer
The selected choice, confidence, and the probability of each choice.
| Property | Type | Required | Description |
|---|---|---|---|
type | "choice" | yes | |
choice | string | yes | The name of the selected choice, one of the question's criteria. Normally the choice with the highest probability. |
confidence | SystemOneProbability | yes | Confidence in the selected choice, from 0 to 1. |
probabilities | map of SystemOneProbability | yes | Probability of each choice, keyed by choice name. Values sum to approximately 1. |
ScoreQuestion
A question that rates the state on an ordered rubric.
| Property | Type | Required | Description |
|---|---|---|---|
type | "score" | yes | |
instructions | SystemOneContent | null | What to rate. | |
criteria | array of SystemOneContent | yes | Ordered descriptions of the score levels, lowest first. Each description's position is its score, starting at zero. |
ScoreAnswer
An expected score with its rubric, confidence, and the probability of each level.
| Property | Type | Required | Description |
|---|---|---|---|
type | "score" | yes | |
score | number | yes | Expected score: the probability-weighted average of the levels. May fall between levels. |
confidence | SystemOneProbability | yes | Confidence in the score, from 0 to 1. |
legend | map of SystemOneContent | yes | The question's criteria keyed by their score level. |
probabilities | map of SystemOneProbability | yes | Probability of each score level, using the same keys as legend. Values sum to approximately 1. |
BoxQuestion
A question that locates what its instructions describe in the request's image.
| Property | Type | Required | Description |
|---|---|---|---|
type | "box" | yes | |
instructions | SystemOneContent | null | What to locate in the image. |
BoxAnswer
A located box with normalized edge coordinates and confidence.
| Property | Type | Required | Description |
|---|---|---|---|
type | "box" | yes | |
box | BoxCoordinates | yes | |
confidence | SystemOneProbability | null | yes | Confidence in the box, from 0 to 1. Null when the model does not provide confidence. |
BoxCoordinates
Box edges as fractions of the image's height and width, from 0 to 1. Vertical edges are measured from the top; horizontal edges from the left.
| Property | Type | Required | Description |
|---|---|---|---|
top | SystemOneFraction | yes | |
bottom | SystemOneFraction | yes | |
left | SystemOneFraction | yes | |
right | SystemOneFraction | yes |
TextQuestion
A question answered with text copied from the state, such as a name or an ID.
| Property | Type | Required | Description |
|---|---|---|---|
type | "text" | yes | |
instructions | SystemOneInstructions | ||
null_threshold | SystemOneNullThreshold |
TextAnswer
Text copied from the state. value is null when p_null is above the question's null_threshold, and not null otherwise. When span is not null, the text it covers equals guess.
| Property | Type | Required | Description |
|---|---|---|---|
type | "text" | yes | |
value | string | null | yes | The text, or null when the state does not determine it. |
guess | string | The most likely text, present even when value is null. | |
span | SystemOneSpan | null | Where guess was read in the state text. Absent or null when guess was not read from the state text, for example when it was read from an image or computed. | |
p_null | SystemOneProbability | yes | Probability that the state does not determine a value. |
confidence | SystemOneProbability | yes | Confidence in guess, from 0 to 1. |
NumberQuestion
A question answered with a number read or computed from the state.
| Property | Type | Required | Description |
|---|---|---|---|
type | "number" | yes | |
instructions | SystemOneInstructions | ||
unit | SystemOneUnitLabel | ||
integer | SystemOneInteger | ||
decimals | SystemOneDecimals | ||
null_threshold | SystemOneNullThreshold |
NumberAnswer
A number that honors the question's integer and decimals settings. value is null when p_null is above the question's null_threshold, and not null otherwise.
| Property | Type | Required | Description |
|---|---|---|---|
type | "number" | yes | |
value | number | null | yes | The number, or null when the state does not determine it. |
guess | number | The most likely number, present even when value is null. | |
span | SystemOneSpan | null | Where guess was read in the state text. Absent or null when guess was not read from the state text, for example when it was read from an image or computed. | |
p_null | SystemOneProbability | yes | Probability that the state does not determine a value. |
confidence | SystemOneProbability | yes | Confidence in guess, from 0 to 1. |
DateQuestion
A question answered with a calendar date read or computed from the state. Dates written without a year are resolved against the request's reference_date when present.
| Property | Type | Required | Description |
|---|---|---|---|
type | "date" | yes | |
instructions | SystemOneInstructions | ||
null_threshold | SystemOneNullThreshold |
DateAnswer
A calendar date as YYYY-MM-DD. value is null when p_null is above the question's null_threshold, and not null otherwise.
| Property | Type | Required | Description |
|---|---|---|---|
type | "date" | yes | |
value | string | null | yes | The date, or null when the state does not determine it. |
guess | string | The most likely date, present even when value is null. | |
span | SystemOneSpan | null | Where guess was read in the state text. Absent or null when guess was not read from the state text, for example when it was read from an image or computed. | |
p_null | SystemOneProbability | yes | Probability that the state does not determine a value. |
confidence | SystemOneProbability | yes | Confidence in guess, from 0 to 1. |
TimeQuestion
A question answered with a time of day read or computed from the state.
| Property | Type | Required | Description |
|---|---|---|---|
type | "time" | yes | |
instructions | SystemOneInstructions | ||
null_threshold | SystemOneNullThreshold |
TimeAnswer
A time of day as HH:MM or HH:MM:SS, 24-hour, without a time zone. value is null when p_null is above the question's null_threshold, and not null otherwise.
| Property | Type | Required | Description |
|---|---|---|---|
type | "time" | yes | |
value | SystemOneTime | null | yes | The time, or null when the state does not determine it. |
guess | SystemOneTime | The most likely time, present even when value is null. | |
span | SystemOneSpan | null | Where guess was read in the state text. Absent or null when guess was not read from the state text, for example when it was read from an image or computed. | |
p_null | SystemOneProbability | yes | Probability that the state does not determine a value. |
confidence | SystemOneProbability | yes | Confidence in guess, from 0 to 1. |
DateTimeQuestion
A question answered with a date and time read or computed from the state.
| Property | Type | Required | Description |
|---|---|---|---|
type | "datetime" | yes | |
instructions | SystemOneInstructions | ||
null_threshold | SystemOneNullThreshold |
DateTimeAnswer
An ISO 8601 date and time, YYYY-MM-DDTHH:MM[:SS[.fraction]], with a UTC offset only when the state gives one. value is null when p_null is above the question's null_threshold, and not null otherwise.
| Property | Type | Required | Description |
|---|---|---|---|
type | "datetime" | yes | |
value | SystemOneDateTime | null | yes | The date and time, or null when the state does not determine it. |
guess | SystemOneDateTime | The most likely date and time, present even when value is null. | |
span | SystemOneSpan | null | Where guess was read in the state text. Absent or null when guess was not read from the state text, for example when it was read from an image or computed. | |
p_null | SystemOneProbability | yes | Probability that the state does not determine a value. |
confidence | SystemOneProbability | yes | Confidence in guess, from 0 to 1. |
DurationQuestion
A question answered with a length of time, as a number in the chosen unit.
| Property | Type | Required | Description |
|---|---|---|---|
type | "duration" | yes | |
instructions | SystemOneInstructions | ||
unit | SystemOneDurationUnit | ||
integer | SystemOneInteger | ||
decimals | SystemOneDecimals | ||
null_threshold | SystemOneNullThreshold |
DurationAnswer
A length of time as a number in the question's unit, honoring its integer and decimals settings. value is null when p_null is above the question's null_threshold, and not null otherwise.
| Property | Type | Required | Description |
|---|---|---|---|
type | "duration" | yes | |
value | number | null | yes | The duration, or null when the state does not determine it. |
guess | number | The most likely duration, present even when value is null. | |
unit | SystemOneDurationUnit | The unit of value and guess, the same as the question's. | |
span | SystemOneSpan | null | Where guess was read in the state text. Absent or null when guess was not read from the state text, for example when it was read from an image or computed. | |
p_null | SystemOneProbability | yes | Probability that the state does not determine a value. |
confidence | SystemOneProbability | yes | Confidence in guess, from 0 to 1. |
ListQuestion
A question answered with every matching item in the state.
| Property | Type | Required | Description |
|---|---|---|---|
type | "list" | yes | |
instructions | SystemOneInstructions | ||
items | "text" | "number" | "date" | yes | The type of each item, with the same format as the answer of that type. |
decimals | SystemOneDecimals | Number of decimal places for number items, from 0 to 6. |
ListAnswer
The matching items in the order they appear in the input. Never null: no match is an empty list.
| Property | Type | Required | Description |
|---|---|---|---|
type | "list" | yes | |
value | array of string | number | yes | The items, in input order. Empty when nothing matches. |
spans | array of SystemOneSpan | null | One entry per item, in the same order: the item's span, or null when the item was not read from the state text, for example when it was read from an image. Required for text items; for other items, present when they are read from the state text. | |
confidence | SystemOneProbability | yes | Confidence in the list, from 0 to 1. |
EstimateQuestion
A question answered with a distribution over a value the state gives evidence for but may not determine. min and max are both numbers or both dates.
| Property | Type | Required | Description |
|---|---|---|---|
type | "estimate" | yes | |
instructions | SystemOneInstructions | ||
unit | SystemOneUnitLabel | ||
min | SystemOneEstimateValue | yes | Lowest value the answer may take. |
max | SystemOneEstimateValue | yes | Highest value the answer may take. |
step | SystemOneStep | ||
scale | SystemOneScale | ||
quantiles | boolean | Whether the answer includes quantiles, the 1st to 99th percentiles. Defaults to false. |
EstimateAnswer
A distribution over the estimated value. Never null.
| Property | Type | Required | Description |
|---|---|---|---|
type | "estimate" | yes | |
quantiles | array of SystemOneEstimateValue | The 1st to 99th percentiles, in order. Present only when the question sets quantiles to true. |
ForecastQuestion
A question answered with an estimate for each of the next horizon steps of a series in the state. min, max, step, and scale apply to every step.
| Property | Type | Required | Description |
|---|---|---|---|
type | "forecast" | yes | |
instructions | SystemOneInstructions | ||
unit | SystemOneUnitLabel | ||
min | SystemOneEstimateValue | yes | Lowest value any step may take. |
max | SystemOneEstimateValue | yes | Highest value any step may take. |
step | SystemOneStep | ||
scale | SystemOneScale | ||
horizon | integer | yes | Number of steps to forecast. |
interval | "step" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year" | The time between steps of the series. step means one row of the series as given. |
ForecastAnswer
One estimate per step ahead, as a steps array.
| Property | Type | Required | Description |
|---|---|---|---|
type | "forecast" | yes | |
steps | array of SystemOneDistribution | yes | Exactly horizon estimates, nearest step first. Steps have no quantiles. |
ExtensionQuestion
A question of a non-core type named owner:type. Its other fields are defined by the owner.
| Property | Type | Required | Description |
|---|---|---|---|
type | SystemOneExtensionType | yes |
ExtensionAnswer
An answer to an extension question. Its other fields are defined by the owner of the type.
| Property | Type | Required | Description |
|---|---|---|---|
type | SystemOneExtensionType | yes |
SystemOneExtensionType
A non-core type name: a lowercase owner prefix, a colon, and a lowercase type name, such as acme:sentiment.
Type: string
SystemOneInstructions
What the answer should contain.
Type: SystemOneContent | null
SystemOneNullThreshold
The answer's value is null when p_null is above this threshold.
Type: number
SystemOneUnitLabel
The unit of the value, such as USD or kg. It describes the value; it does not convert it.
Type: string
SystemOneDurationUnit
The unit of a duration.
Type: "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years"
SystemOneInteger
Whether the value must be a whole number.
Type: boolean
SystemOneDecimals
Number of decimal places in the value, from 0 to 6.
Type: integer
SystemOneTime
A 24-hour time of day as HH:MM or HH:MM:SS.
Type: string
SystemOneDateTime
An ISO 8601 date and time, YYYY-MM-DDTHH:MM[:SS[.fraction]], with an optional Z or +HH:MM offset.
Type: string
SystemOneSpan
Where guess was read in the input: a half-open range [start, end) of character offsets, counted in Unicode code points, into state, or into the response's state_text when present.
Type: array of integer
SystemOneEstimateValue
An estimated value: a number, or a date as YYYY-MM-DD for date estimates.
Type: number | string
SystemOneStep
The grid estimates fall on, starting at min: a positive number (in days for date estimates), or month or year for date estimates.
Type: number | "month" | "year"
SystemOneScale
Whether the model spreads its distribution evenly between min and max (linear) or across orders of magnitude (log).
Type: "linear" | "log"
SystemOneDistribution
A predicted distribution, of the same kind as the question's min and max (numbers or dates). value, median, p10, and p90 are within [min, max] and on the step grid; p10 <= median <= p90.
| Property | Type | Required | Description |
|---|---|---|---|
value | SystemOneEstimateValue | yes | The point estimate. Never null. |
median | SystemOneEstimateValue | yes | The 50th percentile. |
p10 | SystemOneEstimateValue | yes | The 10th percentile, the low end of the 80% interval. |
p90 | SystemOneEstimateValue | yes | The 90th percentile, the high end of the 80% interval. |
mean | SystemOneEstimateValue | The mean, a date for date estimates. It may fall between grid points. | |
p_below | SystemOneProbability | Probability that the true value is below min. | |
p_above | SystemOneProbability | Probability that the true value is above max. |
SystemOneProbability
A probability or confidence from 0 to 1.
Type: number
SystemOneFraction
A fraction of an image dimension from 0 to 1.
Type: number
SystemOneErrorResponse
An error envelope.
| Property | Type | Required | Description |
|---|---|---|---|
error | SystemOneError | yes |
SystemOneError
An error. Two codes are standardized: unsupported_question_type, when the server does not support a question's type, and unsupported_parameter, when it cannot honor a request field or question setting. Both use type invalid_request_error and name the rejected field in param. Other codes are implementer-defined.
| Property | Type | Required | Description |
|---|---|---|---|
type | string | yes | The error category, such as invalid_request_error. |
code | string | null | yes | A machine-readable error code. |
param | string | null | yes | The request field that caused the error, as a path such as reference_date or questions.<name>.type. |
message | string | yes | A human-readable description of the error. |