Decisions (Beta)
System One
TypeSafe’s System One format for the Decisions API: send your application’s state and a map of typed questions, get calibrated probabilities back
POST
cURL
Overview
You send your application’sstate and a map of typed questions, and get a calibrated probability back under each question’s key. state is a string, a JSON object or a JSON array. Fields this endpoint doesn’t implement are ignored, not rejected.
A request to jev-1.13.0, clef, clef-flash, mercury-decide, elephant-1 or mammoth-1 reaches its provider as sent and its reply comes back as sent, with id, model and cost added. On mercury-decide, elephant-1 and mammoth-1, each image is read where its reference appears; see Images. A request to gemini-decision-1 is rewritten into Google’s dialect of this format: state goes as Google’s input (an object or array state as its JSON text), the noul criteria as true_description and false_description, and each question under an id of ours, with its answer returned under yours. Google reads instructions and criteria descriptions as text only, so a JSON object or array there is Google’s 400. A request to gpt-6-luna is translated into OpenAI’s format and the answers translated back. On OpenAI’s models lists what changes.
Question types
noul
A yes/no judgment. Returns a probability between 0 and 1 that the answer is yes. criteria is optional, and may carry true and false descriptions to sharpen the judgment.
choice
Selects one option from a required map of option name to description. Returns the chosen option, a probability distribution over all options, and a confidence value.
A description can be null when the option name is self-explanatory, for example { "shipping": null, "technical": null, "other": null }.
Option order can change the answer. Question ids and option names that are plain whole numbers, such as "10" and "2" (not "01", "-1" or "1.5"), are put in ascending numeric order ahead of the other names, whatever order you send them in, both on the way to the model and in the answers. If the order matters, use names that aren’t bare integers.
score
A position on ordered levels, described by a required array of one to ten level descriptions, ordered from lowest to highest. Returns a probability-weighted value, the levels as a legend, a distribution, and a confidence value.
box
Experimental. Finds one thing in an image and returns the four edges of a box around it, plus a confidence. A box question takes instructions only, no criteria, such as "the coffee mug in `photo`". It needs Jev 1.14 (jev-1.14.0 or jev-preview) and an image in the request; see Images for an example.
A box answer is always a box, even when the target isn’t in the image. Ask a noul question in the same request to check that the target is there, and ignore the box when that answer is low.
Images
List each image once inassets, under a reference string. Then write that reference wherever the image belongs: as a value in state, inside a question’s instructions, or in its criteria. Jev reads the image in its place. Images work on Jev 1.13 and 1.14, and on mercury-decide, elephant-1, mammoth-1 and gemini-decision-1. TypeSafe’s TypeSafe-Danger-Zone-Images header is added for you whenever a request has an image or a box question.
- References. A reference is matched as plain text anywhere in your strings, so a short one like
catwould also match insidecategory. Use one that can’t occur in your text by accident, such as a new UUID per image. Object keys, such as choice option names, are never replaced. Every image inassetsmust be referenced somewhere, or the request is a400. - Cost. Images are billed as input tokens at the normal rate, about 2 tokens per 28 × 28 pixel tile: roughly 850 for a 640 × 480 image and 6,300 for a 1568 × 1568 one. Every place a reference appears adds another copy of the image and is billed again, so when several questions use one image, put it in
stateonce and refer to it by name from each question. - Format. PNG or JPEG, still images only, sent as standard base64 with no
data:prefix. Multipart uploads aren’t supported. - Size. Each side 280 to 1568 pixels and each file up to 16 MiB. Images outside the limits are refused rather than resized, so scale them before you send them.
mercury-decide the cost, format and size rules above don’t apply: it reads PNG, JPEG, WEBP and GIF, up to 16 images of 10 MiB each, billed at about one token per 32 × 32 pixel patch. Each image takes the place of the first occurrence of its reference in state; one referenced only in a question, or nowhere, follows the state labelled Image "<reference>":. A box question is a 400 on every model but Jev 1.14.
On elephant-1 and mammoth-1 images are placed the same way as on mercury-decide. They read PNG, JPEG and WEBP, up to 16 images and 5.5 MB in all, billed at about one token per 32 × 32 pixel patch and at least 64 per image.
On gemini-decision-1 images are placed the same way as on mercury-decide. It reads PNG, JPEG and WEBP of any size within the request’s 50 MiB, billed at 1,089 tokens per image.
See TypeSafe’s Images and Box guides for the full rules and patterns.
Long context
A request is limited to 64k tokens in total, and 32k forstate plus any one question. To raise both limits to 262k tokens, send the TypeSafe-Danger-Zone-Long-Context: true header with the request. It costs the same per token, but it’s slower and less accurate than staying within the default limits, so send it only on requests that need it.
Answers
Each answer sits under its question’s key, and its shape depends on itstype.
- A
noulreturns{ "type": "noul", "noul": 0.87 }. The singlenoulfield is the probability of yes. - A
choicereturns{ "type": "choice", "choice": "shipping", "confidence": 0.91, "probabilities": { "shipping": 0.91, "technical": 0.06, "account": 0.03 } }. - A
scorereturns{ "type": "score", "score": 1.7, "confidence": 0.78, "legend": { "0": "Low: no action needed soon", "1": "Medium: should be addressed within a few days", "2": "High: needs a response today" }, "probabilities": { "0": 0.05, "1": 0.2, "2": 0.75 } }.legendmaps each level back to the description you supplied, so you can render the answer without holding onto the original request. - A
boxreturns{ "type": "box", "box": { "top": 0.08, "bottom": 0.94, "left": 0.12, "right": 0.88 }, "confidence": 0.9 }. Each edge is a fraction of the image’s height (top,bottom) or width (left,right), measured from its top-left corner. Multiply by the image’s size in pixels to draw or crop the box. - A
refusal,{ "type": "refusal" }, means the model couldn’t answer from the state. TypeSafe’s models never return one. See below.
confidence summarizes how concentrated the probability distribution is, not whether the chosen answer is correct. The option order you send can change the answer, on every model.
Fields TypeSafe adds beyond the documented schema reach you rather than being stripped, so allow for unknown fields on the response and on individual answers.
usage.output_tokens is the count TypeSafe reports. Output tokens aren’t charged. cost is in dollars, in the same shape the chat endpoints return.On OpenAI’s models
A request togpt-6-luna is translated to OpenAI’s format, which is narrower than TypeSafe’s, so a few things change on the way.
- A
statethat is an object or array is sent as its JSON text. Structuredinstructionsand descriptions are sent as JSON text too. noulcriteriabecome instruction text.True means: <your true criterion>is appended when you supplytrue, andFalse means: <your false criterion>when you supplyfalse. The question is asked as apredicate.choicecriteriakeys become the choice values, andnulldescriptions are omitted.scorecriteriabecome level labels. The answer’slegendstill carries your criteria as sent.- OpenAI requires 2 to 255 choices and 2 to 10 score levels. A request outside that is sent anyway, and OpenAI’s
400comes back in the error shape below. - Each image goes in the input right after the first place its reference appears in
state. An image referenced only in a question, or nowhere, follows the state labelledImage "<reference>":, so a question can name it by its reference.gpt-6-lunareads PNG, JPEG, WEBP and GIF. - The model may answer
{ "type": "refusal" }when the state can’t answer the question. - A
boxquestion is a400: OpenAI’s format has no box.
Errors
Errors take TypeSafe’s shape,{ "detail": { "error_type", "message" } }, so their SDK’s error handling works unchanged. error_type is the provider’s when it sent one (max_tokens_exceeded from TypeSafe, invalid_request_error from OpenAI), authentication_error for a missing or invalid key, as TypeSafe sends, else our error code. The statuses are those of /v1/decisions. A body compressed with Content-Encoding: gzip, x-gzip or zstd, as TypeSafe’s SDKs send it, is accepted; another encoding is a 415.
Keys with redaction enabled get a 400. Keys with ZDR or HIPAA mode enabled get a 422 for a provider that can’t meet the policy. A stored provider key works as BYOK does on the chat endpoints.
Models and aliases
gpt-6-luna, jev-1.13.0, jev-1.14.0, clef, clef-flash, mercury-decide, elephant-1, mammoth-1 and gemini-decision-1. jev-latest, jev and jev-1.13 resolve to jev-1.13.0, and jev-preview to jev-1.14.0. A provider/ prefix is accepted. One that isn’t a provider of the model is a 400.
Related Documentation
Decisions
The same models in OpenAI’s format, with images
Writing questions
TypeSafe’s guide to state, instructions and criteria
Jev 1.13 jaggedness
Known failure modes and what to do instead
Error Handling
Understand error responses across the API
Body
application/json
Last modified on November 12, 2026

