Skip to main content
POST
cURL
Beta Feature/v1/systemone takes TypeSafe’s System One format and answers in it, so a client written against TypeSafe’s API works here by changing the hostname. It serves the same models as /v1/decisions, which takes OpenAI’s format and is the one to build new code against.

Overview

You send your application’s state 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

Experimental. Images and box questions are TypeSafe’s experimental features. The request format, the answers and the limits can change between Jev releases, and accuracy changes as the models are updated. Use them for prototypes, not production paths.
List each image once in assets, 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 cat would also match inside category. 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 in assets must be referenced somewhere, or the request is a 400.
  • 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 state once 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.
On 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

Experimental. Long context is one of TypeSafe’s experimental features.
A request is limited to 64k tokens in total, and 32k for state 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 its type.
  • A noul returns { "type": "noul", "noul": 0.87 }. The single noul field is the probability of yes.
  • A choice returns { "type": "choice", "choice": "shipping", "confidence": 0.91, "probabilities": { "shipping": 0.91, "technical": 0.06, "account": 0.03 } }.
  • A score returns { "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 } }. legend maps each level back to the description you supplied, so you can render the answer without holding onto the original request.
  • A box returns { "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 to gpt-6-luna is translated to OpenAI’s format, which is narrower than TypeSafe’s, so a few things change on the way.
  • A state that is an object or array is sent as its JSON text. Structured instructions and descriptions are sent as JSON text too.
  • noul criteria become instruction text. True means: <your true criterion> is appended when you supply true, and False means: <your false criterion> when you supply false. The question is asked as a predicate.
  • choice criteria keys become the choice values, and null descriptions are omitted.
  • score criteria become level labels. The answer’s legend still 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 400 comes 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 labelled Image "<reference>":, so a question can name it by its reference. gpt-6-luna reads PNG, JPEG, WEBP and GIF.
  • The model may answer { "type": "refusal" } when the state can’t answer the question.
  • A box question is a 400: 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.

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
model
required

A model slug from /v1/models

state
required

The application state the questions are judged against: a string, a JSON object or a JSON array.

questions
object
required

Questions keyed by an id of your choosing; answers come back under the same ids. At least one.

assets
object

Images keyed by the reference string the state or questions use. Base64 only.

Response

Default Response

model
string
required

The model that answered, as provider/model.

answers
object
required

One answer per question, under the question's id.

usage
object
required
cost
object
required
id
string

The request id; the Response ID the logs page shows.

provider
string
{key}
any
Last modified on November 12, 2026