Decisions
Decisions evaluate content against questions you define and return typed answers: a probability that a condition holds, a choice from your options, or a score on an ordered rubric. Use them when your application needs a judgment it can act on directly, such as assigning a category or prioritizing a record.
Mixlayer exposes two decision endpoints. Both accept a classification model and multiple independent questions about shared content; neither generates output text.
Common use cases
- Routing: select a handler, queue, or workflow from a fixed set of options.
- Filtering: estimate whether a document meets a condition before processing it.
- Prioritization: score records against an explicit urgency or relevance rubric.
- Content review: evaluate separate policy conditions and combine the answers in your application’s logic.
Choose an endpoint
Choose SystemOne for compatibility with the TypeSafe System One API, supplying structured records and retrieving answers by key. Choose Decisions when integrating with the OpenAI Decisions request and response format. Compatibility describes the format; Mixlayer’s accepted inputs, limits, and scoring behavior are documented below.
Select a model
Use a classification model available to your organization. A generation or embedding model is not a substitute. Check the Mixlayer console or your organization’s model list for identifiers and model kinds.
The text examples use mixlayer/jini-qwen3.8-27b as the classification model and
$MIXLAYER_API_KEY for an API key with inference permission.
Set the API key environment variable before running the requests.
To run the image examples, set MIXLAYER_VISION_MODEL to a classification
model that lists image in its input_modalities.
SystemOne
Mixlayer’s SystemOne endpoint uses the same request and response format as TypeSafe’s System One API. Use the Mixlayer endpoint, API key, and model identifier shown below with your existing SystemOne request structure.
Send state and keyed questions
All three top-level fields, model, state, and questions, are required.
Each question needs type and instructions. This request evaluates a
delivery note for missing items, routing, and urgency:
state accepts a string, object, or array. Top-level numbers, booleans, and
null are rejected. instructions and rubric descriptions can themselves be
text, objects, arrays, or null; use clear text descriptions to start.
Read the answers
Answers use the same IDs as the request. An illustrative response is shown below; probabilities and token counts will vary:
- Noul:
noulis the conditional probability of yes versus no, from 0 to 1. It is a number, not a boolean. - Choice:
choiceis the highest-probability option name.probabilitiesmaps every option name to a probability and sums to one. - Score:
scoreis the probability-weighted average of zero-based level indices.legendmaps those indices to rendered descriptions, andprobabilitiesuses string keys such as"0"and"1".
See the SystemOne API reference for the full schema.
Upload images as assets
Use an assets map to attach still PNG or JPEG images. Refer to each asset by
its key in a string value in state, question instructions, or criteria.
Each image must be referenced at least once. JSON object keys stay as text.
This example uses jq and curl to upload a local delivery.png file.
Send the JSON as the first multipart field, named request with content type
application/json. The asset’s part names the corresponding file field.
For a JSON request, supply format (png, jpg, or jpeg) and
data_base64 in place of part. Use raw base64 in data_base64.
Each image edge must be 280–1,568 pixels.
OpenAI-compatible Decisions
Send input and ordered questions
The required fields are model, input, and questions. Here is the same
delivery-note task using the Decisions format:
name identifies an answer for your code and is echoed in the response. Omit it
to receive name: null. Put the complete evaluation instruction in
instructions; naming a question does not change its scoring.
Read the answers
The answers array preserves question order. An illustrative response:
Predicates return probability rather than SystemOne’s noul. Choice
probabilities preserve request option order, and the winning choice preserves
its original JSON type: boolean true and string "true" are different values.
Score probabilities preserve level order and include each level’s label and
zero-based index. Labels do not need to be unique.
User-message input
Instead of a string, input can be an array of messages with role: "user".
Each message’s content can be text or an array of input_text parts:
This is an input-field example; include model and questions in the full
request. Adjacent text parts are joined without added separators, and separate
messages are joined with two newlines. Add spaces or newlines where needed.
Only user messages are supported. File and audio parts, other roles, and item
references are rejected.
See the Decisions API reference for the full schema.
Send image and JSON parts
Use input_image alongside input_text and input_json parts in a user
message. Use the same part format in a question’s instructions to include
evidence for just that question. Set the data field of an input_json part
to the JSON value you want to include.
This example uses jq and curl. Set IMAGE_URL to an HTTPS URL Mixlayer
can fetch or a base64 data URL. Decisions accepts still PNG, JPEG, and WebP
images. The optional detail field accepts low, high, auto, and
original.
Interpret probabilities and scores
Questions are evaluated independently against the shared content. One question does not see another question’s answer. Combine independent results in your code; use a later request if a question depends on an earlier result.
Score levels start at 0, not 1. For three levels, a score is between 0 and 2
and can be fractional. Probabilities of 0.1, 0.8, and 0.1 yield
0 × 0.1 + 1 × 0.8 + 2 × 0.1 = 1.0. Use Choice when you need a single category.
Mixlayer’s Decisions endpoint scores choices and levels independently, then
normalizes conditional yes probabilities in log space. Choice confidence
measures the winning probability above a uniform baseline, rescaled to 0–1.
Score confidence measures concentration around the most probable level
relative to uniform spread.
Probabilities and confidence are not calibrated guarantees of correctness.
Set thresholds using labeled examples from your own workload. The Decisions
schema includes a refusal answer for compatibility, but the current scorer
does not produce refusals; refusal detection is not implemented.
Limits and usage
A Noul or Predicate question uses one branch. Each Choice option and each Score level uses a separate branch. The examples above use seven branches: one yes/no question, three choices, and three score levels. SystemOne question IDs must also be nonblank and at most 256 UTF-8 bytes.
Both endpoints count the shared input prefix once plus the input suffix for
every scoring branch. output_tokens is always zero. Decisions also returns
total_tokens, equal to input_tokens, and token-detail fields that currently
report zero cache and reasoning tokens. It does not return compute_units.
See Pricing for model rates.
Unknown request fields are rejected. Generation settings such as temperature,
max_tokens, and stream are not accepted. Decisions accepts
safety_identifier for compatibility but ignores it; authentication comes from
your bearer token.
Invalid JSON requests typically return 422. SystemOne can also return 400
for invalid image assets or multipart uploads and 413 for an oversized body.
Rate limits return 429; unavailable classification capacity or an
exceeded classification deadline can return 529. Error bodies use
error.code and error.message. See Credits & Limits for
general limits and retry guidance.
Best practices
- Define one judgment per question. Keep evidence in
stateorinput, and describe the evaluation ininstructionsand the rubric. - Use explicit options and levels. Give each category a distinct meaning;
include an
otheroption when your categories do not cover all inputs. - Group independent questions. Share the evidence in one request and stay within the total branch limit, which can be reached before the question limit.
- Check the distribution. A winning choice alone hides ambiguous results. Use probabilities and confidence to decide when to route for review.
- Evaluate before automating. Test your rubrics and thresholds on representative examples, including unclear cases and missing information.