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 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.

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:

curl https://mixlayer.ai/v1/systemone \
  -H "Authorization: Bearer $MIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "mixlayer/jini-qwen3.8-27b",
  "state": {
    "delivery_note": "Received 9 of the 12 cable kits listed on the packing slip. We need the remaining kits before Friday."
  },
  "questions": {
    "missing_items": {
      "type": "noul",
      "instructions": "Does the delivery note report fewer items received than expected?",
      "criteria": {
        "true": "The received quantity is lower than the expected quantity.",
        "false": "No quantity shortfall is reported."
      }
    },
    "route": {
      "type": "choice",
      "instructions": "Which queue best matches the delivery note?",
      "criteria": {
        "inventory": "Missing items or incorrect quantities.",
        "shipping": "Transit delays or tracking questions.",
        "other": "Anything outside these categories."
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is resolving the issue?",
      "criteria": [
        "Routine: no deadline or operational impact is stated.",
        "Time-sensitive: a deadline is stated, but operations can continue.",
        "Critical: operations are already stopped."
      ]
    }
  }
}'

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:

{
  "model": "mixlayer/jini-qwen3.8-27b",
  "answers": {
    "missing_items": {"type": "noul", "noul": 0.95},
    "route": {
      "type": "choice",
      "choice": "inventory",
      "probabilities": {"inventory": 0.7, "shipping": 0.2, "other": 0.1},
      "confidence": 0.55
    },
    "urgency": {
      "type": "score",
      "score": 1.0,
      "legend": {
        "0": "Routine: no deadline or operational impact is stated.",
        "1": "Time-sensitive: a deadline is stated, but operations can continue.",
        "2": "Critical: operations are already stopped."
      },
      "probabilities": {"0": 0.1, "1": 0.8, "2": 0.1},
      "confidence": 0.7
    }
  },
  "usage": {"input_tokens": 180, "output_tokens": 0}
}

• Noul: noul is the conditional probability of yes versus no, from 0 to 1. It is a number, not a boolean.
• Choice: choice is the highest-probability option name. probabilities maps every option name to a probability and sums to one.
• Score: score is the probability-weighted average of zero-based level indices. legend maps those indices to rendered descriptions, and probabilities uses string keys such as "0" and "1".

See the SystemOne API reference for the full schema.

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:

curl https://mixlayer.ai/v1/decisions \
  -H "Authorization: Bearer $MIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "mixlayer/jini-qwen3.8-27b",
  "input": "Received 9 of the 12 cable kits listed on the packing slip. We need the remaining kits before Friday.",
  "questions": [
    {
      "type": "predicate",
      "name": "missing_items",
      "instructions": "Does the delivery note report fewer items received than expected?"
    },
    {
      "type": "choice",
      "name": "route",
      "instructions": "Which queue best matches the delivery note?",
      "choices": [
        {"value": "inventory", "description": "Missing items or incorrect quantities."},
        {"value": "shipping", "description": "Transit delays or tracking questions."},
        {"value": "other", "description": "Anything outside these categories."}
      ]
    },
    {
      "type": "score",
      "name": "urgency",
      "instructions": "How urgent is resolving the issue?",
      "levels": [
        {"label": "Routine", "description": "No deadline or operational impact is stated."},
        {"label": "Time-sensitive", "description": "A deadline is stated, but operations can continue."},
        {"label": "Critical", "description": "Operations are already stopped."}
      ]
    }
  ]
}'

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:

{
  "model": "mixlayer/jini-qwen3.8-27b",
  "answers": [
    {"type": "predicate", "name": "missing_items", "probability": 0.95},
    {
      "type": "choice",
      "name": "route",
      "choice": "inventory",
      "probabilities": [
        {"value": "inventory", "probability": 0.7},
        {"value": "shipping", "probability": 0.2},
        {"value": "other", "probability": 0.1}
      ],
      "confidence": 0.55
    },
    {
      "type": "score",
      "name": "urgency",
      "score": 1.0,
      "probabilities": [
        {"value": 0, "label": "Routine", "probability": 0.1},
        {"value": 1, "label": "Time-sensitive", "probability": 0.8},
        {"value": 2, "label": "Critical", "probability": 0.1}
      ],
      "confidence": 0.7
    }
  ],
  "usage": {
    "input_tokens": 180,
    "input_tokens_details": {"cached_tokens": 0, "cache_write_tokens": 0},
    "output_tokens": 0,
    "output_tokens_details": {"reasoning_tokens": 0},
    "total_tokens": 180
  }
}

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:

{
  "input": [
    {
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Expected quantity: 12 cable kits. "},
        {"type": "input_text", "text": "Received quantity: 9 cable kits."}
      ]
    }
  ]
}

This is an input-field example; include model and questions in the full request. Parts within a message are concatenated without added separators; separate messages are joined with two newlines. Add spaces or newlines to parts where needed. Only user messages are supported. Images, files, audio, other roles, and item references are rejected.

See the Decisions API reference for the full schema.

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.

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 request shapes, unsupported input, and exceeded validation limits return 422. 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 state or input, and describe the evaluation in instructions and the rubric.
• Use explicit options and levels. Give each category a distinct meaning; include an other option 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.